SaveSemanticSnapshot- en ComputeSemanticHash-methoden

Streamt een geversioneerde canonieke weergave van werkmapsemantiek of berekent de SHA-256 van precies die bytes

Syntaxis

procedure SaveSemanticSnapshot(AStream: TStream); overload;
procedure SaveSemanticSnapshot(AStream: TStream;
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions); overload;

function ComputeSemanticHash: WideString; overload;
function ComputeSemanticHash(
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions): WideString; overload;

De methoden worden aangeboden door klassiek IXLSWorkbook en TXLSWorkbook in lxHandle, en door TXLSXWorkbook in lxHandleX

De profiel- en optietypes worden gedeclareerd in lxSemanticSnapshot en zijn zichtbaar via beide werkmapunits

Profielen

Opties

De optieverzameling heeft het type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption. De overloads zonder parameters gebruiken xlsspContent met een lege optieverzameling

Streaming- en identiteitsregels

• SaveSemanticSnapshot schrijft op de huidige positie van de doelstream en zoekt de stream niet door, is er geen eigenaar van en geeft deze niet vrij
• Een schrijffout stroomafwaarts kan een voorvoegsel in het doel achterlaten, dus aanroepers die atomaire publicatie vereisen schrijven eerst naar een tijdelijk doel voordat ze de bestemming vervangen
• ComputeSemanticHash geeft 64 kleine hexadecimale tekens terug en hasht incrementeel zonder een volledige momentopnamebuffer toe te wijzen
• De momentopname is een semantisch HotXLS-protocol, geen XLS-, XLSX-, ODS-, CSV- of PDF-document
• Vergelijk momentopnames of hashes alleen wanneer protocolversie, profiel en optieverzameling overeenkomen
• De bewerking slaat niet op, herberekent niet, vernieuwt geen koppelingen, benadert geen externe bronnen en muteert geen werkmapcaches

Moderne celfeatures

TXLSSemanticCellStyle.CellControlKind heeft type TXLSSemanticCellControlKind met xlssControlNone, xlssControlUnknown en xlssControlCheckbox; CellControlDefaultState heeft type TXLSSemanticCheckboxDefaultState met xlssCheckboxUnchecked, xlssCheckboxChecked en xlssCheckboxBlank

XLSX-stijllezingen herleiden directe en overgeërfde controls zonder cellen te maken; canonieke stijlserialisatie wijst xlssControlUnknown af in plaats van een onbekende property bag als gewone cel te behandelen

Snapshots en hashes omvatten genormaliseerde effectieve control-rechthoeken, waarbij aangrenzende gelijke gebieden worden samengevoegd zonder hele kolommen naar cellen uit te schrijven; niet-gerelateerde niet-standaard stijloverlays behouden hun bestaande niet-ondersteunde normalisatiegrens

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) geeft losse entries terug, gesleuteld op celadres, inclusief exacte gecodeerde PNG- of JPEG-bytes, contenttype, alternatieve tekst en decoratieve metadata; quota's dekken canonieke bytes en image-entries, en te grote payloads worden geweigerd vóór het kopiëren

Werkmapvergelijking omvat deze imagedefinities wanneer lcoDrawings is geselecteerd, terwijl lcoCellStyles en lcoBlankStyleRegions effectieve Checkbox-formaten omvatten; alleen overeenkomende fallback-fouten maken verschillende afbeeldingen niet gelijk

Onbekende rich-value-image-grafieken geven EXLSSemanticSnapshot tijdens geselecteerde featurevergelijking of snapshot-doorkruising; deze operaties behouden de leeslease van de werkmap en berekenen geïnspecteerde cellen niet

Concurrency en fouten

Beide methoden houden een leeslease van de werkmap vast voor de volledige doorkruising

Een gelijktijdige openbare mutatie faalt voordat de werkmapstatus wordt gewijzigd, met EXLSWorkbookWriteGuardUnavailable, terwijl een gedetecteerde generatiewijziging of een niet-ondersteunde dubbelzinnige semantische structuur EXLSSemanticSnapshot

Delphi-voorbeeld

