IMSProvider::Logon

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Enregistre MAPI sur une instance d’un fournisseur de magasin de messages.

HRESULT Logon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  LPCIID lpInterface,
  ULONG FAR * lpcbSpoolSecurity,
  LPBYTE FAR * lppbSpoolSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPMSLOGON FAR * lppMSLogon,
  LPMDB FAR * lppMDB
);

Paramètres

lpMAPISup

[in] Pointeur vers l’objet de prise en charge MAPI actuel pour la banque de messages.

ulUIParam

[in] Handle de la fenêtre parente de toutes les boîtes de dialogue ou fenêtres affichées par cette méthode.

lpszProfileName

[in] Pointeur vers une chaîne qui contient le nom du profil utilisé pour l’ouverture de session du fournisseur de magasin. Cette chaîne peut être affichée dans des boîtes de dialogue, écrite dans un fichier journal ou simplement ignorée. Il doit être au format Unicode si l’indicateur MAPI_UNICODE est défini dans le paramètre ulFlags .

cbEntryID

[in] Taille, en octets, de l’identificateur d’entrée pointé par le paramètre lpEntryID .

lpEntryID

[in] Pointeur vers l’identificateur d’entrée de la banque de messages. Le passage de null dans lpEntryID indique qu’une banque de messages n’a pas encore été sélectionnée et que des boîtes de dialogue permettant à l’utilisateur de sélectionner une banque de messages peuvent être affichées.

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 :

MAPI_DEFERRED_ERRORS

L’appel est autorisé à réussir même si l’objet sous-jacent n’est pas disponible pour l’implémentation appelante. Si l’objet n’est pas disponible, un appel ultérieur à l’objet peut générer une erreur.

MAPI_UNICODE

Les chaînes transmises sont au format Unicode. Si MAPI_UNICODE n’est pas défini, les chaînes sont au format ANSI.

MDB_NO_DIALOG

Empêche l’affichage des boîtes de dialogue d’ouverture de session. Si cet indicateur est défini, la valeur d’erreur MAPI_E_LOGON_FAILED est retournée si l’ouverture de session échoue. Si cet indicateur n’est pas défini, le fournisseur de la banque de messages peut inviter l’utilisateur à corriger un nom ou un mot de passe, à insérer un disque ou à effectuer d’autres actions nécessaires pour établir la connexion au magasin.

MDB_NO_MAIL

La banque de messages ne doit pas être utilisée pour envoyer ou recevoir des messages. L’indicateur indique à MAPI de ne pas informer le spouleur MAPI que cette banque de messages est en cours d’ouverture. Si cet indicateur est défini et que la banque de messages est étroitement couplée à un fournisseur de transport, le fournisseur n’a pas besoin d’appeler la méthode IMAPISupport ::SpoolerNotify .

MDB_TEMPORARY

Journaux sur le magasin afin que les informations puissent être récupérées par programmation à partir de la section de profil, sans utiliser de boîtes de dialogue. Cet indicateur indique à MAPI que le magasin ne doit pas être ajouté à la table de la banque de messages et qu’il ne peut pas être rendu permanent. Si cet indicateur est défini, les fournisseurs de magasins de messages n’ont pas besoin d’appeler la méthode IMAPISupport ::ModifyProfile .

MDB_WRITE

Demande l’autorisation de lecture/écriture.

lpInterface

[in] Pointeur vers l’identificateur d’interface (IID) de la banque de messages à laquelle se connecter. Le passage de la valeur Null indique que l’interface MAPI pour la banque de messages ( IMsgStore) est retournée. Le paramètre lpInterface peut également être défini sur un identificateur pour une interface appropriée pour la banque de messages (par exemple, IID_IUnknown ou IID_IMAPIProp).

lpcbSpoolSecurity

[out] Pointeur vers la variable dans laquelle le fournisseur de magasin retourne la taille, en octets, des données de validation dans le paramètre lppbSpoolSecurity .

lppbSpoolSecurity

[out] Pointeur vers le pointeur vers les données de validation retournées. Ces données de validation sont fournies afin que la méthode IMSProvider ::SpoolerLogon puisse enregistrer le spouleur MAPI dans le même magasin que le fournisseur de la banque de messages.

