IMAPISession::QueryIdentity

The IMAPISession::QueryIdentity method returns the entry identifier of the object that provides the primary identity for the session.

Quick Info

See IMAPISession : IUnknown.

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

Parameters

lpcbEntryID: [out] Pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.
lppEntryID: [out] Pointer to a pointer to the entry identifier of the object providing the primary identity.

Return Values

S_OK: The primary identity was successfully returned.
MAPI_W_NO_SERVICE: The call succeeded, but there is no primary identity for the session. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPSession::QueryIdentity method retrieves the primary identity for the current session. The primary identity is an object, typically a messaging user, that represents the user of a session. Although many service providers in multiple message services can provide the primary identity for a session, MAPI designates a single service provider. The service provider supplying the primary identity sets the following:

STATUS_PRIMARY_IDENTITY flag in the PR_RESOURCE_FLAGS property
PR_IDENTITY_DISPLAY
PR_IDENTITY_ENTRYID
PR_IDENTITY_SEARCH_KEY

If the service provider supplying the primary identity belongs to a message service, the other service providers in the message service also set the PR_IDENTITY properties. These properties are published in the session's status table.

If possible, QueryIdentity returns the value for the PR_IDENTITY_ENTRYID property from the status row tagged with STATUS_PRIMARY_IDENTITY. If the PR_IDENTITY_ENTRYID property is missing from the primary identity row, QueryIdentity returns a one-off entry identifier built with other information from that row.

If the STATUS_PRIMARY_IDENTITY flag is missing from all of the PR_RESOURCE_FLAG columns in the status table, QueryIdentity returns the first entry identifier that it finds. When there is no appropriate entry identifier to return, QueryIdentity succeeds with the warning MAPI_W_NO_SERVICE and points lppEntryID to a hard-coded entry identifier.

Notes to Callers

You can call the IMsgServiceAdmin::SetPrimaryIdentity method to assign a message service the task of supplying the session's primary identity.

Another way to retrieve the primary identity is by searching the status table for the row with the PR_RESOURCE_FLAGS columns set to STATUS_PRIMARY_IDENTITY. For more information on this alternate way of retrieving identity information, see Using the Status Table and Status Objects.

When you have finished using the entry identifier for the primary identity returned by QueryIdentity, free its memory by calling the MAPIFreeBuffer function.

For more information about identity in general, see Primary Identity.

For more information about retrieving MAPI session identity, see Retrieving Primary and Provider Identity.