SaveSemanticSnapshot- og ComputeSemanticHash-metoder

Skriver en versjonert kanonisk representasjon av arbeidsbokens semantikk til en strøm, eller beregner SHA-256 av nøyaktig de bytene

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;

Metodene eksponeres av Classic IXLSWorkbook og TXLSWorkbook i lxHandle og av TXLSXWorkbook i lxHandleX

Profil- og valgtypene er deklarert i lxSemanticSnapshot og er synlige gjennom begge arbeidsbokenhetene

Profiler

Valg

Valgsettet har type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption. Overbelastningene uten parametere bruker xlsspContent med et tomt valgsett

Regler for strøm og identitet

• SaveSemanticSnapshot skriver ved målstrømmens nåværende posisjon og utfører ikke søking, tar ikke eierskap til og frigjør ikke strømmen
• En nedstrøms skrivefeil kan etterlate et prefiks i målet, slik at de som kaller og krever atomær publisering, bør skrive til et midlertidig mål før målet erstattes
• ComputeSemanticHash returnerer 64 små heksadesimale tegn og beregner hashen trinnvis uten å tildele en komplett øyeblikksbildebuffer
• Øyeblikksbildet er en semantisk HotXLS-protokoll, ikke et XLS-, XLSX-, ODS-, CSV- eller PDF-dokument
• Sammenlign bare øyeblikksbilder eller hasher når protokollversjon, profil og valgsett stemmer overens
• Operasjonen lagrer ikke, beregner ikke på nytt, oppdaterer ikke koblinger, åpner ikke eksterne ressurser og muterer ikke arbeidsbokens buffere

Samtidighet og feil

Begge metodene holder et leselån på arbeidsboken gjennom hele gjennomløpet

En samtidig offentlig mutasjon mislykkes før arbeidsboktilstanden endres, med EXLSWorkbookWriteGuardUnavailable, mens en oppdaget generasjonsendring eller en ustøttet tvetydig semantisk struktur utlø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();

Snapshot-modellreferanse

Snapshot-motoren er ikke bundet til arbeidsbokobjekter: alt nedenfor er deklarert i lxSemanticSnapshot, og arbeidsbokmetodene er tynne innpakninger over de samme globale inngangspunktene

Utvidelsesgrensesnitt

Implementer IXLSSemanticWorkbookSource for å skrive ut eller hashe et snapshot av enhver kilde, og valgfritt IXLSSemanticFormulaResolver slik at utskrevne formler bærer oppløst informasjon om eksterne referanser og definerte navn

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;

Inne i WriteCommon er writeren et ugjennomsiktig håndtak: ikke kall dets primitive metoder — BeginContainer / EndContainer rammer en tagget beholder, og WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString og WriteBytes koder hver nøyaktig én kanonisk primitiv, med Finish som forsegler strømmen og Finished som rapporterer fullføring — send den tilbake til utdata-hjelpefunksjonene nedenfor, slik at hver produsent skriver identiske bytes

Globale inngangspunkter

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 fyller en stilpost med de kanoniske standardverdiene før individuelle felt redigeres; XLSBuiltinSemanticNumberFormat mapper en innebygd tallformat-id (under 164) til formatstrengen sin, som forbrukere trenger for å tolke utskrevne stiler og dekodede strømmer

Modellvokabular

Hjelpefunksjoner for utdata

Disse globale rutinene skriver ett modellfragment inn i writeren som sendes til WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition og XLSWriteSemanticFormulaCell (formelceller bærer matarisegrenser og et valgfritt bufret resultat). XLSWriteSemanticWorkbookCommon åpner arbeidsbokbeholderen og kaller WriteCommon, som egendefinerte kilder normalt kaller først

Se også

grensesnitt IXLSWorkbook · klasse TXLSXWorkbook · CreateReadOnlyView-metode