lppMAPIError

[out] Pointeur vers un pointeur vers la structure MAPIERROR retournée, le cas échéant, qui contient des informations sur la version, le composant et le contexte d’une erreur. Le paramètre lppMAPIError peut être défini sur null s’il n’existe aucune structure MAPIERROR à retourner.

lppMSLogon

[out] Pointeur vers le pointeur vers l’objet d’ouverture de session de la banque de messages auquel MAPI doit se connecter.

lppMDB

[out] Pointeur vers le pointeur vers l’objet de magasin de messages pour le spouleur MAPI et les applications clientes auxquelles se connecter.

Valeur renvoyée

S_OK

L'appel a r�ussi et a renvoy� la valeur attendue ou les valeurs.

MAPI_E_FAILONEPROVIDER

Ce fournisseur ne peut pas se connecter, mais cette erreur ne doit pas désactiver le service.

MAPI_E_LOGON_FAILED

Impossible d’établir une session d’ouverture de session.

MAPI_E_UNCONFIGURED

Le profil ne contient pas suffisamment d’informations pour que l’ouverture de session se termine. Lorsque cette valeur est retournée, MAPI appelle la fonction de point d’entrée de service de messagerie du fournisseur de magasin de messages.

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.

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_W_ERRORS_RETURNED

L’appel a réussi, mais le fournisseur de magasin de messages a des informations d’erreur disponibles. Lorsque cet avertissement est retourné, l’appel doit être géré comme ayant réussi. Pour tester cet avertissement, utilisez la macro HR_FAILED . Pour plus d’informations, consultez Utilisation de macros pour la gestion des erreurs. Pour obtenir les informations d’erreur auprès du fournisseur, appelez la méthode IMAPISession ::GetLastError .

Remarques

MAPI appelle la méthode IMSProvider ::Logon pour effectuer la majorité du traitement nécessaire pour obtenir l’accès à une banque de messages. Les fournisseurs de magasins de messages valident toutes les informations d’identification utilisateur nécessaires pour accéder à un magasin particulier et retournent un objet de magasin de messages dans le paramètre lppMDB auquel le spouleur MAPI et les applications clientes peuvent se connecter.

En plus de l’objet de magasin de messages retourné pour l’utilisation du client et du spouleur MAPI, le fournisseur retourne également un objet d’ouverture de session de magasin de messages que MAPI doit utiliser pour contrôler le magasin ouvert. L’objet d’ouverture de session de la banque de messages et l’objet de magasin de messages doivent être étroitement liés à l’intérieur du fournisseur de la banque de messages afin que chacun puisse affecter l’autre. L’utilisation de l’objet store et de l’objet d’ouverture de session doit être identique ; il doit y avoir une correspondance un-à-un entre l’objet d’ouverture de session et l’objet store, de sorte que les objets agissent comme s’il s’agit d’un seul objet qui expose deux interfaces. Les deux objets doivent également être créés ensemble et libérés ensemble.

L’objet de prise en charge MAPI, créé par MAPI et transmis au fournisseur dans le paramètre lpMAPISup , fournit l’accès aux fonctions dans MAPI dont le fournisseur a besoin. Il s’agit notamment des fonctions qui enregistrent et récupèrent les informations de profil, accèdent aux carnets d’adresses, etc. Le pointeur lpMAPISup peut être différent pour chaque magasin ouvert. Lors du traitement des appels d’une banque de messages après l’ouverture de session, le fournisseur de magasin doit utiliser la variable lpMAPISup spécifique à ce magasin. Pour tout appel d’ouverture de session qui ouvre une banque de messages et réussit à créer un objet d’ouverture de session de la banque de messages, le fournisseur doit enregistrer un pointeur vers l’objet de prise en charge MAPI dans l’objet d’ouverture de session du magasin et appeler la méthode IUnknown ::AddRef pour ajouter une référence pour l’objet de prise en charge.

