IMsgServiceAdmin::SetPrimaryIdentity

The IMsgServiceAdmin::SetPrimaryIdentity method designates a message service to be the supplier of the primary identity for the profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT SetPrimaryIdentity(
  LPMAPIUID lpUID,   
  ULONG ulFlags      
);

Parameters

lpUID: [in] Pointer to the MAPIUID structure holding the unique identifier for the message service to supply the primary identity, or NULL, indicating that SetPrimaryIdentity should clear the current identity.
ulFlags: Reserved; must be zero.

Return Values

S_OK: The message service was successfully assigned the supplier of the primary identity.
MAPI_E_NO_ACCESS: SetPrimaryIdentity attempted to designate a message service that has the SERVICE_NO_PRIMARY_IDENTITY flag set in its PR_RESOURCE_FLAGS property.

Remarks

The IMsgServiceAdmin::SetPrimaryIdentity method establishes a message service as the supplier of the primary identity for the profile. The primary identity is typically the user logged on to the message service. It is represented by three properties:

PR_IDENTITY_DISPLAY

PR_IDENTITY_ENTRYID

PR_IDENTITY_SEARCH_KEY

Every service provider in the designated message service sets these three properties to the display name, entry identifier, and search key of the messaging user that is supplying the primary identity. Clients can retrieve the primary identity's entry identifier by calling IMAPISession::QueryIdentity.

Another property, PR_RESOURCE_FLAGS, is set to STATUS_PRIMARY_IDENTITY for every provider that is a member of the message service supplying the primary identity and to SERVICE_PRIMARY_IDENTITY for the message service. When a service provider cannot supply the primary identity for its message service, it sets PR_RESOURCE_FLAGS to STATUS_NO_PRIMARY_IDENTITY. SetPrimaryIdentity sets the PR_RESOURCE_FLAGS property of each message service that is not supplying the primary identity to SERVICE_NO_PRIMARY_IDENTITY.

Each message service provider that MAPI has information about can establish an identity for each of its users when a client logs on to the service. However, because MAPI supports connections to multiple service providers for each MAPI session, there is no firm definition of a particular user's identity for the MAPI session as a whole; a user's identity depends on which service is involved. Clients can call SetPrimaryIdentity to designate one of the many identities established for a user by message services as the primary identity for that user.