OpenStreamOnFile

適用於：Outlook 2013 |Outlook 2016

配置並初始化 OLE IStream 物件，以存取檔案的內容。 此函式會採用 ANSI 字串作為檔名，包括路徑和擴展名，因此建議使用此函式的 Unicode 版本 OpenStreamOnFileW。

項目	值
標頭檔：	Mapiutil.h
實作者：	Mapi
通話者：	用戶端應用程式和服務提供者

HRESULT STDMETHODCALLTYPE OpenStreamOnFile(
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPFREEBUFFER lpFreeBuffer,
  ULONG ulFlags,
  LPSTR lpszFileName,
  LPSTR lpszPrefix,
  LPSTREAM FAR * lppStream
);

參數

lpAllocateBuffer

[in] MAPIAllocateBuffer 函式的指標，用來配置記憶體。

lpFreeBuffer

[in] MAPIFreeBuffer 函式的指標，用來釋放記憶體。

ulFlags

[in]旗標的位掩碼，用來控制要透過 OLE IStream 物件存取之檔案的建立或開啟。 您可以設定下列旗標：

SOF_UNIQUEFILENAME

要為 IStream 物件建立暫存盤。 如果已設定此旗標，則也應該設定STGM_CREATE和STGM_READWRITE旗標。

STGM_CREATE

即使檔案已經存在，還是要建立檔案。 如果未設定 lpszFileName 參數，則必須同時設定此旗標和STGM_DELETEONRELEASE。 如果設定STGM_CREATE，也必須設定STGM_READWRITE旗標。

STGM_DELETEONRELEASE

釋放 IStream 物件時，將會刪除檔案。 如果未設定 lpszFileName 參數，則必須同時設定此旗標和STGM_CREATE。

STGM_READ

檔案是以唯讀存取權建立或開啟。

STGM_READWRITE

檔案是以讀取/寫入許可權建立或開啟。 如果未設定此旗標，則不得設定STGM_CREATE旗標。

lpszFileName

[in] OpenStreamOnFile 初始化 IStream 物件之檔案的檔名，包括路徑和擴展名。 如果已設定SOF_UNIQUEFILENAME旗標， lpszFileName 會 包含要在其中建立臨時檔之目錄的路徑。 如果 lpszFileName 是 NULL，OpenStreamOnFile 會從系統取得適當的路徑，而且必須設定STGM_CREATE和STGM_DELETEONRELEASE旗標。

lpszPrefix

[in] OpenStreamOnFile 初始化 IStream 物件之檔名的前置詞。 如果設定，前置詞必須包含不超過三個字元。 如果 lpszPrefix 為 NULL，則會使用 “SOF” 的前置詞。

lppStream

[out]公開 IStream 介面之物件的指標。

傳回值

S_OK

呼叫成功，並傳回預期的值。

MAPI_E_NO_ACCESS

無法存取檔案，因為用戶權力不足或無法修改唯讀檔案。

MAPI_E_NOT_FOUND

指定的檔案不存在。

註解

OpenStreamOnFile 函式有兩個重要用途，以SOF_UNIQUEFILENAME旗標的設定來區分。 未設定此旗標時，OpenStreamOnFile 會在現有的檔案上開啟 IStream 物件，例如使用 IStream：：CopyTo 方法，將其內容複製到附件的 PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) 屬性。 在此情況下， lpszFileName 參數會指定檔案的路徑和檔名。

設定SOF_UNIQUEFILENAME時， OpenStreamOnFile 會建立暫存盤來保存 IStream 對象的數據。 針對此使用方式， lpszFileName 參數可以選擇性地指定要建立檔案之目錄的路徑， 而 lpszPrefix 參數可以選擇性地指定檔名的前置詞。

當呼叫的用戶端應用程式或服務提供者完成 IStream 物件時，應該呼叫 OLE IStream：：Release 方法來釋放它。

MAPI 會針對大部分的記憶體配置和解除分配使用 lpAllocateBuffer 和 lpFreeBuffer 所指向的函式，特別是在呼叫 IMAPIProp：：GetProps 和 IMAPITable：：QueryRows 等物件介面時，配置記憶體供用戶端應用程式使用。

呼叫者注意事項

SOF_UNIQUEFILENAME旗標可用來建立具有訊息系統唯一名稱的臨時檔。 如果設定此旗標， lpszFileName 參數會指定暫存盤的路徑， 而 lpszPrefix 參數則包含檔名的前置字元。 建構的檔名是 <前置詞>HHHH。TMP，其中 HHHH 是十六進位數位。 如果 lpszFileName 是 NULL，則會在從 Windows 函式 GetTempPath 傳回的暫存盤目錄中建立檔案，如果未指定暫存盤目錄，則會建立當前目錄。

如果未設定SOF_UNIQUEFILENAME旗標， 則會忽略 lpszPrefix ，且 lpszFileName 應該包含要開啟或建立之檔案的完整路徑和檔名。 檔案將會根據 ulFlags中設定的其他旗標來開啟或建立。

MFCMAPI 參考

如需 MFCMAPI 範例程式代碼，請參閱下表。

檔案	Function	Comment
File.cpp	WriteAttachStreamToFile	MFCMAPI 使用 OpenStreamOnFile 方法在檔案上開啟數據流，以便將附件寫出至檔案。

另請參閱

MFCMAPI 作為程式碼範例