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.

See also

IMAPISession::OpenEntry

IMsgServiceAdmin::SetPrimaryIdentity

MAPIFreeBuffer

IMAPISession : IUnknown

MFCMAPI as a Code Sample

MAPI Primary Identity

Retrieving Primary and Provider Identity

Using Macros for Error Handling

Status Table and Status Objects