Propriétés canoniques MAPI
S’applique à : Outlook 2013 | Outlook 2016
Une propriété canonique est une propriété virtuelle qui représente une propriété MAPI, ou plusieurs propriétés MAPI définies avec le même identificateur de propriété. Les propriétés canoniques sont uniquement destinées à faciliter l’identification cohérente des propriétés MAPI dans les discussions ou la documentation en dehors du code. Contrairement aux noms de propriétés étiquetées définis par MAPI, les noms de propriétés canoniques ne sont pas définis en tant que constantes globales dans les fichiers d’en-tête MAPI.
Conventions d’affectation de noms
Les noms de propriétés canoniques commencent par un préfixe, « Pid », qui représente « identificateur de propriété ». Selon que la propriété est une propriété étiquetée, une propriété nommée avec un identificateur numérique ou une propriété nommée avec un nom de chaîne, le préfixe est qualifié respectivement comme « PidTag », « PidLid » et « PidName ». Par exemple, PidTagAccount représente les propriétés balisées, PR_ACCOUNT (PidTagAccount), PR_ACCOUNT_A (PidTagAccount) et PR_ACCOUNT_W (PidTagAccount), qui spécifient le nom de compte d’un destinataire ; PidLidContacts représente la propriété dispidContacts , une propriété nommée qui a un identificateur numérique et qui spécifie le nom des contacts associés à un message ; et PidNamePhishingStamp représente «http://schemas.microsoft.com/outlook/phishingstamp », une propriété nommée qui a un nom de chaîne et qui spécifie la chaîne marquant les messages susceptibles d’être du hameçonnage.
Représentation de propriétés similaires à l’aide d’une propriété canonique
Identification des propriétés dans MAPI
Toutes les propriétés dans MAPI sont identifiées par un identificateur de propriété qui est une valeur 16 bits non signée. L’identificateur de propriété et le type de propriété (une autre valeur 16 bits non signée) constituent une balise de propriété pour la propriété.
MAPI utilise une balise de propriété pour définir les propriétés de manière unique. Les propriétés qui ont la même balise de propriété, comme PR_BUSINESS2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber) et PR_OFFICE2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber), sont considérées comme des propriétés identiques dans MAPI. Pour obtenir la liste des balises de propriété que MAPI a définies pour ses propres propriétés, consultez le fichier d’en-tête MAPI, Mapitags.h.
Notez que MAPI divise les identificateurs de propriété en plages. L’emplacement d’un identificateur dans la plage indique son utilisation et sa propriété. Les identificateurs de propriété des propriétés balisées se situent dans la plage de 0x0001 à 0x7FFF. Dans cette plage se trouvent les identificateurs de propriété des propriétés définies par MAPI, qui entrent dans la plage de 0x0001 à 0x3FFF. Les identificateurs de propriété des propriétés nommées sont compris entre 0x8000 et 0x8FFF.
Les propriétés nommées sont également attribuées par un jeu de propriétés et un ID long (LID), qui est une valeur 32 bits non signée, ou une chaîne. Un jeu de propriétés est un GUID qui identifie un groupe de propriétés nommées ayant un objectif similaire. Le jeu de propriétés et le LID ou le nom de chaîne sont utilisés pour obtenir ou définir la propriété nommée.
Type de propriété
Outre les identificateurs, une propriété est attribuée par un type de données qui spécifie le type de valeurs autorisées pour cette propriété.
Pour les propriétés de type chaîne, selon la prise en charge d’Unicode dans la plateforme sous-jacente, la propriété peut être de type PT_STRING8 (chaîne de caractères 8 bits terminée par null) ou PT_UNICODE (chaîne Unicode terminée par null). Une propriété peut être définie avec le type PT_TSTRING et, selon les paramètres de compilation, PT_TSTRING par défaut une chaîne Unicode pour les plateformes qui prennent en charge Unicode, ou une chaîne PT_STRING8 pour les plateformes qui prennent en charge ANSI ou DBCS. Il est courant qu’une propriété de type chaîne soit identifiée par trois noms similaires, tels que PR_ACCOUNT, PR_ACCOUNT_A et PR_ACCOUNT_W, qui sont respectivement de type PT_TSTRING, PT_STRING8 et PT_UNICODE.
Pour plus d’informations sur les types de propriétés et les macros associées aux types, consultez le fichier d’en-tête MAPI Mapidefs.h.
Identification des propriétés similaires
Dans le paysage de propriétés MAPI actuel, il n’est pas rare de constater qu’une propriété a été exposée sous différents noms de propriété, qui sont tous définis avec le même identificateur de propriété. Par exemple, les propriétés balisées, PR_BUSINESS2_TELEPHONE_NUMBER et PR_OFFICE2_TELEPHONE_NUMBER, sont définies dans Mapitags.h pour avoir le même identificateur de propriété et le même type. Ces deux propriétés sont étroitement liées :
PR_BUSINESS2_TELEPHONE_NUMBER_A
PR_BUSINESS2_TELEPHONE_NUMBER_W
PR_OFFICE2_TELEPHONE_NUMBER_A
PR_OFFICE2_TELEPHONE_NUMBER_W
Les propriétés avec le suffixe « _A » sont typées comme PT_STRING8, et celles avec le suffixe « _W » sont typées comme PT_UNICODE.
L’objectif d’une propriété canonique, PidTagBusiness2TelephoneNumber dans cet exemple, est de faciliter le référencement de ces propriétés MAPI étroitement affiliées à l’aide d’un identificateur et de manière cohérente (à l’aide du préfixe « Pid ») sur toutes les propriétés MAPI. Pour connaître les propriétés MAPI réelles qu’une propriété canonique représente, consultez Mappage de noms de propriétés canoniques à des noms MAPI. Pour rechercher la propriété canonique à laquelle une propriété MAPI est associée, consultez Mappage de noms MAPI à des noms de propriétés canoniques.
Prise en charge MAPI des noms de propriétés canoniques
Étant donné que les propriétés canoniques ne sont pas des propriétés réelles et ne sont pas définies dans les fichiers d’en-tête MAPI, vous ne devez pas utiliser de noms de propriétés canoniques dans le code . au lieu de cela, vous devez continuer à utiliser les noms de propriétés MAPI exacts dans le code. Par exemple, vous pouvez faire référence PR_BUSINESS2_TELEPHONE_NUMBER et PR_OFFICE2_TELEPHONE_NUMBER en dehors du code en tant que PidTagBusiness2TelephoneNumber, et utiliser PR_BUSINESS2_TELEPHONE_NUMBER ou PR_OFFICE2_TELEPHONE_NUMBER dans le code.
Si vous devez utiliser des noms de propriétés canoniques dans votre code, vous devez d’abord les définir dans vos propres fichiers d’en-tête.
Noms de propriétés canoniques et spécifications du protocole Exchange
Les noms canoniques sont référencés dans Microsoft Exchange Server spécifications de protocole utilisées par Exchange Server pour communiquer avec d’autres produits Microsoft. Pour plus d’informations sur les propriétés d’objet message référencées par les spécifications du protocole Exchange, consultez [MS-OXPROPS].