Metody SaveSemanticSnapshot a ComputeSemanticHash

Streamuje verzovanou kanonickou reprezentaci sémantiky sešitu nebo vypočte SHA-256 přesně těchto bajtů

Syntaxe

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;

Metody zpřístupňují klasické IXLSWorkbook a TXLSWorkbook v lxHandle a TXLSXWorkbook v lxHandleX

Typy profilu a možností jsou deklarovány v lxSemanticSnapshot a jsou viditelné přes obě jednotky sešitu

Profily

Možnosti

Přetížení bez parametrů používají xlsspContent s prázdnou sadou možností

Pravidla streamování a identity

• SaveSemanticSnapshot zapisuje na aktuální pozici cílového datového proudu a neposouvá se, nevlastní ho a neuvolňuje ho
• Selhání zápisu po proudu může v cíli zanechat úvodní část, takže volající vyžadující atomické publikování by měli nejprve zapisovat do dočasného cíle a teprve potom nahradit konečný cíl
• ComputeSemanticHash vrací 64 malých šestnáctkových znaků a počítá hash přírůstkově bez přidělení úplné vyrovnávací paměti snímku
• Snímek je sémantický protokol HotXLS, nikoli dokument XLS, XLSX, ODS, CSV ani PDF
• Porovnávejte snímky nebo hashe jen tehdy, když se shodují verze protokolu, profil i sada možností
• Operace neukládá, nepřepočítává, neaktualizuje odkazy, nepřistupuje k externím prostředkům a nemění mezipaměti sešitu

Souběžnost a chyby

Obě metody po celou dobu průchodu drží pronájem čtení sešitu

Souběžná veřejná mutace selže s EXLSWorkbookWriteGuardUnavailable dříve, než se změní stav sešitu, zatímco zjištěná změna generace nebo nepodporovaná nejednoznačná sémantická struktura vyvolá EXLSSemanticSnapshot

Příklad pro Delphi

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;

Příklad pro C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Reference modelu snapshotu

Snapshot engine není vázaný na objekty sešitu: vše níže je deklarováno v lxSemanticSnapshot a metody sešitu jsou tenké obálky nad týmitž globálními vstupními body

Rozhraní rozšíření

Implementujte IXLSSemanticWorkbookSource, chcete-li emitovat či hashovat snapshot libovolného zdroje, a volitelně IXLSSemanticFormulaResolver, aby emitované vzorce nesly rozřešené informace o externích referencích a definovaných názvech

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;

Uvnitř WriteCommon je writer neprůhledný handle: nevolejte jeho primitivní metody — BeginContainer / EndContainer orámují tagovaný kontejner a WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString a WriteBytes kódují po jedné kanonické primitivě, přičemž Finish zapečetí stream a Finished hlásí dokončení — předávejte jej zpět do emisních helperů níže, aby každý producent emitoval identické bajty

Globální vstupní body

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 vyplní záznam stylu kanonickými defaults před úpravou jednotlivých polí; XLSBuiltinSemanticNumberFormat namapuje id vestavěného formátu čísel (pod 164) na jeho formátovací řetězec, který konzumenti potřebují k interpretaci emitovaných stylů a dekódovaných streamů

Slovník modelu

Emisní helpery

Tyto globální funkce zapisují jeden fragment modelu do writeru předaného do WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition a XLSWriteSemanticFormulaCell (buňky se vzorci nesou hranice pole a volitelný cacheovaný výsledek). XLSWriteSemanticWorkbookCommon otevře kontejner sešitu a zavolá WriteCommon, kterou vlastní zdroje obvykle volají jako první

Viz také

Rozhraní IXLSWorkbook · Třída TXLSXWorkbook · Metoda CreateReadOnlyView