IMsgServiceAdmin::SetPrimaryIdentity
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Designates a message service to be the supplier of the primary identity for the profile.
HRESULT SetPrimaryIdentity(
LPMAPIUID lpUID,
ULONG ulFlags
);
Parameters
lpUID
[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to supply the primary identity, or NULL, which indicates that SetPrimaryIdentity should clear the current identity.ulFlags
[in] Reserved; must be zero.
Return Value
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 (PidTagResourceFlags) 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 who is logged on to the message service. It is represented by three properties:
PR_IDENTITY_DISPLAY (PidTagIdentityDisplay)
PR_IDENTITY_ENTRYID (PidTagIdentityEntryId)
PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey)
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 supplies the primary identity. Clients can retrieve the primary identity's entry identifier by calling the IMAPISession::QueryIdentity method.
The PR_RESOURCE_FLAGS property is set to STATUS_PRIMARY_IDENTITY for every provider that is a member of the message service that supplies 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.