เมธอด 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
• เปรียบเทียบสแนปช็อตหรือแฮชเฉพาะเมื่อเวอร์ชันโปรโตคอล โปรไฟล์ และชุดตัวเลือกตรงกัน
• การดำเนินการไม่บันทึก ไม่คำนวณใหม่ ไม่รีเฟรชลิงก์ ไม่เข้าถึงทรัพยากรภายนอก และไม่แก้ไขแคชของสมุดงาน

การทำงานพร้อมกันและข้อผิดพลาด

ทั้งสองเมธอดถือสัญญาเช่าการอ่านของสมุดงานตลอดการไล่ผ่านทั้งหมด

การกลายสภาพสาธารณะพร้อมกันจะล้มเหลวก่อนเปลี่ยนสถานะสมุดงานด้วย 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 ไม่ผูกติดกับออบเจกต์สมุดงาน ทุกอย่างด้านล่างนี้ประกาศไว้ใน lxSemanticSnapshot และเมธอดของสมุดงานเป็นแค่ wrapper บาง ๆ ครอบ entry point ระดับ global ชุดเดียวกัน

Extension interfaces

implement IXLSSemanticWorkbookSource เพื่อ emit หรือ hash snapshot ของแหล่งข้อมูลใดก็ได้ และถ้าต้องการให้ implement IXLSSemanticFormulaResolver เพิ่มด้วย สูตรที่ emit จะระบุข้อมูล external reference กับ defined name ที่ resolve แล้ว

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 ตัว writer เป็น opaque handle อย่าเรียกเมธอด primitive ของมันตรง ๆ — BeginContainer / EndContainer ครอบ container แบบมีแท็ก ส่วน WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString และ WriteBytes encode primitive แบบ canonical หนึ่งค่าต่อหนึ่งเมธอด โดย Finish ปิดสตรีมและ Finished รายงานความสำเร็จ — ให้ส่ง handle นี้กลับเข้า emission helpers ด้านล่าง เพื่อให้ทุก producer emit ไบต์ชุดเดียวกัน

Entry point ระดับ global

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 เติม style record ด้วยค่าเริ่มต้นแบบ canonical ก่อนแก้ฟิลด์แต่ละตัว, XLSBuiltinSemanticNumberFormat แมป id ของ number format ในตัว (ต่ำกว่า 164) ไปเป็นสตริงฟอร์แมต ซึ่งผู้บริโภคต้องใช้ตีความสไตล์และสตรีมที่ถอดรหัสแล้ว

คำศัพท์ของโมเดล

Emission helpers

global เหล่านี้เขียนส่วนหนึ่งของโมเดลลง writer ที่ส่งให้ WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition และ XLSWriteSemanticFormulaCell (เซลล์สูตรระบุขอบเขต array กับผลลัพธ์แคชที่ใส่หรือไม่ก็ได้) ส่วน XLSWriteSemanticWorkbookCommon เปิด container ของสมุดงานแล้วเรียก WriteCommon ซึ่งแหล่งข้อมูลแบบกำหนดเองปกติจะเรียกเป็นอันดับแรก

ดูเพิ่มเติม

อินเทอร์เฟซ IXLSWorkbook · คลาส TXLSXWorkbook · เมธอด CreateReadOnlyView