Returns the entry identifier of the object that provides the primary identity for the session.
[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.
[out] A pointer to a pointer to the entry identifier of the object that provides the primary identity.
The primary identity was successfully returned.
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. For more information, see Using Macros for Error Handling.
The IMAPISession::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 that supplies the primary identity sets the following items:
The STATUS_PRIMARY_IDENTITY flag in the PR_RESOURCE_FLAGS (PidTagResourceFlags) property.
The PR_IDENTITY_DISPLAY (PidTagIdentityDisplay) property.
The PR_IDENTITY_ENTRYID (PidTagIdentityEntryId) property.
The PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey) property.
If the service provider that supplies 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.
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 about this alternate way of retrieving identity information, see Status Table and Status Objects.
When you are 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 MAPI Primary Identity.
For more information about retrieving MAPI session identity, see Retrieving Primary and Provider Identity.