IABContainer::ResolveNames
S’applique à : Outlook 2013 | Outlook 2016
Effectue la résolution de noms pour une ou plusieurs entrées de destinataire.
HRESULT ResolveNames(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
LPADRLIST lpAdrList,
LPFlagList lpFlagList
);
Paramètres
lpPropTagArray
[in] Pointeur vers une structure SPropTagArray qui contient un tableau de balises de propriété décrivant les propriétés à inclure dans la structure ADRLIST retournée par le fournisseur. Pour demander le jeu de propriétés par défaut du fournisseur, transmettez NULL dans le paramètre lpPropTagArray .
ulFlags
[in] Masque de bits d’indicateurs qui contrôle le type du texte dans les chaînes retournées. Les indicateurs suivants peuvent être définis :
EMS_AB_ADDRESS_LOOKUP
Seules les correspondances d’adresse de proxy exactes sont trouvées ; les correspondances partielles sont ignorées. Cet indicateur est pris en charge uniquement par le fournisseur de carnets d’adresses Exchange.
MAPI_CACHE_ONLY
Seul le carnet d’adresses en mode hors connexion sera utilisé pour effectuer la résolution de noms. Par exemple, vous pouvez utiliser cet indicateur pour permettre à une application cliente d’ouvrir la liste d’adresses globale (GAL) en mode d’échange mis en cache et d’accéder à une entrée de ce carnet d’adresses à partir du cache sans créer de trafic entre le client et le serveur. Cet indicateur est pris en charge uniquement par le fournisseur de carnets d’adresses Exchange.
MAPI_UNICODE
Les propriétés de chaîne retournées sont au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, les chaînes sont au format ANSI.
lpAdrList
[in, out] En entrée, pointeur vers une structure ADRLIST qui contient la liste des destinataires à résoudre. En sortie, pointeur vers une structure ADRLIST qui contient les noms résolus.
lpFlagList
[in, out] Pointeur vers un tableau d’indicateurs, chaque indicateur correspondant à une structure ADRENTRY dans le paramètre lpAdrList, qui fournit la status de l’opération de résolution de noms pour le destinataire. Les indicateurs du paramètre lpFlagList sont dans le même ordre que les entrées de lpAdrList. Les indicateurs suivants peuvent être définis :
MAPI_AMBIGUOUS
Le destinataire correspondant a été résolu, mais pas en identificateur d’entrée unique. Les autres conteneurs ne doivent pas essayer de résoudre ce destinataire.
MAPI_RESOLVED
Le destinataire correspondant a été résolu en identificateur d’entrée unique. Les autres conteneurs ne doivent pas essayer de résoudre ce destinataire.
MAPI_UNRESOLVED
L’entrée correspondante n’a pas été résolue. D’autres conteneurs doivent essayer de résoudre ce destinataire.
Valeur renvoyée
S_OK
Le processus de résolution de noms a réussi.
MAPI_E_BAD_CHARWIDTH
Soit l’indicateur MAPI_UNICODE a été défini et l’implémentation ne prend pas en charge Unicode, soit MAPI_UNICODE n’a pas été défini et l’implémentation prend uniquement en charge Unicode.
MAPI_E_NO_SUPPORT
Le fournisseur de carnet d’adresses ne prend pas en charge la résolution de noms en bloc à l’aide de cette méthode.
Remarques
La méthode ResolveNames tente de faire correspondre les destinataires non résolus du tableau d’entrées du paramètre lpAdrList aux destinataires de ce conteneur de carnet d’adresses. Un destinataire non résolu a généralement uniquement la propriété PR_DISPLAY_NAME (PidTagDisplayName) et peut-être quelques autres propriétés. Un destinataire non résolu n’a pas la propriété PR_ENTRYID (PidTagEntryId) et son indicateur correspondant dans le paramètre lpFlagList est défini sur MAPI_UNRESOLVED. À l’inverse, un destinataire résolu a toujours au moins la propriété PR_ENTRYID ainsi que plusieurs autres propriétés telles que PR_EMAIL_ADDRESS (PidTagEmailAddress), PR_DISPLAY_NAME et PR_ADDRTYPE (PidTagAddressType).
La résolution de noms démarre généralement lorsqu’un client appelle la méthode IAddrBook ::ResolveName . Outlook MAPI répond en appelant la méthode ResolveNames de chaque conteneur de carnet d’adresses inclus dans le chemin de recherche du carnet d’adresses, spécifié par la propriété PR_AB_SEARCH_PATH (PidTagAbSearchPath). Les entrées du paramètre lpAdrList incluent des destinataires déjà résolus, car ils se trouvent dans des conteneurs pour lesquels MAPI a déjà appelé ResolveNames, car les entrées apparaissent plus haut dans le chemin de recherche.
Chaque conteneur tente de résoudre les entrées non résolues en faisant correspondre le nom d’affichage du destinataire au nom complet de l’une de ses entrées. Lorsqu’une correspondance unique est trouvée, ResolveNames ajoute la propriété PR_ENTRYID et d’autres propriétés incluses dans le paramètre lpPropTagArray à l’entrée correspondante dans la structure ADRLIST sortante. ResolveNames définit ensuite l’entrée dans le paramètre lpFlagList sur MAPI_RESOLVED. L’identificateur d’entrée stocké dans la propriété PR_ENTRYID peut être à court terme ou à long terme.
Une fois que tous les conteneurs du chemin de recherche ont tenté le processus de résolution de noms, MAPI ouvre une boîte de dialogue, si possible, pour demander à l’utilisateur de l’aide pour résoudre les conflits restants.
Les clients peuvent également utiliser la structure ADRLIST retournée dans les appels à la méthode IMessage ::ModifyRecipients .
Remarques pour les responsables de l’implémentation
Vous n’êtes pas obligé de prendre en charge la résolution de noms avec la méthode ResolveNames . Au lieu de cela, ou en plus, vous pouvez le prendre en charge avec la restriction de propriété PR_ANR (PidTagAnr). Si vous décidez de vous appuyer sur la restriction PR_ANR pour la résolution de noms, vous pouvez retourner MAPI_E_NO_SUPPORT. For more information, see L'impl�mentation de la r�solution de noms.
Définissez l’entrée d’indicateur d’un destinataire dans le paramètre lpFlagList sur MAPI_UNRESOLVED si le destinataire ne correspond à aucun des destinataires du conteneur.
Lorsqu’un destinataire correspond à plusieurs destinataires, définissez son indicateur sur MAPI_AMBIGUOUS et ne modifiez pas sa structure ADRENTRY .
MAPI nécessite certaines propriétés pour les destinataires inclus dans la liste des destinataires d’un message. Vous pouvez les inclure dans la structure ADRENTRY dans le cadre du processus de résolution de noms ou attendre que MAPI les demande avec des appels aux méthodes IAddrBook ::P repareRecips et IMAPISupport ::ExpandRecips . Vous pouvez éliminer ces appels supplémentaires et améliorer les performances en incluant les propriétés suivantes dans les structures ADRENTRY de tous les destinataires résolus :
PR_ADDRTYPE
PR_DISPLAY_NAME
PR_EMAIL_ADDRESS
PR_ENTRYID
PR_OBJECT_TYPE (PidTagObjectType)
PR_SEARCH_KEY (PidTagSearchKey)
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)
Si certaines propriétés du paramètre lpPropTagArray ne sont pas disponibles (généralement parce que l’entrée de conteneur ne prend pas en charge les propriétés et qu’elles ne sont pas incluses dans le membre ADRENTRY du destinataire dans la structure ADRLIST ), définissez le type de propriété de chaque propriété non disponible sur PT_ERROR.
Ne supprimez aucune propriété de la structure ADRENTRY d’un destinataire résolu.
Si vous devez remplacer plutôt que modifier une structure ADRENTRY , libérez d’abord la structure ADRENTRY d’origine en appelant la fonction MAPIFreeBuffer , puis allouez la structure ADRENTRY de remplacement avec MAPIAllocateBuffer.