SaveSemanticSnapshot and ComputeSemanticHash methods

Streams a versioned canonical representation of workbook semantics, or computes the SHA-256 of exactly those bytes

Syntax

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;

The methods are exposed by Classic IXLSWorkbook and TXLSWorkbook in lxHandle, and by TXLSXWorkbook in lxHandleX

The profile and option types are declared in lxSemanticSnapshot and are visible through both workbook units

Profiles

Options

The option set has type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionThe parameterless overloads use xlsspContent with an empty option set

Streaming and identity rules

• SaveSemanticSnapshot writes at the target stream's current position and does not seek, own or free the stream
• A downstream write failure can leave a prefix in the target, so callers that require atomic publication should write to a temporary target before replacing the final destination
• ComputeSemanticHash returns 64 lowercase hexadecimal characters and hashes incrementally without allocating an entire snapshot buffer
• The snapshot is a HotXLS semantic protocol, not an XLS, XLSX, ODS, CSV or PDF document
• Compare snapshots or hashes only when the protocol version, profile and option set match
• The operation does not save, recalculate, refresh links, access external resources or mutate workbook caches

Modern cell features

TXLSSemanticCellStyle.CellControlKind has type TXLSSemanticCellControlKind with xlssControlNone, xlssControlUnknown and xlssControlCheckbox; CellControlDefaultState has type TXLSSemanticCheckboxDefaultState with xlssCheckboxUnchecked, xlssCheckboxChecked and xlssCheckboxBlank

XLSX style reads resolve direct and inherited controls without creating cells; canonical style serialisation rejects xlssControlUnknown instead of treating an unknown property bag as a plain cell

Snapshots and hashes include normalised effective control rectangles, merging adjacent equal regions without expanding whole columns into cells; unrelated non-default style overlays retain their existing unsupported-normalisation boundary

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) returns detached entries keyed by cell address, including the exact encoded PNG or JPEG bytes, content type, alternative text and decorative metadata; quotas cover canonical bytes and image entries, and oversized payloads are rejected before any copying

Workbook comparison includes these image definitions when lcoDrawings is selected, whilst lcoCellStyles and lcoBlankStyleRegions include effective Checkbox formats; matching fallback errors on their own do not make distinct images equal

Unknown rich-value image graphs raise EXLSSemanticSnapshot during selected feature comparison or snapshot traversal; these operations hold the workbook read lease and never calculate inspected cells

Concurrency and errors

Both methods hold a workbook read lease for the complete traversal

A concurrent public mutation fails before changing workbook state with EXLSWorkbookWriteGuardUnavailable, whilst a detected generation change or unsupported ambiguous semantic structure raises EXLSSemanticSnapshot

Delphi example

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 example

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

WideString hash = workbook->ComputeSemanticHash();

Snapshot model reference

The snapshot engine is not tied to workbook objects; everything below is declared in lxSemanticSnapshot, and the workbook methods are thin wrappers over the same global entry points

Extension interfaces

Implement IXLSSemanticWorkbookSource to emit or hash a snapshot of any source, and optionally IXLSSemanticFormulaResolver so that emitted formulas carry resolved external-reference and defined-name information

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;

Inside WriteCommon the writer is an opaque handle: do not call its primitive methods — BeginContainer / EndContainer frame a tagged container and WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString, and WriteBytes encode one canonical primitive each, with Finish sealing the stream and Finished reporting completion — pass it back into the emission helpers below so that every producer emits identical bytes

Entry-point globals

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 fills a style record with the canonical defaults before the individual fields are edited; XLSBuiltinSemanticNumberFormat maps a builtin number-format id (below 164) to its format string, which consumers need in order to interpret emitted styles and decoded streams

Model vocabulary

Emission helpers

These globals write one model fragment into the writer passed to WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition, and XLSWriteSemanticFormulaCell (formula cells carry array bounds and an optional cached result). XLSWriteSemanticWorkbookCommon opens the workbook container and invokes WriteCommon, which custom sources normally call first

See also

IXLSWorkbook Interface · TXLSXWorkbook class · CreateReadOnlyView method