IABProvider::Logon
S’applique à : Outlook 2013 | Outlook 2016
Établit une connexion à une session active.
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
);
Paramètres
lpMAPISup
[in] Pointeur vers l’objet de prise en charge du fournisseur de carnets d’adresses.
ulUIParam
[in] Handle de la fenêtre parente pour la boîte de dialogue d’ouverture de session que la méthode Logon affiche, si elle est autorisée. Le paramètre ulUIParam contient la valeur du paramètre du même nom passé à MAPI lors de l’appel précédent à la fonction MAPILogonEx .
lpszProfileName
[in] Pointeur vers le nom du profil de session.
ulFlags
[in] Masque de bits d’indicateurs qui contrôle la façon dont l’ouverture de session est effectuée. Les indicateurs suivants peuvent être définis :
AB_NO_DIALOG
Le fournisseur ne doit pas afficher de boîte de dialogue pendant l’ouverture de session. Si cet indicateur n’est pas défini, le fournisseur peut afficher une boîte de dialogue pour inviter l’utilisateur à fournir des informations de configuration manquantes.
MAPI_DEFERRED_ERRORS
Permet à l’ouverture de session de revenir correctement, éventuellement avant la fin du processus d’ouverture de session.
MAPI_UNICODE
Toutes les chaînes doivent être au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, les chaînes doivent être au format ANSI.
lpulcbSecurity
[in, out] Pointeur vers la taille, en octets, de la structure d’informations d’identification de sécurité pointée par le paramètre lppbSecurity . En entrée, la valeur doit être différente de zéro ; dans la sortie, la valeur doit être égale à zéro. Dans les deux cas, les pointeurs doivent être valides.
lppbSecurity
[in, out] Pointeur vers un pointeur vers les informations d’identification de sécurité. En entrée, la valeur doit être différente de zéro ; dans la sortie, la valeur doit être égale à zéro. Dans les deux cas, le pointeur doit être valide.
lppMAPIError
[out] Pointeur vers un pointeur vers une structure MAPIERROR . Le paramètre lppMAPIError peut être défini sur NULL s’il n’existe aucune structure MAPIERROR à retourner.
lppABLogon
[out] Pointeur vers un pointeur vers l’objet d’ouverture de session du fournisseur.
Valeur renvoyée
S_OK
Une connexion à une session active a été établie avec succès.
MAPI_E_FAILONEPROVIDER
Le fournisseur ne peut pas se connecter, mais MAPI peut continuer à se connecter aux autres fournisseurs dans le service de messagerie auquel appartient le fournisseur.
MAPI_E_UNCONFIGURED
Le fournisseur ne dispose pas d’informations suffisantes pour terminer l’ouverture de session. MAPI appelle la fonction d’entrée du service de messagerie du fournisseur.
MAPI_E_UNKNOWN_CPID
Le serveur n’est pas configuré pour prendre en charge la page de codes du client.
MAPI_E_UNKNOWN_LCID
Le serveur n’est pas configuré pour prendre en charge les informations de paramètres régionaux du client.
MAPI_E_USER_CANCEL
L’utilisateur a annulé l’opération, généralement en cliquant sur le bouton Annuler dans la boîte de dialogue d’ouverture de session.
Remarques
Connections sont établies avec chaque fournisseur de carnet d’adresses dans le profil de session lorsqu’un client appelle la méthode IMAPISession ::OpenAddressBook. OpenAddressBook appelle ensuite la méthode Logon de chaque fournisseur.
Le nom de profil pointé par le paramètre lpszProfileName s’affiche dans le jeu de caractères du client de l’utilisateur, comme indiqué par la présence ou l’absence de l’indicateur MAPI_UNICODE dans le paramètre ulFlags .
Remarques pour les responsables de l’implémentation
Dans votre implémentation de la méthode Logon , appelez la méthode IMAPISupport ::SetProviderUID pour inscrire un identificateur unique ou une structure MAPIUID . Chacun de vos objets aura un identificateur d’entrée qui inclut ce MAPIUID. MAPI utilise MAPIUID pour faire correspondre un objet à son fournisseur. Par exemple, lorsqu’un client appelle la méthode IMAPISession ::OpenEntry pour ouvrir un utilisateur de messagerie, OpenEntry examine la partie MAPIUID de l’identificateur d’entrée qui a été transmis et la fait correspondre à un MAPIUID inscrit par un fournisseur de carnet d’adresses.
Si un client se connecte à votre fournisseur plusieurs fois, vous pouvez inscrire un MAPIUID différent pour chaque ouverture de session. L’inscription de structures MAPIUID uniques permet à MAPI d’acheminer correctement les demandes vers le fournisseur approprié instance. Toutefois, vous souhaiterez peut-être que chaque objet d’ouverture de session partage un MAPIUID. Dans ce cas, vous devez être en mesure de gérer le routage vous-même au lieu de vous appuyer sur MAPI. Pour plus d’informations sur la création d’un MAPIUID, consultez Inscription d’identificateurs uniques de fournisseur de services.
L’objet de support que MAPI transmet à votre méthode Logon dans le paramètre lpMAPISup permet d’accéder à la plupart des méthodes incluses dans l’interface IMAPISupport : IUnknown . MAPI crée un objet de support personnalisé en fonction de votre type de fournisseur. Par exemple, si vous devez vous connecter à un système de messagerie ou à un service d’annuaire sous-jacent lorsque vous établissez votre connexion, vous pouvez appeler la méthode IMAPISupport ::OpenProfileSection pour récupérer les informations d’identification de sécurité pour cette session de connexion particulière.
Si l’ouverture de session réussit, veillez à appeler la méthode IUnknown ::AddRef de l’objet de support pour incrémenter son nombre de références. Cela permet à votre fournisseur de conserver le pointeur d’objet de support pour le reste de la session. Si vous n’appelez pas cette méthode AddRef , MAPI déchargera votre fournisseur.
Vous pouvez inclure le nom de profil passé dans le paramètre lpszProfileName dans les boîtes de dialogue d’erreur, les écrans d’ouverture de session ou d’autres interfaces utilisateur. Pour utiliser le nom du profil, copiez-le dans le stockage que vous avez alloué.
Créez un objet d’ouverture de session et retournez un pointeur vers celui-ci dans le paramètre lppABLogon . MAPI utilise cet objet d’ouverture de session pour effectuer des appels aux méthodes dans votre implémentation IABLogon .
Si vous avez besoin d’un mot de passe lors de l’ouverture de session, affichez une boîte de dialogue d’ouverture de session uniquement si l’indicateur AB_NO_DIALOG n’est pas défini. Si l’utilisateur annule le processus d’ouverture de session, généralement en cliquant sur le bouton Annuler dans la boîte de dialogue, retournez MAPI_E_USER_CANCEL à partir de Ouverture de session.
En règle générale, lorsqu’un fournisseur de carnet d’adresses ne peut pas se connecter, MAPI désactive le service de messagerie auquel appartient le fournisseur défaillant, autrement dit, MAPI n’essaie pas d’établir de connexions pour les autres fournisseurs qui appartiennent au service pendant le reste de la durée de vie de la session. Toutefois, si votre fournisseur ne peut pas établir de connexion et que vous ne souhaitez pas désactiver l’ensemble du service, retournez MAPI_E_FAILONEPROVIDER ou MAPI_E_UNCONFIGURED. MAPI ne désactive pas le service de messagerie auquel appartient le fournisseur.
Retournez MAPI_E_FAILONEPROVIDER si une erreur qui n’est pas suffisamment grave pour empêcher les autres fournisseurs du service de messagerie d’établir des connexions. Retournez MAPI_E_UNCONFIGURED si les informations de configuration nécessaires sont manquantes dans le profil et que vous ne pouvez pas afficher une boîte de dialogue pour inviter l’utilisateur. MAPI répond en appelant la fonction de point d’entrée du service de messagerie de votre fournisseur avec MSG_SERVICE_CONFIGURE défini comme paramètre ulContext pour permettre au service de se configurer lui-même, par programmation ou à l’aide d’une feuille de propriétés. Une fois la fonction de point d’entrée du service de message terminée, MAPI retente l’ouverture de session.