IMAPISession::QueryIdentity

Article
03/15/2024

S’applique à : Outlook 2013 | Outlook 2016

Retourne l’identificateur d’entrée de l’objet qui fournit l’identité principale pour la session.

HRESULT QueryIdentity(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Paramètres

lpcbEntryID

[out] Pointeur vers le nombre d’octets dans l’identificateur d’entrée vers lequel pointe le paramètre lppEntryID .

lppEntryID

[out] Pointeur vers un pointeur vers l’identificateur d’entrée de l’objet qui fournit l’identité principale.

Valeur renvoyée

S_OK

L’identité principale a été retournée avec succès.

MAPI_W_NO_SERVICE

L’appel a réussi, mais il n’y a pas d’identité principale pour la session. 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.

Remarques

La méthode IMAPISession ::QueryIdentity récupère l’identité principale de la session active et retourne la valeur via le paramètre lppEntryID . L’identité principale est un objet, généralement un utilisateur de messagerie, qui représente l’utilisateur d’une session. lppEntryID renvoie l’identité principale d’un objet IMailUser , qui est également stocké en tant que propriété PidTagEntryID . Vous pouvez utiliser la valeur retournée dans lppEntryID pour ouvrir un objet IMailUser à l’aide de IMAPISession ::OpenEntry.

Bien que de nombreux fournisseurs de services dans plusieurs services de messagerie puissent fournir l’identité principale pour une session, MAPI désigne un fournisseur de services unique. Le fournisseur de services qui fournit l’identité principale définit les éléments suivants :

Indicateur STATUS_PRIMARY_IDENTITY dans la propriété PR_RESOURCE_FLAGS (PidTagResourceFlags).
Propriété PR_IDENTITY_DISPLAY (PidTagIdentityDisplay).
Propriété PR_IDENTITY_ENTRYID (PidTagIdentityEntryId).
Propriété PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey).

Si le fournisseur de services qui fournit l’identité principale appartient à un service de messagerie, les autres fournisseurs de services du service de messagerie définissent également les propriétés PR_IDENTITY. Ces propriétés sont publiées dans la table status de la session.

Si possible, QueryIdentity renvoie la valeur de la propriété PR_IDENTITY_ENTRYID à partir de la ligne status étiquetée avec STATUS_PRIMARY_IDENTITY. Si la propriété PR_IDENTITY_ENTRYID est manquante dans la ligne d’identité principale, QueryIdentity retourne un identificateur d’entrée unique créé avec d’autres informations de cette ligne.

Si l’indicateur STATUS_PRIMARY_IDENTITY est manquant dans toutes les colonnes PR_RESOURCE_FLAG de la table status, QueryIdentity renvoie le premier identificateur d’entrée trouvé. Lorsqu’il n’existe aucun identificateur d’entrée approprié à renvoyer, QueryIdentity réussit avec l’avertissement MAPI_W_NO_SERVICE et pointe lppEntryID vers un identificateur d’entrée codé en dur.

Remarques pour les appelants

Vous pouvez appeler la méthode IMsgServiceAdmin ::SetPrimaryIdentity pour affecter à un service de message la tâche de fournir l’identité principale de la session.

Une autre façon de récupérer l’identité principale consiste à rechercher dans la table status la ligne avec les colonnes PR_RESOURCE_FLAGS définies sur STATUS_PRIMARY_IDENTITY. Pour plus d’informations sur cette autre façon de récupérer les informations d’identité, consultez Table d’état et Objets d’état.

Lorsque vous avez terminé d’utiliser l’identificateur d’entrée pour l’identité principale retournée par QueryIdentity, libérez sa mémoire en appelant la fonction MAPIFreeBuffer .

Pour plus d’informations sur l’identité en général, consultez Identité principale MAPI.

Pour plus d’informations sur la récupération de l’identité de session MAPI, consultez Récupération de l’identité principale et du fournisseur.

Référence MFCMAPI

Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.

Fichier	Fonction	Commentaire
MainDlg.cpp	CMainDlg ::OnQueryIdentity	MFCMAPI utilise la méthode IMAPISession ::QueryIdentity pour ouvrir l’entrée du carnet d’adresses pour l’identité principale de la session.