IMAPIProp::GetIDsFromNames
Область применения: Outlook 2013 | Outlook 2016
Предоставляет идентификаторы свойств, которые соответствуют одному или нескольким именам свойств.
HRESULT GetIDsFromNames(
ULONG cPropNames,
LPMAPINAMEID FAR * lppPropNames,
ULONG ulFlags,
LPSPropTagArray FAR * lppPropTags
);
Параметры
cPropNames
[в] Количество имен свойств, на которые указывает параметр lppPropNames . Если lppPropNames имеет значение NULL, параметр cPropNames должен иметь значение 0.
lppPropNames
[в] Указатель на массив имен свойств или NULL. Передача NULL запрашивает идентификаторы свойств для всех имен свойств во всех наборах свойств, о которых объект содержит сведения. Параметр lppPropNames не должен иметь значение NULL, если флаг MAPI_CREATE задан в параметре ulFlags .
ulFlags
[в] Битовая маска флагов, указывающая, как должны быть возвращены идентификаторы свойств. Можно задать следующий флаг:
MAPI_CREATE
Назначает идентификатор свойства , если он еще не назначен, одному или нескольким именам, включенным в массив имен свойств, на который указывает lppPropNames. Этот флаг внутренне регистрирует идентификатор в таблице сопоставления имени и идентификатора.
lppPropTags
[out] Указатель на указатель на массив тегов свойств, содержащий существующие или недавно назначенные идентификаторы свойств. Типы свойств для тегов свойств в этом массиве имеют значение PT_UNSPECIFIED.
Возвращаемое значение
S_OK
Идентификаторы для указанных имен свойств были успешно возвращены.
MAPI_E_NO_SUPPORT
Объект не поддерживает именованные свойства.
MAPI_E_NOT_ENOUGH_MEMORY
Недостаточно памяти для получения идентификаторов.
MAPI_E_TOO_BIG
Невозможно выполнить операцию, так как для нее требуется возвратить слишком много тегов свойств.
MAPI_W_ERRORS_RETURNED
Вызов в целом выполнен успешно, но не удалось вернуть один или несколько идентификаторов свойств. Соответствующий тип свойства для каждого недоступного свойства имеет значение PT_ERROR , а его идентификатор равен нулю. При возврате этого предупреждения обработайте вызов как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . См . раздел Использование макросов для обработки ошибок.
Замечания
Метод IMAPIProp::GetIDsFromNames извлекает массив тегов свойств, которые содержат идентификаторы свойств для одного или нескольких именованных свойств. IMAPIProp::GetIDsFromNames можно вызвать для выполнения следующих действий:
Создание идентификаторов для новых имен.
Получение идентификаторов для определенных имен.
Получение идентификаторов для всех именованных свойств, включенных в сопоставление объекта.
Именованные свойства обычно используются поставщиками хранилища сообщений для папок и сообщений. Другие объекты, такие как пользователи сообщений и разделы профиля, могут не поддерживать связь имен с идентификаторами свойств и возвращать MAPI_E_NO_SUPPORT из GetIDsFromNames.
Если возникает ошибка, которая возвращает идентификатор для определенного имени, GetIDsFromNames возвращает MAPI_W_ERRORS_RETURNED и задает тип свойства в записи массива тегов свойств, которая соответствует имени PT_ERROR , а идентификатору — нулю.
Сопоставление имени и идентификатора представлено свойством PR_MAPPING_SIGNATURE объекта (PidTagMappingSignature). PR_MAPPING_SIGNATURE содержит структуру MAPIUID , указывающую поставщика услуг, ответственного за объект . Если свойство PR_MAPPING_SIGNATURE одинаково для двух объектов, предположим, что эти объекты используют одно и то же сопоставление имени и идентификатора.
Примечания для исполнителей
Идентификаторы, которые передаются обратно в массиве тегов свойств, на который указывает параметр lppPropNames , должны находиться в 0x8000 0xFFFE диапазоне. Записи в этом массиве должны находиться в том же порядке, что и имена, передаваемые в массиве имен свойств, на который указывает lppPropNames.
Если вы поддерживаете именованные свойства в контейнере, используйте одно и то же сопоставление имен и идентификаторов для всех объектов в контейнере (то есть не используйте разное сопоставление для каждой папки в хранилище сообщений или каждого сообщения в папке).
Примечания для вызывающих методов
Так как для типов свойств возвращаемых идентификаторов в массиве тегов свойств, на который указывает lppPropTags , задано значение PT_UNSPECIFIED, необходимо вызвать метод IMAPIProp::SetProps , чтобы получить точные типы.
Если вы перемещаете или копируете объекты с именоваемыми свойствами, а исходные и целевые объекты имеют разные подписи сопоставления, как указано значениями их PR_MAPPING_SIGNATURE свойств, имена необходимо сохранить во время этих операций. Чтобы сохранить имена свойств, настройте соответствующие идентификаторы свойств в соответствии с сопоставлением имени и идентификатора целевого объекта.
Некоторые объекты имеют ограничение на количество идентификаторов свойств, которые они могут называть. Если вызов GetIDsFromNames приводит к превышению этого ограничения, метод возвращает MAPI_E_TOO_BIG. В этом случае выполняется запрос по идентификатору.
Дополнительные сведения см. в разделе Именованные свойства MAPI.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::FindAllNamedPropsUsed |
MFCMAPI использует метод IMAPIProp::GetIDsFromNames для получения тегов свойств для всех сопоставленных именованных свойств. |