SaveSemanticSnapshot- og ComputeSemanticHash-metoder

Streamer en versioneret, kanonisk repræsentation af projektbogens semantik eller beregner SHA-256 af præcis de bytes

Syntaks

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;

Metoderne eksponeres af Classic IXLSWorkbook og TXLSWorkbook i lxHandle og af TXLSXWorkbook i lxHandleX

Profil- og option-typerne er deklareret i lxSemanticSnapshot og er synlige via begge projektmappe-enheder

Profiler

Indstillinger

Optionsættet har typen TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption. Overloadene uden parametre bruger xlsspContent med et tomt optionsæt

Strøm- og identitetsregler

• SaveSemanticSnapshot skriver ved målstreamens aktuelle position og søger, ejer eller frigør ikke streamen
• En efterfølgende skrivefejl kan efterlade et præfiks i målet, så kaldere, der kræver atomar publicering, bør skrive til et midlertidigt mål, før destinationen erstattes
• ComputeSemanticHash returnerer 64 hexadecimaltegn med små bogstaver og hasher inkrementelt uden at allokere en komplet snapshot-buffer
• Snapshottet er en HotXLS-semantisk protokol, ikke et XLS-, XLSX-, ODS-, CSV- eller PDF-dokument
• Sammenlign kun snapshots eller hashes, når protokolversion, profil og optionsæt matcher
• Operationen gemmer ikke, genberegner ikke, opdaterer ikke links, tilgår ikke eksterne ressourcer og muterer ikke projektbogens caches

Samtidighed og fejl

Begge metoder holder en læse-lease på projektmappen under hele gennemløbet

En samtidig offentlig mutation fejler, før projektbogens tilstand ændres, med EXLSWorkbookWriteGuardUnavailable, mens en detekteret generationsændring eller en ikke-understøttet, tvetydig semantisk struktur udløser EXLSSemanticSnapshot

Delphi-eksempel

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-eksempel

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

WideString hash = workbook->ComputeSemanticHash();

Reference for snapshotmodellen

Snapshot-motoren er ikke bundet til projektmappe-objekter: alt nedenfor er deklareret i lxSemanticSnapshot, og projektmappe-metoderne er tynde wrappere over de samme globale indgangspunkter

Udvidelsesinterfaces

Implementér IXLSSemanticWorkbookSource for at emitte eller hashe et snapshot af enhver kilde og valgfrit IXLSSemanticFormulaResolver, så de emmitterede formler bærer opløst information om eksterne referencer og definerede navne

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;

Inde i WriteCommon er writeren et uigennemsigtigt handle: kald ikke dens primitive metoder — BeginContainer / EndContainer indrammer en tagget beholder, og WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString og WriteBytes encoder hver især én kanonisk primitiv, med Finish, der forsegler streamen, og Finished, der rapporterer fuldførelse — giv den tilbage til emissionshælperne nedenfor, så alle producenter emitterer identiske bytes

Globale indgangspunkter

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 udfylder en typografipost med de kanoniske standardværdier, før de enkelte felter redigeres; XLSBuiltinSemanticNumberFormat afbilleder et indbygget talformat-id (under 164) til dets formatstreng, hvilket forbrugere behøver for at fortolke emmitterede typografier og afkodede streams

Modelordforråd

Emissionshjælpere

Disse globale rutiner skriver én modelfragt ind i den writer, der gives til WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition og XLSWriteSemanticFormulaCell (formelceller bærer array-grænser og et valgfrit cached resultat). XLSWriteSemanticWorkbookCommon åbner projektmappe-beholderen og kalder WriteCommon, som brugerdefinerede kilder normalt kalder først

Se også

grænseflade IXLSWorkbook · klasse TXLSXWorkbook · CreateReadOnlyView metode