OpenIMsgOnIStg
适用于：Outlook 2013 | Outlook 2016
在现有 OLE IStorage 对象的基础上生成一个新的 IMessage 对象，以在消息会话中使用。
| 属性 | 值 |
|---|---|
| 标头文件： |
Imessage.h |
| 实现者： |
MAPI |
| 调用者： |
客户端应用程序和服务提供商 |
SCODE OpenIMsgOnIStg(
LPMSGSESS lpMsgSess,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
LPMALLOC lpmalloc,
LPVOID lpMapiSup,
LPSTORAGE lpStg,
MSGCALLRELEASE FAR * lpfMsgCallRelease,
ULONG ulCallerData,
ULONG ulFlags,
LPMESSAGE FAR * lppMsg
);
参数
lpMsgSess
[in]指向消息会话对象的指针，将在其中创建新的 IMessage-on- IStorage 对象。
lpAllocateBuffer
[in]指向 MAPIAllocateBuffer 函数的指针，用于分配内存。
lpAllocateMore
[in]指向 MAPIAllocateMore 函数的指针，用于分配额外的内存。
lpFreeBuffer
[in]指向 MAPIFreeBuffer 函数的指针，用于释放内存。
lpMalloc
[in]指向公开 OLE IMalloc 接口的内存分配器对象的指针。 使用 IStorage 和 IStream 等接口时，IMessage 接口需要使用此分配方法。
lpMapiSup
[in]指向 MAPI 支持对象的可选指针，服务提供商可以使用该对象调用 IMAPISupport ： IUnknown 接口的方法。
lpStg
[in，out]指向打开且具有只读或读/写权限的 OLE IStorage 对象的指针。 由于 IMessage 不支持仅写访问， 因此 OpenIMsgOnIStg 不接受在只写模式下打开的存储对象。
lpfMsgCallRelease
[in]基于 MSGCALLRELEASE 原型的回调函数的可选指针，MAPI 在 IMessage-on- IStorage 对象上最后一次发布后调用该原型。
ulCallerData
[in]由 MAPI 使用 IMessage-on- IStorage 对象保存的调用方数据，并传递给基于 MSGCALLRELEASE 的 回调函数。 数据提供有关要发布的 IMessage 对象和基于该对象的 IStorage 对象的上下文。
ulFlags
[in]当客户端应用程序或服务提供商调用 IMessage：：SaveChanges 方法时，用于控制是否调用 OLE IStorage：：Commit 方法的标志的位掩码。 可以设置以下标志：
IMSG_NO_ISTG_COMMIT
客户端或提供程序调用 SaveChanges 时，不调用 OLE 方法 IStorage：：Commit。
MAPI_UNICODE
启用 Unicode .msg文件的创建。 生成的 IMessage 文件在其PR_STORE_SUPPORT_MASK中显示 STORE_UNICODE_OK ，并支持 Unicode 属性。
注意
MAPI_UNICODE标志仅在 Outlook 2003 或更高版本上的此函数中受支持。
lppMsg
[out]指向指向打开的 IMessage 对象的指针的指针。
返回值
S_OK
调用成功，并返回了预期的值。
备注
只能在属性对象（即实现 IMAPIProp 的对象）上访问属性属性： IUnknown 接口。 为了使 MAPI 属性在 OLE 结构化存储对象上可用，OpenIMsgOnIStg 在 OLE IStorage 对象之上生成 IMessage ： IMAPIProp 对象。 可以使用 SetAttribIMsgOnIStg 设置或更改此类对象的属性属性，并使用 GetAttribIMsgOnIStg 检索。
给调用方的说明
在调用 OpenIMsgOnIStg 之前，应使用 OpenIMsgSession 打开消息会话。 提供有效的 lpMsgSess 参数可确保在消息会话中创建新消息，以便在会话关闭时将其关闭。 如果 lpMsgSess 为 NULL，则会独立于任何消息会话创建消息。 如果创建消息的客户端应用程序或服务提供程序未释放它及其所有附件和打开的表，则内存会泄漏，并可能导致应用程序终止。
MAPI 使用 lpAllocateBuffer、 lpAllocateMore 和 lpFreeBuffer 指向的函数进行大多数内存分配和解除分配，特别是在调用对象接口（如 IMAPIProp：：GetProps 和 IMAPITable：：QueryRows）时分配内存供客户端应用程序使用。 使用有效的 lpMapiSup 参数调用 OpenIMsgOnIStg 函数时，lpAllocateBuffer、lpAllocateMore 和 lpFreeBuffer 指针是可选的。
由于 MAPI 正在处理基础 OLE 对象，因此还需要使用 OLE 内存分配。 有关 OLE 结构化存储对象和 OLE 内存分配的详细信息，请参阅 OLE 程序员参考。
如果为 lpMapiSup 提供了有效值， 则 IMessage 通过调用 IMAPISupport：:D oProgressDialog 方法为 IMAPIProp：：CopyTo 和 IMessage：:D eleteAttach 方法提供进度用户界面，从而支持MAPI_DIALOG和ATTACH_DIALOG标志。 此外， IMessage：：ModifyRecipients 方法尝试通过调用 IMAPISupport：：OpenAddressBook 方法并调用生成的通讯簿对象，将短期条目标识符转换为长期条目标识符。 如果为 lpMapiSup 传递 NULL， 则 IMessage 会忽略MAPI_DIALOG并ATTACH_DIALOG并存储短期条目标识符，而不进行转换。
必须在STGM_READ或STGM_READWRITE模式下打开 lpStg 参数指向的 IStorage 对象。 如果使用STGM_READWRITE模式，还必须设置STGM_TRANSACTED模式。
lpfMsgCallRelease 参数指向的回调函数是可选的;如果提供，则应基于 MSGCALLRELEASE 函数原型。 当 IMessage-on- IStorage 对象的引用计数被最后一次调用其 Release 方法设置为零时，IMessage 接口会调用它。 回调函数通常用于释放基础 IStorage 接口。 进行回调后，IMessage 不会尝试访问 lpStg 参数指向的 IStorage 对象。
某些客户端或提供程序可能会在调用其 SaveChanges 方法时向 IStorage 对象写入超出 IMessage 本身写入的数据。 客户端或提供程序可以使用 IMSG_NO_ISTG_COMMIT 标志来防止 IMessage 在处理 SaveChanges 调用时调用 OLE IStorage：：Commit 方法;在这种情况下，在写入其他数据时，客户端或提供程序必须自行提交 IStorage 对象。 为了帮助实现此目的， IMessage 实现保证命名它在 IStorage 对象中创建的所有子存储，以字符串“__”开头，即使用两个下划线。 客户端或提供程序可以通过将其子存储名称保留在此命名空间中来避免名称冲突。
MAPI 不定义对邮件的子对象（如附件、流或嵌入邮件）执行的多个打开操作的行为。 MAPI 当前允许已打开的子对象再次打开，但 MAPI 通过递增现有打开对象的引用计数并将其返回到调用 IMessage：：OpenAttach 或 IMAPIProp：：OpenProperty 方法的客户端或提供程序来执行打开操作。 这意味着，为子对象上的第一个打开操作请求的访问权限是为所有后续打开操作提供的访问权限，而不管这些操作请求的访问权限是什么。
将邮件放入附件的正确过程是调用接口标识符为 IID_IMessage 的 IMAPIProp：：OpenProperty 方法。 OpenProperty 目前还支持创建直接在 OLE IStorage 接口上可用的消息附件，即使用 IID_IStorage 接口标识符。 支持 IStorage 访问，以便轻松将 Microsoft Word 文档放入附件中，而无需将其与 OLE IStream 接口进行转换。 但是，如果 OpenIMsgOnIStg 传递了指向附件数据的 IStorage 指针，然后以错误的顺序释放对象，IMessage 的行为可能无法预测。
MFCMAPI 引用
有关 MFCMAPI 示例代码，请参阅下表。
| 文件 | 函数 | Comment |
|---|---|---|
| File.cpp |
LoadMSGToMessage |
MFCMAPI 使用 OpenIMsgOnIStg 方法在 顶部打开 IMessage 接口。MSG 文件，以便可以使用 MAPI 操作文件。 |