StgCreateDocfile 函式 (coml2api.h)

  • 發行項

StgCreateDocfile 函式會使用 IStorage 介面的 COM 提供的複合檔案實作，建立新的複合文件儲存物件。

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

語法

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

參數

[in] pwcsName

所建立複合檔案之 Null 終止 Unicode 字串名稱的指標。 它未解譯至文件系統。 這可以是相對名稱或 NULL。 如果 為 NULL，則會以唯一名稱配置暫存複合檔。

[in] grfMode

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

[in] reserved

保留以備將來之用；必須為零。

[out] ppstgOpen

新儲存物件 之 IStorage 指標位置的指標。

傳回值

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

備註

StgCreateDocfile 函式會使用 IStorage 介面的 COM 提供的複合文件實作來建立新的儲存物件。 呼叫 IStorage：：Stat 方法，即可擷取開啟的複合檔案名稱。

StgCreateDocfile 會在檔案不存在時建立檔案。 如果存在，則使用 grfMode 參數中的STGM_CREATE、STGM_CONVERT和STGM_FAILIFTHERE旗標會指出如何繼續。 如需詳細資訊，請參閱 STGM 常數。

如果複合檔案是以交易模式開啟， (grfMode 參數會指定STGM_TRANSACTED) ，而且已有具有此名稱的檔案存在，則在認可所有未完成的變更之前，不會改變現有的檔案。 如果呼叫進程因為文件系統) 中的訪問控制而缺少現有 (檔案的寫入許可權， grfMode 參數只能指定STGM_READ，而且不能指定STGM_WRITE或STGM_READWRITE。 產生的新開啟複合檔案仍可寫入，但後續的認可作業將會在交易模式中失敗 (，在認可時會強制執行寫入許可權) 。

指定STGM_SIMPLE在有限但常用的案例中，提供更快速的複合檔案對象實作。 這可由需要具有多個數據流且沒有記憶體的複合檔案實作的應用程式使用。 簡單模式不支援 IStorage 上的所有方法。 如需詳細資訊，請參閱 STGM 常數。

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

StgCreateDocfile 可用來建立暫存複合檔案，方法是傳遞 pwcsName 參數的 NULL 值。 不過，這些檔案只是暫時性的，因為它們具有系統提供的唯一名稱，可能是使用者沒有意義的名稱。 呼叫端負責在完成時刪除暫存盤，除非已為 grfMode 參數指定STGM_DELETEONRELEASE。

規格需求

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

另請參閱

STGM 常數

StgCreateDocFileOnILockBytes

StgCreateStorageEx