StgOpenStorageOnILockBytes 函式 (coml2api.h)

StgOpenStorageOnILockBytes 函式會開啟不存在於磁碟檔案中的現有儲存物件，而是具有呼叫端所提供的基礎位元組陣列。

語法

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

參數

[in] plkbyt

基礎位元組數位物件的ILockBytes指標，其中包含要開啟的儲存物件。

[in] pstgPriority

應為 NULL 的 IStorage 介面指標。 如果不是 NULL，則會如一節中所述使用此參數。

在 StgOpenStorageOnILockBytes 傳回之後，pStgPriority 中指定的儲存物件可能已釋放，且不應再使用。

[in] grfMode

指定要用來開啟記憶體物件的存取模式。 如需詳細資訊，請參閱下面的 STGM 常數 和一節。

[in] snbExclude

可以是 NULL。 如果不是 NULL，此參數會指向此記憶體中要排除的元素區塊，因為記憶體物件已開啟。 這個排除項目會獨立於快照集復本是否在開啟時發生。

[in] reserved

表示保留供日後使用;必須是零。

[out] ppstgOpen

指向成功傳回時開啟之記憶體的 IStorage 指標位置。

傳回值

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

備註

StgOpenStorageOnILockBytes 會開啟指定的根記憶體物件。 開啟儲存物件上 IStorage 介面的指標會透過 ppstgOpen 參數提供。

儲存物件之前必須由 StgCreateDocfileOnILockBytes 函式建立。

除了指定程式設計人員提供的位元組數位物件之外， StgOpenStorageOnILockBytes 類似於 StgOpenStorage 函式。 記憶體物件會根據 grfMode 參數中的存取模式開啟，但受限於下列限制：

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

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

pStgPriority 參數是為了方便呼叫端取代現有儲存物件，通常是在優先順序模式中開啟，並在相同位元組陣列上開啟的新儲存物件。 不同於 StgOpenStorage 的 pStgPriority 參數，此參數不會影響 StgOpenStorageOnILockBytes 所執行的開啟作業，而且只是呼叫端想要釋放的現有記憶體物件。 呼叫端應該一律傳遞此參數的 NULL ，因為 StgOpenStorageOnILockBytes 在某些情況下會釋放物件，而不會在其他情況下釋放它。 呼叫端可以改為在呼叫 StgOpenStorageOnILockBytes 之前釋放物件，以更安全的方式複製 pStgPriority 參數的使用，如下列範例所示：

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
    

如需詳細資訊，請參閱 StgOpenStorage。

規格需求

另請參閱

StgCreateDocfileOnILockBytes

StgOpenStorage