StgCreateStorageEx 函式 (coml2api.h)

發行項
08/22/2023

StgCreateStorageEx函式會使用IStorage或IPropertySetStorage介面提供的實作來建立新的儲存物件。若要開啟現有的檔案，請改用 StgOpenStorageEx 函式。

針對 Windows 2000、Windows Server 2003 和 Windows XP 所撰寫的應用程式必須使用 StgCreateStorageEx ，而不是 StgCreateDocfile 來利用增強的 Windows 2000 和 Windows XP 結構化儲存體功能。

語法

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

參數

[in] pwcsName

要建立之檔案路徑的指標。它未解譯至檔案系統。這可以是相對名稱或 Null。如果 為 Null，則會以唯一名稱配置暫存檔案。如果為非Null，字串大小不得超過MAX_PATH個字元。

Windows 2000： 不同于 CreateFile 函式，您無法使用「\？」前置詞超過MAX_PATH限制。

[in] grfMode

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

[in] stgfmt

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

[in] grfAttrs

值，取決於 stgfmt 參數的值。

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

[in] pStgOptions

只有在stgfmt參數設定為 STGFMT_DOCFILE 時，pStgOptions參數才有效。如果 stgfmt 參數設定為 STGFMT_DOCFILE， pStgOptions 會指向 STGOPTIONS 結構，這會指定儲存體物件的功能，例如磁區大小。此參數可能是 Null，它會建立預設磁區大小為 512 個位元組的儲存體物件。如果不是Null， ulSectorSize 成員必須設定為 512 或 4096。如果設定為 4096，STGM_SIMPLE可能無法在 grfMode 參數中指定。必須先設定 usVersion 成員，才能呼叫 StgCreateStorageEx。如需詳細資訊，請參閱 STGOPTIONS。

[in] pSecurityDescriptor

啟用建立檔案時要設定的 ACL。如果不是 Null，則必須是 SECURITY_ATTRIBUTES 結構的指標。如需如何在檔案上設定 ACL 的資訊，請參閱 CreateFile 。

Windows Server 2003、Windows 2000 Server、Windows XP 和 Windows 2000 專業版： 值必須是 Null。

[in] riid

值，指定要傳回之介面指標的介面識別碼 (IID) 。此 IID 可能適用于 IStorage 介面或 IPropertySetStorage 介面。

[out] ppObjectOpen

介面指標變數的指標，可接收新儲存物件上介面的指標;如果作業失敗，則包含 Null 。

傳回值

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

備註

當應用程式修改其檔案時，通常會建立原始的複本。 StgCreateStorageEx函式是建立複本的一種方式。此函式會間接地與加密檔案系統 (EFS) 重複 API 搭配運作。當您使用此函式時，您必須在 STGOPTIONS 結構中設定檔案儲存體的選項。

StgCreateStorageEx 是 StgCreateDocfile 函式的超集合，應該由新程式碼使用。結構化儲存體的未來增強功能將會透過 StgCreateStorageEx 函式公開。如需支援平臺的資訊，請參閱下列需求一節。

StgCreateStorageEx函式會使用其中一個系統提供的結構化儲存體實作來建立新的儲存物件。此函式可用來取得
IStorage 複合檔案實作、 IPropertySetStorage 複合檔案實作，或取得 IPropertySetStorage NTFS 實作。

建立新檔案時，使用的儲存體實作取決於您指定的旗標，以及儲存檔案的磁片磁碟機類型。如需詳細資訊，請參閱 STGFMT 列舉。

StgCreateStorageEx 如果檔案不存在，就會建立檔案。如果存在，則使用 grfMode 參數中的STGM_CREATE、STGM_CONVERT和STGM_FAILIFTHERE旗標會指出如何繼續。如需這些值的詳細資訊，請參閱 STGM 常數。在直接模式中，指定 grfMode 參數 (直接模式中的STGM_READ模式無效，方法是未指定STGM_TRANSACTED旗標) 。此函式無法用來開啟現有的檔案;請改用 StgOpenStorageEx 函式。

您可以使用 StgCreateStorageEx 函式來存取結構化儲存體檔的根儲存體，或支援屬性集之任何檔案的屬性集儲存體。如需不同 STGFMT 值支援哪些 IID 的相關資訊，請參閱 STGFMT 檔。

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

如果在交易模式中建立複合檔案， (藉由指定STGM_TRANSACTED) 和唯讀模式 (指定STGM_READ) ，就可以對傳回的儲存體物件進行變更。例如，可以呼叫 IStorage：：CreateStream。不過，您無法呼叫 IStorage：：Commit來認可這些變更。因此，這類變更將會遺失。

指定STGM_SIMPLE在有限的情況下，提供更快速的複合檔案物件實作，但經常使用的案例牽涉到需要具有多個資料流程且沒有儲存體之複合檔案實作的應用程式。如需詳細資訊，請參閱 STGM 常數。如果指定STGM_SIMPLE，則指定STGM_TRANSACTED無效。

簡單模式不支援 IStorage上的所有方法。具體而言，在簡單模式中，支援的IStorage方法是CreateStream、Commit和SetClass，以及QueryInterface、AddRef和Release的 COM IUnknown方法。此外，使用Null名稱支援SetElementTimes，允許應用程式在根儲存體上設定時間。 IStorage的所有其他方法都會傳回STG_E_INVALIDFUNCTION。

如果 grfMode 參數指定STGM_TRANSACTED，且 pwcsName 參數指定的名稱尚未存在，則會立即建立檔案。在受存取控制的檔案系統中，呼叫端必須具有建立複合檔案之檔案系統目錄的寫入權限。如果未指定STGM_TRANSACTED，而且已指定STGM_CREATE，則會在建立新檔案之前終結具有相同名稱的現有檔案。

您也可以使用StgCreateStorageEx來建立暫存複合檔案，方法是傳遞pwcsName參數的Null值。不過，這些檔案只是暫時性的，只是因為它們具有唯一的系統提供名稱，也就是對使用者而言可能沒有意義的名稱。呼叫端負責在完成時刪除暫存檔，除非已為 grfMode 參數指定STGM_DELETEONRELEASE。如需這些旗標的詳細資訊，請參閱 STGM 常數。

規格需求


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