Le paramètre ulUIParam doit être utilisé si le fournisseur présente des boîtes de dialogue pendant l’appel d’ouverture de session. Toutefois, les boîtes de dialogue ne doivent pas être affichées si ulFlags contient l’indicateur MDB_NO_DIALOG. Si une interface utilisateur doit être appelée mais que ulFlags ne l’autorise pas, ou si, pour une autre raison, une interface utilisateur ne peut pas être affichée, le fournisseur doit retourner MAPI_E_LOGON_FAILED. Si ouverture de session affiche une boîte de dialogue et que l’utilisateur annule l’ouverture de session, généralement en cliquant sur le bouton Annuler de la boîte de dialogue, le fournisseur doit retourner MAPI_E_USER_CANCEL.

Le paramètre lpEntryID peut être null ou pointer vers un identificateur d’entrée de magasin non enregistré précédemment créé par cette banque de messages. Si lpEntryID pointe vers un identificateur d’entrée non enregistré, cet identificateur d’entrée peut provenir de l’un des emplacements suivants :

Il peut s’agir d’un identificateur d’entrée que le fournisseur de magasin a précédemment encapsulé et écrit dans la section de profil en tant que propriété PR_ENTRYID (PidTagEntryId).
Il peut s’agir d’un identificateur d’entrée que le fournisseur a précédemment encapsulé et retourné à un client appelant en tant que propriété PR_STORE_ENTRYID (PidTagStoreEntryId).
Il peut s’agir d’un identificateur d’entrée que le fournisseur a précédemment encapsulé et retourné à un client appelant en tant que propriété PR_ENTRYID d’un objet de magasin de messages.

Dans l’un de ces cas, il est possible que l’identificateur d’entrée ait été créé sur un ordinateur différent de celui actuellement utilisé.

Lorsque lpEntryID n’est pas null, il doit contenir toutes les informations nécessaires pour identifier et localiser la banque de messages. Ces informations peuvent inclure des noms de volume réseau, des numéros de téléphone, des noms de compte d’utilisateur, etc. Si la connexion au magasin ne peut pas être établie à l’aide des données dans l’identificateur d’entrée, le fournisseur de magasin doit afficher une boîte de dialogue qui permet à l’utilisateur de sélectionner le magasin à ouvrir. Une boîte de dialogue peut être nécessaire, par exemple, si un serveur a été renommé, si un nom de compte a changé ou si des parties du réseau ne sont pas disponibles.

Lorsque lpEntryID a la valeur null, la banque de messages à utiliser n’a pas encore été sélectionnée. Le fournisseur peut toujours accéder à un magasin sans afficher de boîte de dialogue s’il prend en charge d’autres méthodes pour spécifier le magasin. Par exemple, le fournisseur peut vérifier son fichier d’initialisation, ou rechercher des propriétés supplémentaires qui ont été placées dans sa section de profil de service de messagerie ou de son service de messagerie au niveau de la configuration.

Si un fournisseur constate que toutes les informations requises ne se trouvent pas dans le profil, il doit retourner MAPI_E_UNCONFIGURED. MAPI appelle ensuite la fonction de point d’entrée du service de messagerie du fournisseur pour permettre à l’utilisateur de sélectionner un magasin, ou même d’en créer un, et d’entrer un nom de compte et un mot de passe, selon les besoins. MAPI crée automatiquement une section de profil pour un nouveau magasin ; cette nouvelle section de profil peut être temporaire ou permanente, selon la façon dont elle a été ajoutée. Si le fournisseur de magasin appelle la méthode IMAPISupport ::ModifyProfile , la nouvelle section de profil devient permanente et la banque est ajoutée à la liste des magasins de messages retournée par la méthode IMAPISession ::GetMsgStoresTable .

Le paramètre lpInterface spécifie l’IID de l’interface requise pour l’objet store nouvellement ouvert. Le passage de null dans lpInterface spécifie que l’interface de magasin de messages MAPI, IMsgStore, est requise. Le passage de l’objet de magasin de messages, IID_IMsgStore, spécifie également qu’IMsgStore est obligatoire. Si IID_IUnknown est passé dans lpInterface, le fournisseur doit ouvrir le magasin à l’aide de l’interface dérivée d’IUnknown qui convient le mieux au fournisseur (là encore, il s’agit généralement d’IMsgStore). Lorsque IID_IUnknown est passé, l’implémentation appelante utilise la méthode IUnknown ::QueryInterface pour sélectionner une interface une fois l’opération d’ouverture du magasin réussie.

