Métodos SaveSemanticSnapshot e ComputeSemanticHash

Transmite em fluxo uma representação canónica com versão da semântica do livro de trabalho ou calcula o SHA-256 de exatamente esses bytes

Sintaxe

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;

Os métodos são expostos pelo IXLSWorkbook e pelo TXLSWorkbook clássicos em lxHandle e pelo TXLSXWorkbook em lxHandleX

Os tipos de perfil e de opções são declarados em lxSemanticSnapshot e ficam visíveis através de ambas as unidades do livro de trabalho

Perfis

Opções

As sobrecargas sem parâmetros utilizam xlsspContent com um conjunto de opções vazio

Regras de fluxo e de identidade

• SaveSemanticSnapshot escreve na posição atual do fluxo de destino e não procura no fluxo, não assume a sua propriedade nem o liberta
• Uma falha de escrita a jusante pode deixar um prefixo no destino, pelo que os autores das chamadas que exijam publicação atómica devem escrever para um destino temporário antes de substituir o destino final
• ComputeSemanticHash devolve 64 caracteres hexadecimais minúsculos e calcula o hash incrementalmente sem alocar uma memória intermédia completa para o instantâneo
• O instantâneo é um protocolo semântico do HotXLS, não um documento XLS, XLSX, ODS, CSV nem PDF
• Compare instantâneos ou hashes apenas quando a versão do protocolo, o perfil e o conjunto de opções coincidirem
• A operação não guarda, não recalcula, não atualiza ligações, não acede a recursos externos e não modifica as caches do livro de trabalho

Concorrência e erros

Ambos os métodos mantêm uma concessão de leitura do livro de trabalho durante toda a travessia

Uma mutação pública concorrente falha antes de alterar o estado do livro de trabalho, com EXLSWorkbookWriteGuardUnavailable, enquanto uma alteração de geração detetada ou uma estrutura semântica ambígua não suportada gera EXLSSemanticSnapshot

Exemplo em 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;

Exemplo em C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Referência do modelo de instantâneos

O motor de instantâneos não está ligado a objetos do livro: tudo o que se segue está declarado em lxSemanticSnapshot, e os métodos do livro são wrappers finos sobre os mesmos pontos de entrada globais

Interfaces de extensão

Implemente IXLSSemanticWorkbookSource para emitir ou calcular o hash de um instantâneo de qualquer origem e, opcionalmente, IXLSSemanticFormulaResolver para que as fórmulas emitidas transportem informação resolvida de referências externas e de nomes definidos

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;

Dentro de WriteCommon, o escritor é um handle opaco: não chame os seus métodos primitivos — BeginContainer / EndContainer enquadram um contentor etiquetado e WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString e WriteBytes codificam cada um uma primitiva canónica, com Finish a selar o stream e Finished a reportar a conclusão — passe-o de volta para os auxiliares de emissão abaixo, para que todos os produtores emitam bytes idênticos

Globais de pontos de entrada

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 preenche um registo de estilo com as predefinições canónicas antes de os campos individuais serem editados; XLSBuiltinSemanticNumberFormat mapeia um id de formato de número incorporado (abaixo de 164) para a sua cadeia de formato, de que os consumidores precisam para interpretar estilos emitidos e streams descodificados

Vocabulário do modelo

Auxiliares de emissão

Estes globais escrevem um fragmento do modelo no escritor passado a WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition e XLSWriteSemanticFormulaCell (as células de fórmula transportam limites de matriz e um resultado em cache opcional). XLSWriteSemanticWorkbookCommon abre o contentor do livro e invoca WriteCommon, que as origens personalizadas normalmente chamam primeiro

Veja também

Interface IXLSWorkbook · Classe TXLSXWorkbook · Método CreateReadOnlyView