IMAPIProp::GetNamesFromIDs
Область применения: Outlook 2013 | Outlook 2016
Предоставляет имена свойств, которые соответствуют одному или нескольким идентификаторам свойств.
HRESULT GetNamesFromIDs(
LPSPropTagArray FAR * lppPropTags,
LPGUID lpPropSetGuid,
ULONG ulFlags,
ULONG FAR * lpcPropNames,
LPMAPINAMEID FAR * FAR * lpppPropNames
);
Параметры
lppPropTags
[вход, выход] Во входных данных — указатель на структуру SPropTagArray , содержащую массив тегов свойств; в противном случае значение NULL, указывающее, что должны быть возвращены все имена. Элемент cValues для массива тегов свойств не может быть 0. Если lppPropTags является допустимым указателем на входные данные, getNamesFromIDs возвращает имена для каждого идентификатора свойства, включенного в массив.
lpPropSetGuid
[в] Указатель на GUID или структуру GUID , которая идентифицирует набор свойств. Параметр lpPropSetGuid может указывать на допустимый набор свойств или может иметь значение NULL.
ulFlags
[в] Битовая маска флагов, указывающая тип возвращаемых имен. Можно использовать следующие флаги (если оба флага заданы, имена не будут возвращены):
MAPI_NO_IDS
Запрашивает, чтобы возвращались только имена, хранящиеся в виде строк Юникода.
MAPI_NO_STRINGS
Запросы, возвращающие только имена, хранящиеся в виде числовых идентификаторов.
lpcPropNames
[out] Указатель на количество указателей имен свойств в массиве, на который указывает параметр lppPropNames .
lpppPropNames
[out] Указатель на массив указателей на структуры MAPINAMEID , содержащие имена свойств.
Возвращаемое значение
S_OK
Имена свойств были успешно возвращены.
MAPI_E_NO_SUPPORT
Объект не поддерживает именованные свойства.
MAPI_W_ERRORS_RETURNED
Вызов в целом выполнен успешно, но имена для одного или нескольких свойств не могут быть возвращены. Теги свойств для свойств, завершившиеся ошибкой, имеют тип свойства PT_ERROR. При возврате этого предупреждения вызов должен быть обработан как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . Дополнительные сведения см. в разделе Использование макросов для обработки ошибок.
MAPI_E_INVALID_PARAMETER
Элемент cValues одной или нескольких записей в массиве тегов свойств, на который указывает lppPropTags , имеет значение 0.
Замечания
Хотя доступ к большинству свойств осуществляется по идентификатору свойства, доступ к некоторым свойствам можно получить по имени. Метод IMAPIProp::GetNamesFromIDs можно вызвать для выполнения следующих действий:
Получение имен для определенных идентификаторов свойств в определенном наборе свойств.
Получение имен для определенных идентификаторов свойств в любом наборе свойств.
Получение именованных свойств, включенных в сопоставление объекта.
Если lppPropTags указывает на допустимый массив тегов свойств с одним или несколькими идентификаторами свойств, а lpPropSetGuid указывает на допустимый набор свойств, метод GetNamesFromIDs игнорирует набор свойств и типы свойств и возвращает все имена, сопоставленные с указанными идентификаторами.
Если lppPropTags указывает на допустимый массив тегов свойств с одним или несколькими идентификаторами свойств, а lpPropSetGuid имеет значение NULL, GetNamesFromIDs возвращает все имена, сопоставленные с указанными идентификаторами.
Если у указанного идентификатора нет имени, метод GetNamesFromIDs возвращает значение NULL в структуре, возвращаемой в lpppPropNames , а также возвращает MAPI_W_ERRORS_RETURNED.
Если lpPropSetGuid и lppPropTags имеют значение NULL, getNamesFromIDs выделяет новый массив тегов свойств и возвращает все имена для всех именованных свойств объекта.
Если имена не возвращаются, возможно, из-за отсутствия свойств в запрошенном наборе свойств или из-за того, что все свойства исключены из флагов, GetNamesFromIDs выполняет следующие действия:
Возвращает S_OK.
Выделяет новую структуру SPropTagArray , устанавливая для элемента cValues значение 0.
Задает для содержимого lpcPropNames значение 0.
Задает для содержимого lpppPropNames значение NULL.
Примечания для исполнителей
Если lpPropSetGuid указывает на допустимый набор свойств, а lppPropTags имеет значение NULL, результат не определен. Вы можете использовать одну из следующих стратегий:
Игнорировать набор свойств и возвращать имена идентификаторов в массиве тегов свойств.
Возвращает имена только идентификаторов в массиве тегов свойств, принадлежащих указанному набору свойств.
Завершится сбоем вызова, возвращая MAPI_E_INVALID_PARAMETER.
Примечания для вызывающих методов
Чтобы получить все именованные свойства для объекта, необходимо сначала вызвать метод IMAPIProp::GetPropList объекта, а затем передать возвращенные идентификаторы, которые находятся над диапазоном 0x8000, в GetNamesFromIDs.
Если вы передаете допустимый набор свойств, но не допустимый массив тегов свойств, будьте готовы к непредсказуемым результатам. Некоторые реализации GetNamesFromIDs игнорируют набор свойств и возвращают имена идентификаторов в массиве тегов свойств. Некоторые реализации возвращают MAPI_E_INVALID_PARAMETER. Другие реализации возвращают имена идентификаторов всех свойств в наборе свойств. Если набор свойств PS_PUBLIC_STRINGS, getNamesFromIDs может возвращать все имена, которые когда-либо были созданы. Не имеет значения, сохраняет ли поставщик услуг свойство под идентификаторами, связанными с общедоступными строками.
Завершив работу с именами свойств, проверка содержимое параметра lpcPropNames, чтобы определить, были ли возвращены какие-либо имена. В этом случае вызовите функцию MAPIFreeBuffer , чтобы освободить память, на которую указывают lppPropTags и lpppPropNames , при успешном возвращении результата. Для каждого параметра достаточно одного вызова MAPIFreeBuffer ; Вам не нужно проходить по массиву указателей и освобождать каждую структуру MAPINAMEID по отдельности.
Дополнительные сведения об именованных свойствах см. в разделе Именованные свойства MAPI.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::FindAllNamedProps |
MFCMAPI использует метод IMAPIProp::GetNamesFromIDs для поиска именованных свойств, которые были сопоставлены ранее. |