IMAPISession::QueryIdentity
Applies to: Outlook 2013 | Outlook 2016
Returns the entry identifier of the object that provides the primary identity for the session.
HRESULT QueryIdentity(
ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
);
Parameters
lpcbEntryID
[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.
lppEntryID
[out] A pointer to a pointer to the entry identifier of the object that provides the primary identity.
Return value
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. For more information, see Using Macros for Error Handling.
Remarks
The IMAPISession::QueryIdentity method retrieves the primary identity for the current session and returns the value through the lppEntryID parameter. The primary identity is an object, typically a messaging user, that represents the user of a session. lppEntryID returns the primary identity for an IMailUser object, which is also stored as the PidTagEntryID property. You can use the value returned in lppEntryID to open an IMailUser object using IMAPISession::OpenEntry.
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.
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 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.
MFCMAPI reference
For MFCMAPI sample code, see the following table.
| File | Function | Comment |
|---|---|---|
| MainDlg.cpp |
CMainDlg::OnQueryIdentity |
MFCMAPI uses the IMAPISession::QueryIdentity method to open the address book entry for the primary identity of the session. |
See also
IMsgServiceAdmin::SetPrimaryIdentity
Retrieving Primary and Provider Identity