IXPProvider::TransportLogon
S’applique à : Outlook 2013 | Outlook 2016
Établit une session dans laquelle une application cliente se connecte à un fournisseur de transport.
HRESULT TransportLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
);
Paramètres
lpMAPISup : [in] Pointeur vers l’objet de prise en charge du fournisseur de transport pour les fonctions de rappel dans MAPI pour cette session. Cet objet reste valide jusqu’à ce que le fournisseur de transport le libère.
ulUIParam : [in] Gérez la fenêtre parente de toutes les boîtes de dialogue ou fenêtres affichées par cette méthode. Le paramètre ulUIParam peut être non null, par exemple lorsque l’indicateur LOGON_SETUP est défini dans le paramètre lpulFlags .
lpszProfileName : [in] Pointeur vers le nom de profil de l’utilisateur. Le paramètre lpszProfileName est principalement utilisé lorsqu’une boîte de dialogue doit être présentée.
lpulFlags : [in, out] Masque de bits des indicateurs qui contrôle la façon dont la session d’ouverture de session est établie. Les indicateurs suivants peuvent être définis lors de l’entrée par le spouleur MAPI :
LOGON_NO_CONNECT : le compte d’utilisateur se connecte à ce fournisseur de transport à des fins autres que la transmission et la réception de messages. Le fournisseur de transport ne doit pas tenter d’établir de connexions à d’autres systèmes de messagerie.
LOGON_NO_DIALOG : aucune boîte de dialogue ne doit s’afficher même si les informations d’identification de l’utilisateur actuellement enregistrées ne sont pas valides ou insuffisantes pour l’ouverture de session.
LOGON_NO_INBOUND : le fournisseur de transport n’a pas besoin de s’initialiser pour la réception des messages et ne doit pas accepter les messages entrants. Le spouleur MAPI peut utiliser la méthode IXPLogon ::TransportNotify ultérieurement pour signaler au fournisseur de transport l’activation du traitement des messages entrants.
LOGON_NO_OUTBOUND : le fournisseur de transport n’a pas besoin de s’initialiser pour envoyer des messages, car le spouleur MAPI n’en fournit pas. Si une application cliente nécessite une connexion à un fournisseur distant lors de la composition d’un message afin qu’elle puisse effectuer des appels de méthode IXPLogon ::AddressTypes , le fournisseur de transport doit établir la connexion. Le spouleur MAPI peut utiliser TransportNotify pour signaler au fournisseur de transport quand les opérations sortantes peuvent commencer.
MAPI_UNICODE : la chaîne transmise pour le nom de profil est au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, la chaîne est au format ANSI.
Les indicateurs suivants peuvent être définis sur la sortie par le fournisseur de transport :
LOGON_SP_IDLE : demande que le spouleur MAPI appelle fréquemment la méthode IXPLogon ::Idle du fournisseur de transport pour le traitement au moment de l’inactivité.
LOGON_SP_POLL : demande que le spouleur MAPI appelle fréquemment la méthode IXPLogon ::P oll sur l’objet d’ouverture de session renvoyé pour case activée pour les nouveaux messages. Si cet indicateur n’est pas défini, le spouleur MAPI recherche uniquement les nouveaux messages lorsque le fournisseur de transport utilise la méthode IMAPISupport ::SpoolerNotify pour informer le spouleur qu’il y a de nouveaux messages à traiter. Un fournisseur de transport devient en fait l’envoi uniquement en ne définissant pas cet indicateur et en n’informant pas le spouleur MAPI de la réception du message.
LOGON_SP_RESOLVE : demande que le spouleur MAPI résolve en adresses complètes toutes les adresses de message pour les destinataires non pris en charge par ce fournisseur de transport. Par conséquent, le fournisseur de transport peut construire un chemin de réponse pour tous les destinataires.
MAPI_UNICODE : les chaînes retournées dans la structure MAPIERROR , le cas échéant, sont au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, les chaînes sont au format ANSI.
lppMAPIError : [out] Pointeur vers un pointeur vers la structure MAPIERROR retournée, le cas échéant, qui contient des informations de version, de composant et de contexte pour l’erreur. Le paramètre lppMAPIError peut être défini sur NULL s’il n’existe aucune structure MAPIERROR à retourner.
lppXPLogon : [out] Pointeur vers le pointeur vers l’objet d’ouverture de session du fournisseur de transport retourné.
Valeur renvoyée
S_OK : l’appel a réussi et a retourné la ou les valeurs attendues.
MAPI_E_FAILONEPROVIDER : ce fournisseur ne peut pas se connecter, mais cette erreur ne doit pas désactiver le service.
MAPI_E_UNCONFIGURED : le profil ne contient pas suffisamment d’informations pour que l’ouverture de session soit terminée. MAPI appelle la fonction de point d’entrée du service de messagerie du fournisseur.
MAPI_E_UNKNOWN_CPID : le fournisseur ne peut pas prendre en charge la page de codes du client.
MAPI_E_UNKNOWN_LCID : le fournisseur ne peut pas 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 une boîte de dialogue.
Remarques
Le spouleur MAPI appelle la méthode IXPProvider ::TransportLogon pour établir une session d’ouverture de session pour un utilisateur.
La plupart des fournisseurs de transport utilisent la méthode IMAPISupport ::OpenProfileSection fournie avec l’objet de support désigné par le paramètre lpMAPISup pour enregistrer et récupérer les informations d’identité utilisateur, les adresses de serveur et les informations d’identification. À l’aide d’OpenProfileSection, un fournisseur de transport peut enregistrer des informations arbitraires et les associer à une connexion à une ressource particulière. Par exemple, un fournisseur peut utiliser OpenProfileSection pour enregistrer le nom de compte et le mot de passe associés à une session particulière, ainsi que les noms de serveurs ou autres informations nécessaires pour accéder aux ressources de cette session. MAPI masque les informations associées à une ressource d’un accès externe. La section de profil mise à disposition via lpMAPISup est gérée par le spouleur MAPI de sorte que les données liées à ce contexte utilisateur sont séparées des données pour les autres contextes.
Le fournisseur de transport doit appeler la méthode IUnknown ::AddRef sur l’objet de prise en charge et conserver une copie du pointeur vers cet objet dans le cadre de l’objet d’ouverture de session du fournisseur.
Le nom complet du profil dans lpszProfileName est fourni afin que le fournisseur de transport puisse l’utiliser dans les messages d’erreur ou les boîtes de dialogue d’ouverture de session. Si le fournisseur conserve ce nom, il doit être copié dans le stockage alloué par le fournisseur.
Les fournisseurs de transport étroitement couplés à d’autres fournisseurs de services peuvent devoir effectuer des tâches supplémentaires lors de l’ouverture de session pour établir les informations d’identification correctes requises pour les opérations entre les fournisseurs compagnons.
En règle générale, les fournisseurs de transport sont ouverts lorsque l’utilisateur se connecte pour la première fois à un profil. Étant donné que la première ouverture de session d’un profil arrive généralement avant l’ouverture de session à n’importe quelle banque de messages, le spouleur MAPI appelle généralement TransportLogon avec les indicateurs LOGON_NO_INBOUND et LOGON_NO_OUTBOUND définis dans lpulFlags. Plus tard, lorsque les magasins de messages appropriés sont disponibles dans la session de profil, le spouleur MAPI appelle TransportNotify pour lancer des opérations entrantes et sortantes pour le fournisseur de transport.
Le passage de l’indicateur LOGON_NO_CONNECT dans lpulFlags signale l’opération hors connexion du fournisseur de transport. Cet indicateur indique qu’aucune connexion externe ne doit être établie. si le fournisseur de transport ne peut pas établir une session sans connexion externe, il doit retourner une valeur d’erreur pour l’ouverture de session.
Un fournisseur de transport doit définir l’indicateur LOGON_SP_IDLE dans lpulFlags au moment de l’initialisation s’il est conçu pour utiliser le temps que le système passe sinon inactif. Ce temps est souvent utilisé pour gérer des opérations automatiques, telles que le téléchargement automatique de messages, le téléchargement de messages chronotés ou l’envoi de messages chronotés. Si cet indicateur est défini, le spouleur MAPI appelle Inactif lorsque le temps d’inactivité du système se produit pour lancer ces opérations. Le spouleur MAPI n’appelle pas Idle à des intervalles définis ; au lieu de cela, il est appelé uniquement pendant le temps d’inactivité réel. Par conséquent, les fournisseurs ne doivent pas travailler sur une hypothèse sur la fréquence à laquelle leurs méthodes inactives seront appelées. Les fournisseurs qui prennent en charge les opérations en temps d’inactivité doivent fournir une interface utilisateur de configuration dans leur feuille de propriétés du fournisseur.
Si l’ouverture de session du fournisseur de transport réussit, le fournisseur doit retourner dans le paramètre lppXPLogon un pointeur vers un objet d’ouverture de session. Le spouleur MAPI utilise cet objet pour un accès fournisseur supplémentaire. Si TransportLogon affiche une boîte de dialogue d’ouverture de session et que l’utilisateur annule l’ouverture de session généralement en cliquant sur le bouton Annuler dans la boîte de dialogue, le fournisseur doit retourner MAPI_E_USER_CANCEL.
Pour la plupart des valeurs d’erreur retournées par TransportLogon, MAPI désactive les services de messagerie auxquels appartient le fournisseur. MAPI n’appellera aucun fournisseur appartenant à ce service pour le reste de la session MAPI. En revanche, lorsque TransportLogon retourne la valeur d’erreur MAPI_E_FAILONEPROVIDER à partir de son ouverture de session, MAPI ne désactive pas le service de message auquel appartient le fournisseur. TransportLogon doit retourner MAPI_E_FAILONEPROVIDER s’il rencontre une erreur qui ne justifie pas la désactivation du service pour le reste de la session.
Si un fournisseur retourne MAPI_E_UNCONFIGURED à partir de son ouverture de session, MAPI appelle la fonction d’entrée du service de messagerie du fournisseur, puis recommencez l’ouverture de session. MAPI transmet MSG_SERVICE_CONFIGURE comme contexte, pour permettre au service de se configurer lui-même. Si le client a choisi d’autoriser une interface utilisateur sur l’ouverture de session, le service peut présenter sa feuille de propriétés de configuration afin que l’utilisateur puisse entrer des informations de configuration.
Si le fournisseur constate que toutes les informations requises ne se trouvent pas dans le profil, il doit retourner MAPI_E_UNCONFIGURED afin que MAPI appelle la fonction de point d’entrée du service de messagerie du fournisseur.