متدهای 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;

این متدها توسط IXLSWorkbook و TXLSWorkbook کلاسیک در lxHandle و توسط TXLSXWorkbook در lxHandleX در معرض دید قرار می‌گیرند

نوع‌های پروفایل و گزینه در lxSemanticSnapshot تعریف شده‌اند و از طریق هر دو واحد کتاب کار دیده می‌شوند

پروفایل‌ها

گزینه‌ها

نسخه‌های سربارگذاری‌شده بدون پارامتر از xlsspContent با مجموعه گزینه خالی استفاده می‌کنند

قواعد جریان و هویت

• SaveSemanticSnapshot در موقعیت جاری جریان هدف می‌نویسد و جست‌وجو (seek) انجام نمی‌دهد، مالک جریان نمی‌شود و آن را آزاد نمی‌کند
• شکست نوشتن در پایین‌دست می‌تواند پیشوندی در هدف باقی بگذارد، بنابراین فراخواننده‌هایی که انتشار اتمی می‌خواهند باید پیش از جایگزینی مقصد، در هدفی موقت بنویسند
• ComputeSemanticHash مقدار 64 نویسهٔ شانزده‌دهی کوچک را برمی‌گرداند و هش را به‌صورت افزایشی بدون تخصیص بافر کامل تصویر لحظه‌ای محاسبه می‌کند
• تصویر لحظه‌ای یک پروتکل معنایی HotXLS است، نه سند XLS، XLSX، ODS، CSV یا PDF
• تصاویر لحظه‌ای یا هش‌ها را تنها زمانی مقایسه کنید که نسخه پروتکل، پروفایل و مجموعه گزینه مطابق باشند
• عملیات ذخیره نمی‌کند، محاسبه مجدد نمی‌کند، پیوندها را تازه نمی‌کند، به منابع خارجی دسترسی نمی‌یابد و حافظه‌های پنهان کتاب کار را جهش نمی‌دهد

همزمانی و خطاها

هر دو متد در تمام پیمایش، اجارهٔ خواندن کتاب کار را نگه می‌دارند

جهش عمومی همزمان پیش از تغییر وضعیت کتاب کار با 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();

مرجع مدل snapshot

رابط‌های افزونه

برای تولید یا هش کردن یک snapshot از هر منبعی، 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 هر کدام یک primitive کانونی را کدگذاری می‌کنند، 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