IMAPIProp::GetProps

Статья
04/04/2023

Область применения: Outlook 2013 | Outlook 2016

Извлекает значение свойства одного или нескольких свойств объекта.

HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

Параметры

lpPropTagArray

[в] Указатель на массив тегов свойств, определяющих свойства, значения которых необходимо извлечь. Параметр lpPropTagArray должен иметь значение NULL, указывающее, что должны быть возвращены значения для всех свойств объекта, или указывать на структуру SPropTagArray , содержащую один или несколько тегов свойств.

ulFlags

[в] Битовая маска флагов, указывающая формат свойств с типом PT_UNSPECIFIED. Можно задать следующий флаг:

MAPI_UNICODE

Строковые значения для этих свойств должны возвращаться в формате Юникода. Если флаг MAPI_UNICODE не задан, строковые значения должны быть возвращены в формате ANSI.

lpcValues

[out] Указатель на количество значений свойств, на которые указывает параметр lppPropArray . Если lppPropArray имеет значение NULL, содержимое параметра lpcValues равно нулю.

lppPropArray

[out] Указатель на указатель на полученные значения свойств.

Возвращаемое значение

S_OK

Значения свойств были успешно получены.

MAPI_W_ERRORS_RETURNED

Вызов в целом выполнен успешно, но доступ к одному или нескольким свойствам невозможен. Член aulPropTag значения свойства для каждого недоступного свойства имеет тип свойства PT_ERROR и идентификатор нуля. При возврате этого предупреждения вызов должен быть обработан как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . Дополнительные сведения см. в разделе Использование макросов для обработки ошибок.

MAPI_E_INVALID_PARAMETER

Ноль передан в член cValues структуры SPropTagArray , на которую указывает lpPropTagArray.

Замечания

Метод IMAPIProp::GetProps получает значения свойств одного или нескольких свойств объекта.

Значения свойств возвращаются в том же порядке, в который они были запрошены (то есть порядок свойств в массиве тегов свойств, на который указывает lpPropTagArray , соответствует порядку в массиве структур значений свойств, на которые указывает lppPropArray).

Типы свойств, указанные в элементах aulPropTag массива тегов свойств, указывают тип значения, которое должно быть возвращено в элементе Value каждой структуры значений свойства. Однако если вызывающий объект не знает тип свойства, вместо этого можно задать тип в элементе aulPropTag PT_UNSPECIFIED. При получении значения GetProps задает правильный тип в элементе aulPropTag структуры значений свойства для свойства.

Если типы свойств указаны в SPropTagArray в lpPropTagArray, значения свойств в SPropValue , возвращаемом в lppPropArray , имеют типы, которые точно соответствуют запрошенным типам, если вместо этого не возвращается значение ошибки.

Строковые свойства могут иметь один из двух типов свойств: PT_UNICODE для представления формата Юникода и PT_STRING8 для представления формата ANSI. Если флаг MAPI_UNICODE задан в параметре ulFlags , если GetProps не может определить подходящий формат для свойства строки, он возвращает его значение в формате Юникода. GetProps не может определить точный тип строкового свойства в следующих ситуациях:

Параметр lpPropTagArray имеет значение NULL для запроса всех свойств.
Член aulPropTag включает значение PT_UNSPECIFIED в качестве типа свойства в массиве тегов свойств.

Если для параметра lpPropTagArray задано значение NULL, чтобы получить все свойства объекта и свойства не существуют, GetProps выполняет следующие действия:

Возвращает S_OK.
Задает значение count в элементе cValues структуры значения свойства равным 0.
Задает для содержимого lpcValues значение 0.
Задает значение lppPropArray в значение NULL.

GetProps не должен возвращать свойства с несколькими значениями, для параметра cValues задано значение 0.

Примечания для исполнителей

Вызовите функцию MAPIAllocateBuffer , чтобы первоначально выделить память для структуры SPropValue , на которую указывает lpPropTagArray; вызовите MAPIAllocateMore , чтобы выделить дополнительную память, необходимую для членов структуры.

Верните MAPI_W_ERRORS_RETURNED, если не удается получить значение для одного или нескольких запрошенных свойств. В структуре значения свойства задайте для типа в элементе aulPropTag значение PT_ERROR а для элемента Value — код состояния, описывающий ошибку. Например, если необходимо преобразовать строку в Юникод и не поддерживает Юникод, задайте для элемента Value значение MAPI_E_BAD_CHARWIDTH. Если свойство слишком велико, задайте для него значение MAPI_E_NOT_ENOUGH_MEMORY. Если объект не поддерживает свойство , задайте для него значение MAPI_E_NOT_FOUND.

