StgCreateDocfileOnILockBytes 函式 (coml2api.h)

StgCreateDocfileOnILockBytes 函式會在呼叫端提供的位元組數位物件上方建立並開啟新的複合檔儲存物件。 記憶體物件支援 IStorage 介面的 COM 提供複合文件實作。

語法

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

參數

[in] plkbyt

基礎位元組數位上 ILockBytes 介面的指標，要在其中建立複合檔案。

[in] grfMode

指定開啟新複合檔案時要使用的存取模式。 如需詳細資訊，請參閱下面的 STGM 常數 和一節。

[in] reserved

保留以備將來之用；必須為零。

[out] ppstgOpen

新儲存物件上 IStorage 指標位置的指標。

傳回值

StgCreateDocfileOnILockBytes 函式也可以傳回任何文件系統錯誤，或包裝在 HRESULT 中的系統錯誤，或 ILockBytes 介面錯誤傳回值。 如需詳細資訊，請參閱 錯誤處理策略 和 處理未知的錯誤。

備註

StgCreateDocfileOnILockBytes 函式會使用 IStorage 介面的 COM 提供的複合文件實作，在位元組數位物件之上建立儲存物件。 StgCreateDocfileOnILockBytes 可用來將檔儲存在任意數據存放區中，例如記憶體或關係資料庫。 位元組數位 (pLkbyt 參數表示，該參數指向物件上的 ILockBytes 介面，) 會用於基礎記憶體來取代磁碟檔案。

除了指定程式設計人員提供的 byte-array 物件之外， StgCreateDocfileOnILockBytes 類似於 StgCreateDocfile 函式。

根據 grfMode 參數中的存取模式開啟新建立的複合檔案，受限於下列限制：

共用模式行為和交易隔離取決於支援具有LOCK_ONLYONCE語意之LockRegion和UnlockRegion的ILockBytes實作。 實作可以透過在 STATSTG 的 grfLocksSupported 成員中設定 LOCK_ONLYONCE 位，以指示它們支援這項功能的結構化記憶體。 如果 ILockBytes 實作不支援這項功能，將不會強制執行共用模式，而且根層級交易認可不會與在同一個字節數位上開啟的其他交易實例正確協調。 使用不支援區域鎖定 之 ILockBytes 實作的應用程式，例如 CreateStreamOnHGlobal 實作，應該避免在相同的位元組數位上開啟多個並行實例。

StgCreateDocfileOnILockBytes 不支持簡單模式。 如果存在，則會忽略 STGM_SIMPLE 旗標。

為了進行轉換，檔案會被視為已經存在。 因此，使用 STGM_FAILIFTHERE 值並不實用，因為它會導致傳回錯誤。 不過，STGM_CREATE和STGM_CONVERT仍然很有用。

提供在位元組陣組物件之上建置複合檔案的能力，以支援在非持續性空間中，在 IStorage 和 IStream 樹狀結構下 (數據) 存留。 假設這項功能，沒有任何專案可防止儲存在檔案中的檔使用這項功能。 例如，容器可能會這麼做，以將採用 COM 所造成的檔格式影響降到最低。 不過，建議 COM 檔針對自己的外部層級記憶體採用 IStorage 介面。 這有下列優點：

• 當檔是內嵌物件時，檔的儲存結構與其儲存結構相同，減少應用程式需要處理的案例數目。
• 您可以撰寫工具來存取檔中的 OLE 內嵌和連結物件，而不需要特別瞭解檔的檔案格式。 這類工具的範例是複製公用程式，複製包含連結物件之容器中包含的所有檔。 這類複製公用程式需要存取包含的連結，以判斷要複製的檔案範圍。
• IStorage 實作解決了如何將變更認可至檔案的問題。 使用 ILockBytes 介面的應用程式必須自行處理這些問題。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 |UWP 應用程式]
目標平台	Windows
標頭	coml2api.h (包含 Objbase.h)
程式庫	Ole32.lib
Dll	Ole32.dll

另請參閱

StgCreateDocfile