IMAPISession::QueryIdentity

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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. 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.

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

Reference

IMAPISession::OpenEntry

IMsgServiceAdmin::SetPrimaryIdentity

MAPIFreeBuffer

IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample

MAPI Primary Identity

Retrieving Primary and Provider Identity

Using Macros for Error Handling

Status Table and Status Objects