OpenIMsgOnIStg
Область применения: Outlook 2013 | Outlook 2016
Создает новый объект IMessage поверх существующего объекта OLE IStorage , который будет использоваться в сеансе сообщений.
| Свойство | Значение |
|---|---|
| Файл заголовка: |
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
[в] Указатель на объект сеанса сообщений, в котором должен быть создан новый объект IMessage-on-IStorage.
lpAllocateBuffer
[в] Указатель на функцию MAPIAllocateBuffer , используемую для выделения памяти.
lpAllocateMore
[в] Указатель на функцию MAPIAllocateMore , которая будет использоваться для выделения дополнительной памяти.
lpFreeBuffer
[в] Указатель на функцию MAPIFreeBuffer , которая будет использоваться для освобождения памяти.
lpMalloc
[в] Указатель на объект распределителя памяти, предоставляющий интерфейс OLE IMalloc . Интерфейс IMessage должен использовать этот метод выделения при работе с такими интерфейсами, как IStorage и IStream.
lpMapiSup
[в] Необязательный указатель на объект MAPI поддержки, который поставщик услуг может использовать для вызова методов интерфейса IMAPISupport : IUnknown .
lpStg
[вход, выход] Указатель на открытый объект OLE IStorage , имеющий разрешение только на чтение или запись. Так как IMessage не поддерживает доступ только для записи, OpenIMsgOnIStg не принимает объект хранилища, открытый в режиме только для записи.
lpfMsgCallRelease
[в] Необязательный указатель на функцию обратного вызова на основе прототипа MSGCALLRELEASE, вызываемого MAPI после последнего выпуска объекта IMessage-on-IStorage.
ulCallerData
[в] Данные вызывающего объекта, сохраненные MAPI с объектом IMessage-on-IStorage и передаваемые в функцию обратного вызова на основе MSGCALLRELEASE. Данные предоставляют контекст о освобождаемом объекте IMessage и объекте IStorage , поверх которого он был создан.
ulFlags
[в] Битовая маска флагов, используемая для управления тем, вызывается ли метод OLE IStorage::Commit , когда клиентское приложение или поставщик услуг вызывает метод IMessage::SaveChanges . Можно задать следующие флаги:
IMSG_NO_ISTG_COMMIT
Метод OLE IStorage::Commit не вызывается, когда клиент или поставщик вызывает SaveChanges.
MAPI_UNICODE
Позволяет создавать файлы в Юникоде .msg. Полученный файл IMessage отображает STORE_UNICODE_OK в PR_STORE_SUPPORT_MASK и поддерживает свойства Юникода.
Примечание.
Флаг MAPI_UNICODE поддерживается только в этой функции в Outlook 2003 или более поздней версии.
lppMsg
[out] Указатель на указатель на открытый объект IMessage .
Возвращаемое значение
S_OK
����� ������� � ������ ��������� ��������� ��� ��������.
Замечания
Доступ к атрибутам свойств можно получить только для объектов свойств, то есть объектов, реализующих интерфейс IMAPIProp : IUnknown . Чтобы сделать свойства MAPI доступными для объекта структурированного хранилища OLE, OpenIMsgOnIStg создает объект IMessage : IMAPIProp поверх объекта OLE IStorage . Атрибуты свойств для таких объектов можно задать или изменить с помощью SetAttribIMsgOnIStg и получить с помощью GetAttribIMsgOnIStg.
Примечания для вызывающих методов
Перед вызовом OpenIMsgIStg должен быть открыт сеанс сообщений с помощью OpenIMsgSession. Указав допустимый параметр lpMsgSess , убедитесь, что новое сообщение создано в сеансе сообщения, чтобы оно было закрыто при закрытии сеанса. Если lpMsgSess имеет значение NULL, сообщение создается независимо от сеанса сообщений. Если клиентское приложение или поставщик услуг, создавший сообщение, не освобождает его, а также все его вложения и открытые таблицы, происходит утечка памяти, что может привести к завершению работы приложения.
MAPI использует функции, на которые указывают lpAllocateBuffer, lpAllocateMore и lpFreeBuffer , для выделения памяти и освобождения, в частности для выделения памяти для использования клиентскими приложениями при вызове интерфейсов объектов, таких как IMAPIProps::GetProps и IMAPITable::QueryRows. Указатели lpAllocateBuffer, lpAllocateMore и lpFreeBuffer необязательны при вызове функции OpenIMsgOnIStg с допустимым параметром lpMapiSup .
Так как он работает с базовым объектом OLE, MAPI также должен использовать выделение памяти OLE. Дополнительные сведения об объектах структурированного хранилища OLE и выделении памяти OLE см. в справочнике по OLE Programmer.
Если для lpMapiSup задано допустимое значение, IMessage поддерживает флаги MAPI_DIALOG и ATTACH_DIALOG путем вызова метода IMAPISupport::D oProgressDialog для предоставления пользовательского интерфейса хода выполнения для методов IMAPIProp::CopyTo и IMessage::D eleteAttach . Кроме того, метод IMessage::ModifyRecipients пытается преобразовать краткосрочные идентификаторы записи в идентификаторы долгосрочных записей, вызывая метод IMAPISupport::OpenAddressBook и выполняя вызовы результирующего объекта адресной книги. Если значение NULL передается для lpMapiSup, IMessage игнорирует MAPI_DIALOG и ATTACH_DIALOG и сохраняет краткосрочные идентификаторы входа без преобразования.
Объект IStorage , на который указывает параметр lpStg, должен быть открыт в режиме STGM_READ или STGM_READWRITE. Если используется режим STGM_READWRITE, необходимо также задать режим STGM_TRANSACTED.
Функция обратного вызова, на которую указывает параметр lpfMsgCallRelease , является необязательной; Если он указан, он должен быть основан на прототипе функции MSGCALLRELEASE . Интерфейс IMessage вызывает его, когда при последнем вызове метода Release для числа ссылок объекта IMessage-on-IStorage задано значение ноль. Функция обратного вызова обычно используется для освобождения базового интерфейса IStorage . После обратного вызова IMessage не будет пытаться получить доступ к объекту IStorage, на который указывает параметр lpStg.
Некоторые клиенты или поставщики могут записывать дополнительные данные в объект IStorage за пределами того, что сам IMessage записывает при вызове метода SaveChanges . Клиент или поставщик может использовать флаг IMSG_NO_ISTG_COMMIT, чтобы предотвратить вызов метода OLE IStorage::Commit при обработке вызова SaveChanges. в этом случае клиент или поставщик должен самостоятельно зафиксировать объект IStorage при записи дополнительных данных. Чтобы помочь в этом, реализация IMessage гарантирует именовать все дочерние журналы, создаваемые в объекте IStorage , начиная со строки "__", то есть с двумя символами подчеркивания. Клиент или поставщик может избежать конфликтов имен, сохраняя имена подчиненных за пределы этого пространства имен.
MAPI не определяет поведение нескольких открытых операций, выполняемых с подобъектом сообщения, например вложением, потоком или внедренным сообщением. В настоящее время MAPI позволяет открыть уже открытый подобъект, но MAPI выполняет операцию открытия путем увеличения числа ссылок для существующего открытого объекта и возврата его клиенту или поставщику, который вызвал метод IMessage::OpenAttach или IMAPIProp::OpenProperty . Это означает, что доступ, запрошенный для первой открытой операции в подобъекте, является доступом, предоставляемым для всех последующих открытых операций, независимо от того, какой доступ запрашивается операциями.
Правильная процедура размещения сообщения во вложение заключается в вызове метода IMAPIProp::OpenProperty с идентификатором интерфейса IID_IMessage. OpenProperty в настоящее время также поддерживает создание вложений сообщений, доступных непосредственно в интерфейсе OLE IStorage , то есть с использованием идентификатора интерфейса IID_IStorage. Доступ iStorage поддерживается, что позволяет легко поместить документ Microsoft Word во вложение, не преобразовывая его в интерфейс OLE IStream или из него. Однако IMessage может работать непредсказуемо, если OpenIMsgOnIStg передается указатель IStorage на данные вложения, а затем объекты освобождаются в неправильном порядке.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| File.cpp |
LoadMSGToMessage |
MFCMAPI использует метод OpenIMsgOnIStg для открытия интерфейса IMessage поверх . ФАЙЛ MSG, чтобы можно было управлять файлом с помощью MAPI. |