Реализация метода GetProps удаленного поставщика транспорта должна возвращать значения свойств папки для свойств, запрошенных вызывающим. Реализация должна выполнять следующие действия.

Выделите массив значений свойства для возврата вызывающей объекту и сохраните его адрес в параметре указателя значения свойства, переданном для этой цели.
Скопируйте теги свойств из свойств папки в теги свойств в массиве значений свойств в соответствии с массивом тегов свойств, переданных в GetProps.
Убедитесь, что тип свойства задан для всех тегов свойств, передаваемых в GetProps. Вызывающий объект может передавать тип свойства PT_UNSPECIFIED. В этом случае GetProps должен задать правильный тип свойства для этого тега свойства.
Задайте значение каждого свойства в массиве значений свойств в соответствии с его тегом. Например, если тег свойства, запрошенный вызывающим объектом, PR_OBJECT_TYPE (PidTagObjectType), GetProps может задать значение MAPI_FOLDER.
Если вызывающий объект передает какие-либо теги свойств, которые не обрабатываются реализацией, можно задать для тега свойства значение PT_ERROR для этих свойств и задать для свойства значение MAPI_E_NOT_FOUND.
Верните S_OK, если ошибок не произошло, или MAPI_W_ERRORS_RETURNED, если ошибки были.

Реализация метода GetProps удаленного поставщика транспорта должна как минимум поддерживать следующие свойства:

PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)

Примечания для вызывающих методов

Для свойств типа PT_OBJECT вызовите метод IMAPIProp::OpenProperty вместо GetProps.

Для безопасных свойств не следует извлекать их путем вызова GetProps с параметром lppPropTagArray, заданным значением NULL. При вызове GetProps необходимо явно задать идентификатор безопасного свойства в элементе aulPropTag его массива тегов свойств. Когда и как доступно безопасное свойство, определяет поставщик услуг.

Освободите возвращаемую структуру SPropValue , вызвав функцию MAPIFreeBuffer , только если GetProps возвращает S_OK или MAPI_W_ERRORS_RETURNED.

Если GetProps возвращает MAPI_W_ERRORS_RETURNED, так как ему не удавалось получить доступ к одному или нескольким свойствам, проверка теги свойств возвращаемых свойств. Неудающиеся свойства будут иметь следующие значения, заданные в их структуре значений свойств:

Тип свойства в элементе aulPropTag , для PT_ERROR.
Значение свойства в элементе Value имеет код состояния для ошибки, например MAPI_E_NOT_FOUND.

Свойства, которые завершаются ошибкой из-за того, что они слишком велики, чтобы их было удобно возвращать в структуре значений свойства , их члену Value присвоено значение MAPI_E_NOT_ENOUGH_MEMORY. Как правило, это происходит со строковыми или двоичными свойствами типа PT_STRING8, PT_UNICODE или PT_BINARY, если значение свойства составляет 4 КБ или больше. Вызовите IMAPIProp::OpenProperty , чтобы получить большие свойства.

Не все реализации GetProps поддерживают форматы Юникода и ANSI для символьных строк. Если для определенного свойства требуется преобразование формата строки и GetProps не может его поддерживать, для элемента Value для свойства задается значение MAPI_E_BAD_CHARWIDTH.

Чтобы проверка, если PST является PST-приложением SharePoint, подключите PST с помощью IMAPISession::OpenMsgStore, а затем вызовите GetProps для объекта хранилища сообщений, запрашивающего это свойство. Если он существует, можно предположить, что PST настроен для SharePoint. Если нет, PST не настроен как PST SharePoint.

Дополнительные сведения об использовании GetProps для доступа к свойствам см. в разделе Получение свойств MAPI.

Справочные материалы по MFCMAPI

Пример кода MFCMAPI указан в приведенной ниже таблице.

Файл	Функция	Comment
MAPIFunctions.cpp	GetPropsNULL	MFCMAPI использует метод IMAPIProp::GetProps для получения всех свойств объекта путем передачи null или массива, возвращаемого методом IMAPIProp::GetPropList в параметре lpPropTagArray .