var
  Snapshot: TFileStream;
  Hash: WideString;
begin
  Snapshot:= TFileStream.Create('workbook.semantic', fmCreate);
  try
    Workbook.SaveSemanticSnapshot(Snapshot,
      xlsspSecurityComplete,
      [xlssoIncludeFormulaCachedResults]);
  finally
    Snapshot.Free;
  end;

  Hash:= Workbook.ComputeSemanticHash;

C++Builder-voorbeeld

TFileStream *snapshot = new TFileStream(
  L"workbook.semantic", fmCreate);
try
{
  workbook->SaveSemanticSnapshot(snapshot);
}
__finally
{
  delete snapshot;
}

WideString hash = workbook->ComputeSemanticHash();

Referentiemodel van de snapshot

De snapshot-engine is niet gebonden aan werkmapobjecten: alles hieronder is gedeclareerd in lxSemanticSnapshot, en de werkmapmethoden zijn dunne wrappers rond dezelfde globale toegangspunten

Extensie-interfaces

Implementeer IXLSSemanticWorkbookSource om een snapshot van een willekeurige bron weg te schrijven of te hashen, en optioneel IXLSSemanticFormulaResolver zodat weggeschreven formules herleide informatie over externe verwijzingen en gedefinieerde namen meedragen

IXLSSemanticWorkbookSource = interface
  procedure WriteCommon(AWriter: TXLSSemanticCanonicalWriter);
end;

IXLSSemanticFormulaResolver = interface
  function ResolveFormulaReference(AExternID: Integer;
    out AInfo: TXLSSemanticFormulaReferenceInfo): Boolean;
  function ResolveFormulaName(ANameID, AExternID: Integer;
    out AInfo: TXLSSemanticFormulaNameInfo): Boolean;
end;

TXLSSemanticFormulaReferenceInfo = record
  LinkKind: TXLSSemanticFormulaLinkKind;
  BookName: WideString;
  FirstSheetName: WideString;
  LastSheetName: WideString;
end;

TXLSSemanticFormulaNameInfo = record
  NameKind: TXLSSemanticFormulaNameKind;
  LinkKind: TXLSSemanticFormulaLinkKind;
  Name: WideString;
  ScopeSheetName: WideString;
  BookName: WideString;
end;

Binnen WriteCommon is de writer een ondoorzichtig handle: roep de primitieve methoden ervan niet zelf aan — BeginContainer / EndContainer kaderen een getagde container en WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideStringen WriteBytes coderen elk precies één canonieke primitief, met Finish die de stream afsluit en Finished die voltooiing rapporteert — geef het handle in plaats daarvan door aan de emission-helpers hieronder, zodat elke producent identieke bytes schrijft

Globale toegangspunten

procedure XLSSaveSemanticSnapshot(AStream: TStream;
  const ASource: IXLSSemanticWorkbookSource;
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions);
function XLSComputeSemanticHash(
  const ASource: IXLSSemanticWorkbookSource;
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions): WideString;
procedure XLSInitializeSemanticCellStyle(out AStyle: TXLSSemanticCellStyle);
function XLSBuiltinSemanticNumberFormat(AId: Word): WideString;

XLSInitializeSemanticCellStyle vult een stylerecord met de canonieke standaardwaarden voordat individuele velden worden bewerkt; XLSBuiltinSemanticNumberFormat wijst een ingebouwd getalnotatie-id (onder 164) toe aan zijn notatiestring, die consumenten nodig hebben om weggeschreven stijlen en gedecodeerde streams te interpreteren

Modelwoordenschat

Emission-helpers

Deze globals schrijven één modelfragment weg naar de writer die aan WriteCommonwordt doorgegeven: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitionen XLSWriteSemanticFormulaCell (formulecellen dragen arraygrenzen en een optioneel gecacht resultaat). XLSWriteSemanticWorkbookCommon opent de werkmapcontainer en roept WriteCommonaan, wat aangepaste bronnen normaal als eerste aanroepen

Zie ook

IXLSWorkbook-interface · TXLSXWorkbook-klasse · CreateReadOnlyView-methode