L’appel IMSProvider ::Logon doit retourner des informations suffisantes, telles qu’un chemin d’accès au magasin et des informations d’identification pour accéder au magasin, pour permettre au spouleur MAPI de se connecter au même magasin que le fournisseur de magasin sans présenter de boîte de dialogue. Les paramètres lpcbSpoolSecurity et lppbSpoolSecurity sont utilisés pour retourner ces informations. Le fournisseur alloue la mémoire pour ces données en passant un pointeur vers une mémoire tampon dans le paramètre lpfAllocateBuffer de la fonction MSProviderInit ; le fournisseur place la taille de cette mémoire tampon dans lpcbSpoolSecurity.

MAPI libère cette mémoire tampon le cas échéant. Si l’ouverture de session du spouleur MAPI au magasin peut être effectuée à partir des informations de la section profil uniquement, le fournisseur peut retourner null dans lppbSpoolSecurity et 0 pour la taille des informations dans lpcbSpoolSecurity. L’ouverture de session du spouleur MAPI se produit dans le cadre d’un processus différent de celui de l’ouverture de session du magasin ; Étant donné que la mémoire tampon qui contient les informations passées est copiée entre les processus, elle peut ne pas être en mémoire au même emplacement pour le processus de spouleur MAPI que pour le processus du fournisseur de magasin. Par conséquent, un fournisseur ne doit pas placer d’adresses dans cette mémoire tampon. Pour plus d’informations sur l’ouverture de session du spouleur MAPI, consultez la méthode IMSProvider ::SpoolerLogon .

La plupart des fournisseurs de magasins utilisent la méthode IMAPISession ::OpenProfileSection de l’objet de support passé dans le paramètre lpMAPISup pour enregistrer et récupérer les informations d’identification et les options de l’utilisateur. OpenProfileSection permet à un fournisseur de magasin d’enregistrer des informations arbitraires supplémentaires dans une section de profil et de les associer à une ressource particulière. Par exemple, un fournisseur de magasin peut enregistrer le nom de compte d’utilisateur et le mot de passe associés à une ressource, ainsi que tous les chemins d’accès ou autres informations nécessaires pour accéder à cette ressource.

Les propriétés avec des identificateurs de propriété 0x6600 via 0x67FF sont des propriétés sécurisées disponibles pour le fournisseur pour son propre usage afin de stocker des données privées dans des sections de profil. Pour plus d’informations sur les utilisations des propriétés dans les objets de section de profil, consultez la méthode IProfSect : IMAPIProp .

En plus des données privées dans les propriétés avec des identificateurs 0x6600 via 0x67FF, le fournisseur de magasin doit fournir des informations pour la propriété PR_DISPLAY_NAME (PidTagDisplayName) dans sa section de profil. Il doit placer PR_DISPLAY_NAME le nom d’affichage du fournisseur lui-même, une chaîne d’identification (par exemple, « Magasin d’informations personnelles Microsoft ») qui est affichée aux utilisateurs afin qu’ils puissent distinguer cette banque de messages des autres auxquels ils peuvent avoir accès. PR_DISPLAY_NAME contient généralement un nom de serveur, un nom de compte d’utilisateur ou un chemin d’accès.

Certaines propriétés de section de profil sont visibles dans la table de la banque de messages ; d’autres sont visibles pendant l’installation, l’installation et la configuration du sous-système MAPI. Le fournisseur fournit généralement des informations pour ces propriétés visibles à la fois pour une nouvelle section de profil, qui n’inclut pas encore d’informations d’identification enregistrées ou privées, et quand il détecte que les informations de propriété ont changé. Pour plus d’informations sur les sections de profil, consultez IMAPISupport ::OpenProfileSection.

Après avoir correctement connecté un utilisateur et avant de revenir à MAPI, le fournisseur de magasin doit créer le tableau de propriétés pour la ligne d’état de la ressource et appeler la méthode IMAPISupport ::ModifyStatusRow .

