Именованные свойства MAPI
Область применения: Outlook 2013 | Outlook 2016
MAPI предоставляет возможность присваивать имена свойствам, сопоставлять эти имена с уникальными идентификаторами и делать это сопоставление постоянным. Постоянное сопоставление имени и идентификатора гарантирует, что имена свойств остаются действительными в сеансах.
Чтобы определить именованное свойство, клиент или поставщик услуг создает имя и сохраняет его в структуре MAPINAMEID . Поскольку имена состоят из 128-разрядного глобально уникального идентификатора или GUID, а также символьной строки Юникода или 32-разрядного числового значения, создатели именованных свойств могут создавать значимые имена, не опасаясь дублирования. Имена уникальны, и их можно использовать без учета значения идентификаторов.
Для поддержки именованных свойств поставщик услуг реализует два метода — IMAPIProp::GetIDsFromNames и IMAPIProp::GetNamesFromIDs — для преобразования имен и идентификаторов и разрешения его методам IMAPIProps::GetPropsIMAPIProps::SetProps извлекать и изменять свойства с идентификаторами в диапазоне именованных свойств. Диапазон идентификаторов именованных свойств находится в диапазоне от 0x8000 до 0xFFFE.
Любой объект, реализующий интерфейс IMAPIProp , может поддерживать именованные свойства. Поставщики адресных книг, которые позволяют копировать записи от других поставщиков в свои контейнеры, и поставщики хранилища сообщений, которые могут использоваться для создания произвольных типов сообщений, необходимы для предоставления этой поддержки. Это вариант для всех других поставщиков услуг. Поставщики, не поддерживающие именованные свойства, возвращают MAPI_E_NO_SUPPORT из методов GetIDsFromNames и GetNamesFromIDs и отказываются задавать свойства с идентификаторами 0x8000 или более поздней, возвращая MAPI_E_UNEXPECTED в SPropProblemarray.
Создание имен свойств — это один из способов определения клиентами новых свойств для существующих или пользовательских классов сообщений. Поставщики услуг могут использовать именованные свойства для предоставления уникальных функций своих систем обмена сообщениями. Еще одно использование именованных свойств заключается в предоставлении альтернативного способа ссылки на свойства с идентификаторами ниже 0x8000.
Например, клиент может использовать код, аналогичный приведенному ниже, для получения имен для всех именованных свойств объекта:
LPSPropTagArray FAR * lppPropTags = NULL;
LPGUID lpPropSetGuid = NULL;
ULONG FAR * lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;
lpMAPIProp->GetNamesFromIDs (lppPropTags,
lpPropSetGuid,
0,
lpcPropNames,
lpppPropNames);
Чтобы запросить все имена из набора свойств PS_PUBLIC_STRINGS, клиент заменит значение NULL в параметре property set на PS_PUBLIC_STRINGS следующим образом:
LPSPropTagArray FAR * lppPropTags = NULL;
LPGUID lpPropSetGuid = &PS_PUBLIC_STRINGS;
ULONG FAR * lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;
lpMAPIProp->GetNamesFromIDs (lppPropTags,
lpPropSetGuid,
0,
lpcPropNames,
lpppPropNames);