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 示例代码，请参阅下表。

文件	函数	Comment
File.cpp	WriteAttachStreamToFile	MFCMAPI 使用 OpenStreamOnFile 方法打开文件上的流，以便可以向该文件写出附件。

另请参阅

MFCMAPI 代码示例