StgCreateStorageEx 函式 (coml2api.h)
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 參數的值而定。
參數值 | 意義 |
---|---|
|
0 或 FILE_FLAG_NO_BUFFERING。 如需詳細資訊,請參閱 CreateFile。 如果 pStgOptions中指定的檔案扇區大小不是基礎磁碟實體扇區大小的整數倍數,此作業將會失敗。 |
|
必須是 0。 |
[in] pStgOptions
只有當 stgfmt 參數設定 STGFMT_DOCFILE為
[in] pSecurityDescriptor
啟用建立檔案時要設定 ACL。 如果沒有 NULL,就必須是 SECURITY_ATTRIBUTES 結構的指標。 如需如何在檔案上設定 ACL 的相關信息,請參閱 CreateFile。
Windows Server 2003、Windows 2000 Server、Windows XP 和 Windows 2000 Professional:值必須 NULL。
[in] riid
值,指定要傳回之介面指標的介面標識碼 (IID)。 此 IID 可能適用於 IStorage 介面或 IPropertySetStorage 介面。
[out] ppObjectOpen
介面指標變數的指標,可接收新儲存物件上介面的指標;如果作業失敗,則包含 NULL。
傳回值
此函式也可以傳回包裝在 HRESULT中的任何文件系統錯誤或系統錯誤。 如需詳細資訊,請參閱 錯誤處理策略 和 處理未知錯誤。
言論
當應用程式修改其檔案時,通常會建立原始的複本。
StgCreateStorageEx 函式是建立複本的一種方式。 此函式會與加密文件系統 (EFS) 重複 API 間接運作。 當您使用此函式時,您必須在 stGOPTIONS 結構
StgCreateStorageEx 是 StgCreateDocfile 函式的超集,而且應該由新程式代碼使用。 結構化記憶體的未來增強功能將會透過 StgCreateStorageEx 函式公開。 如需支持平台的資訊,請參閱下列需求一節。
StgCreateStorageEx 函式會使用其中一個系統提供的結構化儲存實作來建立新的儲存物件。 此函式可用來取得
建立新檔案時,使用的記憶體實作取決於您指定的旗標,以及檔案儲存所在的磁碟驅動器類型。 如需詳細資訊,請參閱 STGFMT 列舉。
StgCreateStorageEx 不存在時建立檔案。 如果存在,則使用 STGM_CREATE、STGM_CONVERT 和 STGM_FAILIFTHERE 旗標,grfMode 參數會指出如何繼續。 如需這些值的詳細資訊,請參閱 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 IUnkn own 方法。 此外,SetElementTimes 支援 NULL 名稱,讓應用程式能夠在根記憶體上設定時間。 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 應用程式] |
目標平臺 | 窗戶 |
標頭 | coml2api.h (include Objbase.h) |
連結庫 | Ole32.lib |
DLL | Ole32.dll |