Общие сведения о типе свойства MAPI
Область применения: Outlook 2013 | Outlook 2016
Типы свойств — это константы, определенные MAPI в MAPIDEFS. Файл заголовка H, указывающий базовый тип данных значения свойства. Все свойства, определенные MAPI, клиентскими приложениями или поставщиками услуг, используют один из этих типов.
Типы свойств соответствуют соглашению об именовании, аналогичному соглашению, используемому для тегов свойств. Многие типы свойств имеют версию с одним и несколькими значениями. Однозначные свойства содержат одно значение своего типа, например одно целое число или строку символов. Константа, используемая для представления свойства одного значения, состоит из двух частей: префикса PT_ и строки, описывающей фактический тип, например LONG или STRING8.
Свойства с несколькими значениями содержат несколько значений своего типа. В отличие от массивов вариантов OLE, каждое значение в многозначном свойстве имеет один и тот же тип. Константы, используемые для представления многозначных свойств, создаются путем объединения флага MV_FLAG с соответствующей константой с одним значением, представляющей базовый тип. Существует три части: префикс PT_ за которым следует MV_ строка, описывающая тип. Например, тип свойства, содержащего несколько целых чисел, — PT_MV_LONG, а для нескольких символьных строк — PT_MV_STRING8.
На следующем рисунке показана структура структуры SPropValue для описания целого числа с несколькими значениями, свойства типа PT_MV_LONG. Элемент Value расширяется, чтобы включить количество целочисленных значений в свойстве и указатель на массив этих значений.
Свойства с несколькими значениями
Хотя поддержка свойств с несколькими значениями необязательна, MAPI рекомендует, чтобы клиенты и поставщики услуг поддерживали оба типа свойств, так как это позволяет повысить взаимодействие между компонентами, совместимыми с MAPI.
На следующем рисунке перечислены все различные константы типа свойств, где они хранятся в структуре SPropValue . Размер элемента Value зависит от конкретного типа. Обратите внимание, что не все типы с одним значением имеют эквиваленты нескольких значений.
Константы типа свойств
Клиенты и поставщики услуг, работающие со свойством, должны выполнить два действия:
Определите, доступно ли свойство или недоступно.
Если доступно, получите значение свойства.
Иногда клиенту или поставщику услуг требуется только проверка для существования свойства; в других случаях необходимо проверка для определенного значения. Например, поставщики транспорта имеют три различных способа обработки свойства PR_SEND_RICH_INFO (PidTagSendRichInfo), логическое значение, указывающее, следует ли передавать сообщение с отформатированным текстом. Если PR_SEND_RICH_INFO имеет значение TRUE, поставщик транспорта передает форматированный текст. Если задано значение FALSE, то перед передачей отформатированный текст удаляется. Если PR_SEND_RICH_INFO недоступен, поставщик транспорта выполняет действия по умолчанию, независимо от того, что предназначено для конкретного поставщика.
MAPI определяет специальный тип свойства, PT_UNSPECIFIED, который клиент или поставщик услуг может использовать для получения свойства, если тип свойства неизвестен. Чтобы получить свойство без предварительного знания его типа, клиент или поставщик услуг вызывает метод IMAPIProp::GetProps объекта и передает тег свойства, состоящий из идентификатора свойства и типа свойства PT_UNSPECIFIED. GetProps возвращает структуру SPropValue для свойства, заменяя PT_UNSPECIFIED соответствующим типом. Поставщики служб, реализующие GetProps, необходимы для поддержки PT_UNSPECIFIED.
Некоторые объекты MAPI поддерживают свойства, которые сами являются объектами. Свойства объекта имеют тип PT_OBJECT. Вместо использования IMAPIProp::GetProps для доступа к этим свойствам клиенты и поставщики услуг обычно используют метод IMAPIProp::OpenProperty , указав соответствующий интерфейс для доступа, или метод объекта, поддерживающего свойство .
Так как доступ к значению свойства объекта предполагает использование одного из интерфейсов для объекта, Метод GetProps неуместен. При использовании GetProps вызывающий объект обращается к значению свойства через структуру SPropValue . С помощью IMAPIProp::OpenProperty вызывающий объект извлекает указатель на интерфейс, который может получить доступ к объекту . OpenProperty всегда можно использовать для получения свойства объекта. Другой параметр, вызывающий метод для объекта, доступен не для каждого свойства объекта.
Например, каждая папка поддерживает две таблицы: таблицу иерархии и таблицу содержимого. Эти таблицы являются свойствами папки; их теги свойств — PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) и PR_CONTAINER_CONTENTS (PidTagContainerContents). Таблицы — это объекты, которым требуется интерфейс IMAPITable для доступа. Клиент может вызвать метод IMAPIContainer::GetHierarchyTable папки для доступа к таблице иерархии, метод IMAPIContainer::GetContentsTable папки для доступа к таблице содержимого или метод IMAPIProp::OpenProperty папки для доступа к любой таблице. Чтобы вызвать OpenProperty, клиент передает тег свойства для свойства в качестве первого параметра и идентификатор интерфейса для интерфейса, который будет использоваться для доступа в качестве второго параметра. Эти параметры будут PR_CONTAINER_HIERARCHY или PR_CONTAINER_CONTENTS и IID_IMAPITable.
Полный список типов свойств с одним и несколькими значениями см. в разделе Типы свойств.