Share via

StgOpenStorage 函式 (coml2api.h)

  • 發行項

StgOpenStorage 函式會在文件系統中開啟現有的根記憶體物件。 使用此函式開啟複合檔案。 請勿使用它來開啟目錄、檔案或摘要目錄。 巢狀儲存物件只能使用其父 IStorage：：OpenStorage 方法開啟。

注意 應用程式應該使用新的函式 StgOpenStorageEx，而不是 StgOpenStorage，以利用增強型和 Windows 結構化記憶體功能。 此函式 StgOpenStorage 仍存在，以與 Windows 2000 上執行的應用程式相容。
 

語法

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

參數

[in] pwcsName

包含要開啟之記憶體物件的 Null 終止 Unicode 字串檔案路徑指標。 如果 pstgPriority 參數不是 NULL，則會忽略此參數。

[in] pstgPriority

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

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

[in] grfMode

指定要用來開啟記憶體物件的存取模式。

[in] snbExclude

如果不是 NULL，則表示要排除記憶體中元素區塊的指標，因為記憶體物件已開啟。 不論快照集復本是否在開啟時發生，都會發生排除。 可以是 NULL。

[in] reserved

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

[out] ppstgOpen

IStorage* 指標變數的指標，可接收已開啟之記憶體的介面指標。

傳回值

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

備註

StgOpenStorage 函式會根據 grfMode 參數中的存取模式開啟指定的根記憶體物件，如果成功，則會提供 IStorage 指標給 ppstgOpen 參數中開啟的儲存物件。

為了支援儲存沒有子記憶體對象的簡單模式， StgOpenStorage 函式接受下列兩個旗標組合中的其中一個作為 grfMode 參數中的有效模式。

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

為了支援單一寫入器、多線程、直接模式，第一個旗標組合是寫入器的有效 grfMode 參數。 第二個旗標組合對讀取器有效。

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

在直接模式中，下列三種組合之一是有效的。

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE
注意 在讀取/寫入模式中開啟記憶體物件而不拒絕其他人的寫入許可權， (grfMode 參數指定STGM_SHARE_DENY_WRITE) 可能是耗时的作业，因為 StgOpenStorage 呼叫必須建立整個儲存器物件的快照集。
 
應用程式通常會嘗試使用下列訪問許可權來開啟記憶體物件。 如果應用程式成功，就不需要建立快照集復本。 
STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

如果先前的訪問許可權失敗，應用程式可以使用許可權還原成快照集復本。 應用程式應該會在進行耗時的復本之前提示使用者。

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition

如果存取模式所隱含的檔共用語意適當，應用程式可能會嘗試開啟記憶體，如下所示。 在此情況下，如果應用程式成功，快照集復本將不會 (，因為已指定 STGM_SHARE_DENY_WRITE ，因此拒絕其他人的寫入存取權) 。

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition
注意 為了降低建立快照集複製的成本，應用程式可以在優先順序模式中開啟記憶體物件， (grfMode 指定 STGM_PRIORITY) 。
 
snbExclude 參數會指定此儲存物件中要清空的一組元素名稱，因為記憶體對象已開啟：數據流會設定為零的長度;儲存物件已移除其所有元素。 藉由排除某些數據流，建立快照集複製的費用可能會大幅降低。 幾乎一律會在先以優先順序模式開啟記憶體對象之後使用此方法，然後完全將現在排除的專案讀入記憶體中。 這個先前的記憶體對象開啟優先順序模式應該透過 pstgPriority 參數傳遞，以移除優先順序模式所隱含的排除專案。 呼叫的應用程式負責在認可之前重寫排除項目的內容。 因此，這項技術最可能只適用於檔在作用中時不需要持續存取其儲存物件的應用程式。

pstgPriority 參數是為了方便呼叫端取代現有的儲存物件，通常是在優先順序模式中開啟，而新的儲存物件會在相同檔案上開啟，但在不同的模式中開啟。 當 pstgPriority 不是 NULL 時，會用來指定檔名，而不是忽略 pwcsName。 不過，建議應用程式一律為 pstgPriority 傳遞 NULL，因為 StgOpenStorage 在某些情況下會釋放物件，而不會在其他情況下釋放它。 特別是，如果函式傳回失敗結果，呼叫端便無法判斷是否釋放記憶體物件。

呼叫端可以更安全的方式複製 pstgPriority 參數的功能，如下列範例所示：

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}

規格需求

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

另請參閱

IStorage

StgCreateDocfile

StgOpenStorageEx