Методи SaveSemanticSnapshot и ComputeSemanticHash

Записва в поток версионирана канонична репрезентация на семантиката на работната книга или изчислява SHA-256 на точно тези байтове

Синтаксис

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;

Методите се разкриват от Classic IXLSWorkbook и TXLSWorkbook в lxHandle и от TXLSXWorkbook в lxHandleX

Типовете за профил и опции са декларирани в lxSemanticSnapshot и са видими и през двете единици за работни книги

Профили

Опции

Претоварванията без параметри използват xlsspContent с празен набор опции

Правила за потока и идентичността

• SaveSemanticSnapshot записва на текущата позиция на целевия поток и не изпълнява seek, не става собственик и не освобождава потока
• Неуспешен запис надолу по веригата може да остави префикс в целта, така че извикващите, които изискват атомарно публикуване, трябва да записват във временна цел, преди да заменят местоназначението
• ComputeSemanticHash връща 64 малки шестнадесетични знака и изчислява хеша инкрементално, без да заделя пълен буфер за снимката
• Снимката е семантичен протокол на HotXLS, а не документ XLS, XLSX, ODS, CSV или PDF
• Сравнявайте снимки или хешове само когато версията на протокола, профилът и наборът опции съвпадат
• Операцията не записва, не преизчислява, не обновява връзки, не достъпва външни ресурси и не мутира кешове на работната книга

Едновременност и грешки

И двата метода задържат lease за четене на работната книга за цялото обхождане

Едновременна публична мутация се проваля преди промяна на състоянието на работната книга с EXLSWorkbookWriteGuardUnavailable, докато открита промяна на поколението или неподдържана двусмислена семантична структура повдига EXLSSemanticSnapshot

Пример за 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;

Пример за C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Референция на модела на снимката

Двигателят на снимките не е обвързан с обектите на работната книга: всичко по-долу е декларирано в lxSemanticSnapshot, а методите на работната книга са тънки обвивки около същите глобални входни точки

Интерфейси за разширение

Имплементирайте IXLSSemanticWorkbookSource, за да изведете или хеширате снимка на всеки източник, и по избор IXLSSemanticFormulaResolver, така че изведените формули да носят разрешена информация за външни препратки и дефинирани имена

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;

Вътре в WriteCommon писателят е непрозрачна дръжка: не извиквайте неговите примитивни методи — BeginContainer / EndContainer очертават маркиран контейнер, а WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString и WriteBytes кодират по един каноничен примитив, като Finish запечатва потока, а Finished докладва завършването — подайте го обратно в помощниците за извеждане по-долу, така че всеки производител да извежда еднакви байтове

Глобални входни точки

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 запълва записа за стил с каноничните стойности по подразбиране, преди да редактирате отделни полета; XLSBuiltinSemanticNumberFormat преобразува вграден идентификатор на числов формат (под 164) в неговия форматен низ — това им трябва на консументите, за да тълкуват изведените стилове и декодираните потоци

Речник на модела

Помощници за извеждане

Тези глобални функции записват един фрагмент от модела в писателя, подаден на WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition и XLSWriteSemanticFormulaCell (клетките с формули носят граници на масив и незадължителен кеширан резултат). XLSWriteSemanticWorkbookCommon отваря контейнера на работната книга и извиква WriteCommon, който персонализираните източници обикновено извикват първи

Вижте също

Интерфейс IXLSWorkbook · Клас TXLSXWorkbook · Метод CreateReadOnlyView