Канонические свойства MAPI
Область применения: Outlook 2013 | Outlook 2016
Каноническое свойство — это виртуальное свойство, представляющее свойство MAPI или несколько свойств MAPI, определенных с одинаковым идентификатором свойства. Канонические свойства предназначены только для упрощения согласованной идентификации свойств MAPI в обсуждениях или документации за пределами кода. В отличие от имен свойств, определенных MAPI, имена канонических свойств не определяются как глобальные константы в файлах заголовков MAPI.
Соглашения об именовании
Канонические имена свойств начинаются с префикса Pid, который представляет идентификатор свойства. В зависимости от того, является ли свойство помеченным тегом, именованным свойством с числовым идентификатором или именованным свойством со строковым именем, префикс дополнительно квалифицируется как "PidTag", "PidLid" и "PidName" соответственно. Например, PidTagAccount представляет свойства с тегами, PR_ACCOUNT (PidTagAccount), PR_ACCOUNT_A (PidTagAccount) и PR_ACCOUNT_W (PidTagAccount), которые указывают имя учетной записи получателя; PidLidContacts представляет свойство dispidContacts , именованное свойство с числовым идентификатором и указывающее имя контактов, связанных с сообщением; и PidNamePhishingStamp представляет "http://schemas.microsoft.com/outlook/phishingstamp," именованное свойство со строковым именем и указывающее сообщения, которые могут быть фишинговыми.
Представление похожих свойств с помощью одного канонического свойства
Определение свойств в MAPI
Все свойства в MAPI определяются идентификатором свойства, который является 16-разрядным значением без знака. Идентификатор свойства и тип свойства (другое 16-разрядное значение без знака) представляют собой тег свойства для свойства.
MAPI использует тег свойства для уникального определения свойств. Свойства с одинаковым тегом свойства, например PR_BUSINESS2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber) и PR_OFFICE2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber), считаются идентичными свойствами в MAPI. Список тегов свойств, определенных MAPI для собственных свойств, см. в файле заголовка MAPI Mapitags.h.
Обратите внимание, что MAPI делит идентификаторы свойств на диапазоны. Если идентификатор попадает в диапазон, указывает на его использование и владение. Идентификаторы свойств с тегами попадают в диапазон 0x0001 0x7FFF. В этом диапазоне находятся идентификаторы свойств, определенных MAPI, которые попадают в диапазон 0x0001 0x3FFF. Идентификаторы именованных свойств попадают в диапазон от 0x8000 до 0x8FFF.
Именованные свойства дополнительно приписываются набором свойств и длинным идентификатором (LID), который является 32-разрядным значением без знака, или строкой. Набор свойств — это GUID, который идентифицирует группу именованных свойств с аналогичной целью. Набор свойств и LID или строковое имя используются для получения или задания именованного свойства.
Тип свойства
Помимо идентификаторов, свойство присваивается типом данных, указывающим тип значений, разрешенных для этого свойства.
Для свойств строкового типа в зависимости от поддержки Юникода на базовой платформе свойство может иметь тип PT_STRING8 (8-разрядная строка символов с пустым завершением) или PT_UNICODE (строка Юникода, завершающаяся null). Свойство можно определить с помощью типа PT_TSTRING и, в зависимости от параметров компиляции, PT_TSTRING по умолчанию строку Юникода для платформ, поддерживающих Юникод, или строку PT_STRING8 для платформ, поддерживающих ANSI или DBCS. Обычно строковое свойство определяется тремя похожими именами, такими как PR_ACCOUNT, PR_ACCOUNT_A и PR_ACCOUNT_W, которые относятся к типу PT_TSTRING, PT_STRING8 и PT_UNICODE соответственно.
Дополнительные сведения о типах свойств и макросах, связанных с типами, см. в файле заголовка MAPI Mapidefs.h.
Определение похожих свойств
В текущем ландшафте свойств MAPI нередко обнаруживается, что свойство предоставляется с разными именами свойств, которые определяются с одинаковым идентификатором свойства. Например, свойства с тегами , PR_BUSINESS2_TELEPHONE_NUMBER и PR_OFFICE2_TELEPHONE_NUMBER, определены в Mapitags.h для того, чтобы иметь одинаковый идентификатор и тип свойства. Тесно связаны с этими двумя свойствами:
PR_BUSINESS2_TELEPHONE_NUMBER_A
PR_BUSINESS2_TELEPHONE_NUMBER_W
PR_OFFICE2_TELEPHONE_NUMBER_A
PR_OFFICE2_TELEPHONE_NUMBER_W
Свойства с суффиксом "_A" типируются как PT_STRING8, а свойства с суффиксом "_W" — как PT_UNICODE.
Цель канонического свойства PidTagBusiness2TelephoneNumber в этом примере заключается в том, чтобы упростить ссылки на такие тесно связанные свойства MAPI с помощью одного идентификатора и согласованно (с помощью префикса Pid) во всех свойствах MAPI. Чтобы узнать, какие реальные свойства MAPI представляет каноническое свойство, см. статью Сопоставление имен канонических свойств с именами MAPI. Чтобы найти каноническое свойство, с которым связано свойство MAPI, см. раздел Сопоставление имен MAPI с каноническими именами свойств.
Поддержка MAPI имен канонических свойств
Так как канонические свойства не являются реальными свойствами и не определены в файлах заголовков MAPI, не следует использовать в коде имена канонических свойств. Вместо этого следует продолжать использовать точные имена свойств MAPI в коде. Например, можно ссылаться на PR_BUSINESS2_TELEPHONE_NUMBER и PR_OFFICE2_TELEPHONE_NUMBER вне кода как PidTagBusiness2TelephoneNumber и использовать в коде PR_BUSINESS2_TELEPHONE_NUMBER или PR_OFFICE2_TELEPHONE_NUMBER .
Если в коде необходимо использовать канонические имена свойств, необходимо сначала определить их в собственных файлах заголовков.
Канонические имена свойств и спецификации протокола Exchange
Канонические имена указываются в спецификациях протоколов Microsoft Exchange Server, которые используются Exchange Server для взаимодействия с другими продуктами Майкрософт. Дополнительные сведения о свойствах объекта сообщения, на которые ссылаются спецификации протокола Exchange, см. в разделе [MS-OXPROPS].