IAddrBook::ResolveName
S’applique à : Outlook 2013 | Outlook 2016
Effectue la résolution de noms, en affectant des identificateurs d’entrée aux destinataires d’une liste de destinataires.
HRESULT ResolveName(
ULONG_PTR ulUIParam,
ULONG ulFlags,
LPSTR lpszNewEntryTitle,
LPADRLIST lpAdrList
);
Paramètres
ulUIParam
[in] Handle de la fenêtre parente d’une boîte de dialogue qui s’affiche, si elle est spécifiée, pour inviter l’utilisateur à résoudre l’ambiguïté.
ulFlags
[in] Masque de bits d’indicateurs qui contrôlent différents aspects du processus de résolution. Les indicateurs suivants peuvent être définis :
AB_UNICODEUI
Indique que lpszNewEntryTitle est une chaîne UNICODE.
MAPI_CACHE_ONLY
Utilisez uniquement le carnet d’adresses en mode hors connexion 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_DIALOG
Affiche une boîte de dialogue pour inviter l’utilisateur à fournir des informations supplémentaires sur la résolution de noms. Si cet indicateur n’est pas défini, aucune boîte de dialogue n’est affichée.
MAPI_UNICODE
Indique que les propriétés retournées dans la liste d’adresses doivent être de type PT_UNICODE et non PT_STRING8.
lpszNewEntryTitle
[in] Pointeur vers le texte du titre du contrôle dans la boîte de dialogue qui invite l’utilisateur à entrer un destinataire. Le titre varie en fonction du type de destinataire. Le paramètre lpszNewEntryTitle peut être NULL.
lpAdrList
[in-out] Pointeur vers une structure ADRLIST qui contient la liste des noms de destinataires à résoudre. Cette structure ADRLIST peut être créée par la méthode IAddrBook ::Address .
Valeur renvoyée
S_OK
Le processus de résolution de noms a réussi.
MAPI_E_AMBIGUOUS_RECIP
Au moins un destinataire dans le paramètre lpAdrList correspondait à plusieurs entrées dans le carnet d’adresses. En règle générale, cette valeur est retournée lorsque l’indicateur MAPI_DIALOG est défini, ce qui empêche l’affichage d’une boîte de dialogue.
MAPI_E_NOT_FOUND
Au moins un destinataire dans le paramètre lpAdrList ne peut pas être résolu. En règle générale, cette valeur est retournée lorsque l’indicateur MAPI_DIALOG est défini, ce qui empêche l’affichage d’une boîte de dialogue.
Remarques
Les clients et les fournisseurs de services appellent la méthode ResolveName pour lancer le processus de résolution de noms. Une entrée non résolue est une entrée qui n’a pas encore d’identificateur d’entrée ou de propriété PR_ENTRYID (PidTagEntryId).
ResolveName passe par le processus suivant pour chaque entrée non résolue dans la liste d’adresses passée dans le paramètre lpAdrList .
Si le type d’adresse du destinataire respecte le format d’une adresse SMTP ( displayname@ domain.top-level-domain), ResolveName lui attribue un identificateur d’entrée unique.
Pour chaque conteneur de la propriété PR_AB_SEARCH_PATH (PidTagAbSearchPath), ResolveName appelle la méthode IABContainer ::ResolveNames . ResolveNames tente de faire correspondre le nom d’affichage de chaque destinataire non résolu avec un nom d’affichage qui appartient à l’une de ses entrées.
Si un conteneur ne prend pas en charge ResolveNames, ResolveName limite la table de contenu du conteneur à l’aide d’une restriction de propriété PR_ANR (PidTagAnr). Cette restriction oblige le conteneur à effectuer un type de recherche « de meilleure estimation » pour localiser un destinataire correspondant. Tous les conteneurs doivent prendre en charge la restriction de propriété PR_ANR .
Lorsqu’un conteneur retourne un destinataire qui correspond à plusieurs noms, ResolveName affiche une boîte de dialogue si l’indicateur MAPI_DIALOG est défini, ce qui permet à l’utilisateur de sélectionner le nom correct.
Si tous les conteneurs de la propriété PR_AB_SEARCH_PATH ont été appelés et qu’aucune correspondance n’a été trouvée, le destinataire reste non résolu.
Si un ou plusieurs destinataires ne sont pas résolus, ResolveName retourne MAPI_E_NOT_FOUND. Si un ou plusieurs destinataires avaient une résolution ambiguë qui n’a pas pu être résolue avec une boîte de dialogue, ou parce que l’indicateur MAPI_DIALOG n’a pas été défini, ResolveName renvoie MAPI_E_AMBIGUOUS_RECIP. Lorsque certains destinataires sont ambigus et que certains ne peuvent pas être résolus, ResolveName peut retourner l’une ou l’autre valeur d’erreur.
Si un nom ne peut pas être résolu, le client peut créer une adresse unique qui a une adresse et un identificateur d’entrée spécialement mis en forme. Pour plus d’informations sur le format des identificateurs d’entrée unique, consultez Identificateurs d’entrée unique. Pour plus d’informations sur le format des adresses ponctuelles, consultez Adresses ponctuelles.
MAPI prend en charge les chaînes de caractères Unicode pour ADRLIST et les nouveaux paramètres de titre d’entrée sur ResolveName ; si vous définissez l’indicateur MAPI_UNICODE, les propriétés suivantes sont retournées en tant que type PT_UNICODE dans les structures ADRENTRY :
PR_ADDRTYPE (PidTagAddressType)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_EMAIL_ADDRESS (PidTagEmailAddress)
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)
Toutefois, la propriété PR_7BIT_DISPLAY_NAME (PidTag7BitDisplayName) est toujours retournée en tant que type PT_STRING8.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| MAPIABFunctions.cpp |
AddOneOffAddress |
MFCMAPI utilise la méthode ResolveName pour résoudre une adresse unique avant de l’ajouter à un message. |
| MAPIABFunctions.cpp |
AddRecipient |
MFCMAPI utilise la méthode ResolveName pour rechercher une entrée de carnet d’adresses par nom complet. |