IMAPIProp::OpenProperty
Область применения: Outlook 2013 | Outlook 2016
Возвращает указатель на интерфейс, который можно использовать для доступа к свойству .
HRESULT OpenProperty(
ULONG ulPropTag,
LPCIID lpiid,
ULONG ulInterfaceOptions,
ULONG ulFlags,
LPUNKNOWN FAR * lppUnk
);
Параметры
ulPropTag
[в] Тег свойства для доступа к свойству. Идентификатор и тип должны быть включены в тег свойства.
lpiid
[в] Указатель на идентификатор интерфейса, который будет использоваться для доступа к свойству . Параметр lpiid не должен иметь значение NULL.
ulInterfaceOptions
[в] Данные, связанные с интерфейсом, определяемым параметром lpiid .
ulFlags
[в] Битовая маска флагов, управляющая доступом к свойству. Можно задать следующие флаги:
MAPI_CREATE
Если свойство не существует, оно должно быть создано. Если свойство существует, текущее значение свойства должно быть отменено. Когда вызывающий объект задает флаг MAPI_CREATE, он также должен задать флаг MAPI_MODIFY.
MAPI_DEFERRED_ERRORS
Позволяет OpenProperty успешно возвращать объект, возможно, до того, как объект будет полностью доступен вызывающей. Если объект недоступен, последующий вызов объекта может вызвать ошибку.
MAPI_MODIFY
MAPI_MODIFY требуется в следующих ситуациях:
При открытии свойства потока, например IID_IStream, чтобы изменить его.
При открытии внедренного вложения сообщения, например PR_ATTACH_DATA_OBJ открыто с помощью IID_IMessage, чтобы изменить его.
lppUnk
[out] Указатель на запрошенный интерфейс, используемый для доступа к свойству.
Возвращаемое значение
S_OK
Запрошенный указатель интерфейса успешно возвращен.
MAPI_E_INTERFACE_NOT_SUPPORTED
Запрошенный интерфейс не поддерживается для этого свойства.
MAPI_E_NO_ACCESS
У вызывающего объекта недостаточно разрешений для доступа к свойству.
MAPI_E_NO_SUPPORT
Объект не может предоставить доступ к этому свойству через запрошенный интерфейс.
MAPI_E_NOT_FOUND
Запрошенное свойство не существует, и MAPI_CREATE не задано в параметре ulFlags .
MAPI_E_INVALID_PARAMETER
Тип свойства в теге имеет значение PT_UNSPECIFIED.
Замечания
Метод IMAPIProp::OpenProperty предоставляет доступ к свойству через определенный интерфейс. OpenProperty является альтернативой методам IMAPIProps::GetProps и IMAPIProp::SetProps . Если getProps или SetProps завершается ошибкой из-за слишком большого или слишком сложного свойства, вызовите OpenProperty. OpenProperty обычно используется для доступа к свойствам типа PT_OBJECT.
Примечания для вызывающих методов
Чтобы получить доступ к вложениям сообщений, откройте свойство PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) с другим идентификатором интерфейса в зависимости от типа вложения. В следующей таблице описано, как вызвать OpenProperty для различных типов вложений:
| Тип вложения | Идентификатор интерфейса для использования |
|---|---|
| В двоичном формате |
IID_IStream |
| String |
IID_IStream |
| Сообщение |
IID_IMessage |
| OLE 2.0 |
IID_IStreamDocfile |
IStreamDocfile — это производная от интерфейса IStream , основанная на составном файле OLE 2.0. IStreamDocfile — лучший вариант для доступа к вложениям OLE 2.0, так как он требует наименьшего объема накладных расходов. Вы можете использовать IID_IStreamDocFile для свойств, содержащих данные, хранящиеся в структурированном хранилище, доступном через интерфейс IStorage .
Дополнительные сведения об использовании OpenProperty со вложениями см. в разделе Свойство PR_ATTACH_DATA_OBJ и Открытие вложения.
Не используйте полученный указатель IStream для вызова метода Seek или SetSize , если не используется нулевая позиция или переменная размера. Кроме того, не полагайтесь на значение выходного параметра plibNewPosition , возвращаемого вызовом Seek .
При вызове OpenProperty для доступа к свойству с помощью интерфейса IStream используйте только этот интерфейс, чтобы внести в него изменения. Не пытайтесь обновить свойство с помощью других методов IMAPIProp : IUnknown , таких как SetProps или IMAPIProp::D eleteProps.
Не пытайтесь открыть свойство с помощью OpenProperty более одного раза. Результаты не определены, так как они могут отличаться от поставщика к поставщику.
Если необходимо изменить открытое свойство, установите флаг MAPI_MODIFY. Если вы не уверены, поддерживает ли объект свойство, но считаете нужным, задайте флаги MAPI_CREATE и MAPI_MODIFY. При установке MAPI_CREATE также необходимо задать MAPI_MODIFY.
Вы отвечаете за переадресацию указателя интерфейса, возвращенного в параметре lppUnk , на указатель, соответствующий интерфейсу, указанному в параметре lpiid . Возвращаемый указатель также необходимо использовать для вызова метода IUnknown::Release по завершении работы с ним.
Иногда задания флагов в параметре ulFlags недостаточно, чтобы указать тип доступа к необходимому свойству. Дополнительные данные, например флаги, можно поместить в параметр ulInterfaceOptions . Эти данные зависят от интерфейса. Некоторые интерфейсы (например , IStream) используют его, а другие — нет. Например, при открытии свойства для изменения с помощью IStream задайте флаг STGM_WRITE в параметре ulInterfaceOptions в дополнение к MAPI_MODIFY. При открытии таблицы с помощью интерфейса IMAPITable можно задать для ulInterfaceOptions значение MAPI_UNICODE, чтобы указать, должны ли столбцы таблицы, в которых содержатся строковые свойства, иметь формат Юникода.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| StreamEditor.cpp |
CStreamEditor::ReadTextStreamFromProperty |
MFCMAPI использует метод IMAPIProp::OpenProperty для получения интерфейса потока для больших текстовых и двоичных свойств. |