Les appels d’ouverture de session qui ouvrent des magasins de messages déjà ouverts pour la session MAPI actuelle ignorent une grande partie du traitement décrit précédemment. Ces appels ne créent pas de lignes d’état, ne retournent pas d’objets d’ouverture de session de magasin de messages, n’appellent pas AddRef pour l’objet de prise en charge MAPI ou ne retournent pas de données pour l’ouverture de session du spouleur MAPI. Ces appels retournent S_OK et retournent un objet de magasin de messages avec l’interface demandée.

Pour détecter de tels appels, le fournisseur doit conserver une liste dans l’objet fournisseur de la banque de messages des magasins déjà ouverts pour cet objet fournisseur. Lors du traitement d’un appel d’ouverture de session, le fournisseur doit analyser cette liste de magasins ouverts et déterminer si le magasin à connecter est déjà ouvert. Si tel est le cas, les informations d’identification de l’utilisateur n’ont pas besoin d’être activées et l’affichage d’une boîte de dialogue doit être évité, si possible. Si des boîtes de dialogue doivent être affichées, le fournisseur doit vérifier les informations retournées pour voir si un magasin a été ouvert une deuxième fois. En outre, le fournisseur doit vérifier les ouvertures en double à l’aide de lpEntryID au début du traitement des appels d’ouverture de session.

Le traitement standard d’un appel d’ouverture de session qui accède à un magasin ouvert est le suivant :

Le fournisseur de magasin appelle AddRef pour l’objet de magasin existant si la nouvelle interface demandée est identique à l’interface du magasin existant. Sinon, il appelle QueryInterface pour obtenir la nouvelle interface. Si le magasin ne prend pas en charge la nouvelle interface, le fournisseur doit retourner la valeur d’erreur MAPI_E_INTERFACE_NOT_SUPPORTED.
Le fournisseur retourne un pointeur vers l’interface requise de l’objet store existant dans lppMDB.
Le fournisseur retourne null dans lppMSLogon.
Le fournisseur ne doit pas ouvrir le profil pour l’objet de support passé dans l’appel. En outre, il ne doit pas inscrire un identificateur unique de fournisseur, inscrire une ligne d’état ou retourner les données d’ouverture de session du spouleur MAPI.
Le fournisseur ne doit pas appeler AddRef pour l’objet de prise en charge, car il ne nécessite pas de pointeur vers l’objet .

Dans la mesure du possible, les fournisseurs doivent retourner les chaînes d’erreur et d’avertissement appropriées pour les appels d’ouverture de session, car cela facilite considérablement la tâche des utilisateurs de déterminer pourquoi quelque chose n’a pas fonctionné. Pour retourner ces chaînes, un fournisseur définit les membres dans la structure MAPIERROR . MAPI recherche, utilise et libère la structure MAPIERROR si elle est retournée par un fournisseur.

La mémoire de cette structure MAPIERROR doit être allouée à l’aide de la mémoire tampon passée dans lpfAllocateBuffer sur l’appel MSProviderInit . Toutes les chaînes d’erreur contenues dans la structure retournée doivent être au format Unicode si MAPI_UNICODE est défini dans les ulFlagsd’ouverture de session ; sinon, elles doivent être dans le jeu de caractères ANSI.

Pour la plupart des valeurs d’erreur retournées par l’ouverture de session, MAPI désactive les services de messagerie auxquels appartient le fournisseur défaillant. MAPI n’appellera aucun fournisseur qui appartient à ces services pendant la durée de la session MAPI. En revanche, lorsque l’ouverture de session renvoie la valeur d’erreur MAPI_E_FAILONEPROVIDER de son ouverture de session, MAPI ne désactive pas le service de messagerie auquel appartient le fournisseur. L’ouverture de session doit retourner MAPI_E_FAILONEPROVIDER si elle rencontre une erreur qui ne justifie pas la désactivation de l’ensemble du service pendant la durée de la session. Par exemple, un fournisseur peut retourner cette erreur lorsqu’il n’autorise pas l’affichage d’une interface utilisateur et qu’un mot de passe requis n’est pas disponible.

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.