MAPI des propri�t�s nomm�e
S’applique à : Outlook 2013 | Outlook 2016
MAPI permet d’attribuer des noms aux propriétés, de mapper ces noms à des identificateurs uniques et de rendre ce mappage persistant. Le mappage de nom persistant à identificateur garantit que les noms de propriétés restent valides entre les sessions.
Pour définir une propriété nommée, un client ou un fournisseur de services crée un nom et le stocke dans une structure MAPINAMEID . Étant donné que les noms sont constitués d’un identificateur global unique 128 bits, ou GUID, et d’une chaîne de caractères Unicode ou d’une valeur numérique 32 bits, les créateurs de propriétés nommées peuvent créer des noms explicites sans crainte de duplication. Les noms sont uniques et peuvent être utilisés sans tenir compte de la valeur de leurs identificateurs.
Pour prendre en charge les propriétés nommées, un fournisseur de services implémente deux méthodes : IMAPIProp ::GetIDsFromNames et IMAPIProp ::GetNamesFromIDs pour traduire entre les noms et les identificateurs et pour autoriser ses méthodes IMAPIProp ::GetPropsIMAPIProp ::SetProps à récupérer et modifier des propriétés avec des identificateurs dans la plage de propriétés nommées. La plage des identificateurs de propriété nommés est comprise entre 0x8000 et 0xFFFE.
Tout objet qui implémente l’interface IMAPIProp peut prendre en charge les propriétés nommées. Les fournisseurs de carnets d’adresses qui autorisent la copie des entrées d’autres fournisseurs dans leurs conteneurs et les fournisseurs de magasins de messages qui peuvent être utilisés pour créer des types de messages arbitraires sont requis pour fournir cette prise en charge. Il s’agit d’une option pour tous les autres fournisseurs de services. Les fournisseurs qui ne prennent pas en charge les propriétés nommées retournent MAPI_E_NO_SUPPORT à partir des méthodes GetIDsFromNames et GetNamesFromIDs et refusent de définir des propriétés avec des identificateurs de 0x8000 ou supérieur, renvoyant MAPI_E_UNEXPECTED dans le SPropProblemarray.
La création de noms pour les propriétés est un moyen pour les clients de définir de nouvelles propriétés pour les classes de message existantes ou personnalisées. Les fournisseurs de services peuvent utiliser des propriétés nommées pour exposer des fonctionnalités uniques de leurs systèmes de messagerie. Une autre utilisation des propriétés nommées consiste à fournir une autre façon de faire référence aux propriétés avec des identificateurs sous 0x8000.
Par exemple, un client peut utiliser un code similaire au code suivant pour récupérer les noms de toutes les propriétés nommées d’un objet :
LPSPropTagArray FAR * lppPropTags = NULL;
LPGUID lpPropSetGuid = NULL;
ULONG FAR * lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;
lpMAPIProp->GetNamesFromIDs (lppPropTags,
lpPropSetGuid,
0,
lpcPropNames,
lpppPropNames);
Pour demander tous les noms du jeu de propriétés PS_PUBLIC_STRINGS, un client remplace la valeur NULL dans le paramètre de jeu de propriétés par PS_PUBLIC_STRINGS comme suit :
LPSPropTagArray FAR * lppPropTags = NULL;
LPGUID lpPropSetGuid = &PS_PUBLIC_STRINGS;
ULONG FAR * lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;
lpMAPIProp->GetNamesFromIDs (lppPropTags,
lpPropSetGuid,
0,
lpcPropNames,
lpppPropNames);