stgOpenStorageEx 函式 (coml2api.h)

發行項
02/24/2024

StgOpenStorageEx 函式會在文件系統中開啟現有的根記憶體物件。使用此函式開啟複合檔案和一般檔案。若要建立新的檔案，請使用 StgCreateStorageEx 函式。

注意若要使用增強功能，所有 Windows 2000、Windows XP 和 Windows Server 2003 應用程式都應該呼叫 StgOpenStorageEx，而不是 StgOpenStorage。 StgOpenStorage 函式用於與 Windows 2000 和更早版本的應用程式相容。

語法

HRESULT StgOpenStorageEx(
  [in]      const WCHAR          *pwcsName,
  [in]      DWORD                grfMode,
  [in]      DWORD                stgfmt,
  [in]      DWORD                grfAttrs,
  [in, out] STGOPTIONS           *pStgOptions,
  [in]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]      REFIID               riid,
  [out]     void                 **ppObjectOpen
);

參數

[in] pwcsName

包含記憶體物件的 Null 終止 Unicode 字串檔案路徑指標。此字串大小不能超過 MAX_PATH 個字元。

Windows Server 2003 和 Windows XP/2000： 不同於 CreateFile 函式，無法使用 “\？” 前置詞來超過 MAX_PATH 限制。

[in] grfMode

值，指定要開啟新記憶體物件的存取模式。如需詳細資訊，請參閱 STGM 常數。如果呼叫端指定交易模式與 STGM_CREATE 或 STGM_CONVERT，則會在呼叫根記憶體的認可作業時進行覆寫或轉換。如果未針對根記憶體物件呼叫 IStorage：：Commit ，則會還原檔案先前的內容。 STGM_CREATE 和 STGM_CONVERT 無法與 STGM_NOSNAPSHOT 旗標結合，因為在交易模式中覆寫或轉換檔案時需要快照集複本。

如果儲存物件是以直接模式開啟， (STGM_DIRECT) 存取STGM_WRITE或STGM_READWRITE，除非指定STGM_DIRECT_SWMR模式，否則必須STGM_SHARE_EXCLUSIVE共用模式。如需詳細資訊，請參閱＜備註＞一節。如果記憶體物件是以直接模式開啟並存取STGM_READ，除非指定STGM_PRIORITY或STGM_DIRECT_SWMR，否則共用模式必須是STGM_SHARE_EXCLUSIVE或STGM_SHARE_DENY_WRITE。如需詳細資訊，請參閱＜備註＞一節。

開啟檔案的模式可能會影響實作效能。如需詳細資訊，請參閱複合檔案實作限制。

[in] stgfmt

指定記憶體檔案格式的值。如需詳細資訊，請參閱 STGFMT 列舉。

[in] grfAttrs

值，取決於 stgfmt 參數的值。

STGFMT_DOCFILE 必須是零 (0) 或 FILE_FLAG_NO_BUFFERING。如需此值的詳細資訊，請參閱 CreateFile。如果 pStgOptions 中指定的檔案扇區大小不是基礎磁碟實體扇區大小的整數倍數，則此作業將會失敗。 stgfmt 的所有其他值都必須為零。

[in, out] pStgOptions

STGOPTIONS 結構的指標，其中包含開啟之記憶體對象的相關數據。只有在 stgfmt 參數設定為 STGFMT_DOCFILE 時，pStgOptions 參數才有效。在呼叫 StgOpenStorageEx 之前，必須先設定 usVersion 成員。如需詳細資訊，請參閱 STGOPTIONS 結構。

[in] pSecurityDescriptor

保留;必須是零。

[in] riid

值，指定要傳回之介面指標的 GUID。也可以是 IID_IStorage 以取得 IStorage 介面或 IID_IPropertySetStorage 取得 IPropertySetStorage 介面的標頭指定值。

[out] ppObjectOpen

介面指標變數的位址，該變數會接收開啟之記憶體物件上之介面的指標;如果作業失敗，則包含 NULL 。

傳回值

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

備註

StgOpenStorageEx 是 StgOpenStorage 函式的超集，應該由新程序代碼使用。未來會透過此函式公開結構化記憶體的增強功能。如需支援平臺的詳細資訊，請參閱需求一節。

StgOpenStorageEx 函式會根據 grfMode 參數中的存取模式開啟指定的根儲存物件，如果成功，則為 ppObjectOpen 參數中開啟的儲存物件提供介面指標。此函式可用來取得 IStorage 複合檔案實作、 IPropertySetStorage 複合檔案實作或
IPropertySetStorage 的 NTFS 文件系統實作。

當您開啟檔案時，系統會根據您在檔類型上指定的 STGFMT 旗標，以及儲存盤案的磁碟驅動器類型，選取結構化記憶體實作。

使用 StgOpenStorageEx 函式來存取結構化儲存檔的根儲存區，或支援屬性集之任何檔案的屬性集儲存區。如需不同 STGFMT 值支援哪些介面標識碼 (IID) 的詳細資訊，請參閱 STGFMT。

使用此函式開啟檔案以存取NTFS屬性集實作時，會套用特殊的共享規則。如需詳細資訊，請參閱 IPropertySetStorage-NTFS 實作。

如果複合檔案是以交易模式開啟，方法是藉由指定STGM_TRANSACTED和只讀模式，藉由指定STGM_READ，就可以變更傳回的儲存物件。例如，可以呼叫 IStorage：：CreateStream。不過，您無法藉由呼叫 IStorage：：Commit 來認可這些變更。因此，這類變更將會遺失。

在此函式的 grfMode 參數中使用STGM_CREATE、STGM_DELETEONRELEASE或STGM_CONVERT旗標無效。

為了支援儲存沒有子記憶體之記憶體對象的簡單模式， StgOpenStorageEx 函式會接受下列兩個旗標組合中的其中一個作為 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 常數。

注意例如， grfMode 參數指定 STGM_SHARE_DENY_WRITE) 在讀取和/或寫入模式中開啟交易模式儲存物件 (，因為 StgOpenStorageEx 呼叫必須建立整個記憶體物件的快照集複本，所以 grfMode 參數會指定STGM_SHARE_DENY_WRITE) 相當耗時。

規格需求

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