Platform SDK: MAPI

Primary Identity

Most MAPI sessions have a particular service provider that supplies the primary identity for the session. Typically, it is an address book provider, which supplies identity through one of its messaging user objects or distribution lists. In fact, MAPI recommends that message services that include an address book provider use one of its objects for the primary identity. When a service provider that belongs to a message service supplies the primary identity, all of the other service providers in the message service share this identity.

The MAPISVC.INF configuration file has entries relating to identity at both the message service and service provider level. Message service sections must include an entry that states whether or not the service can supply the primary identity; service provider sections include a similar entry only when the provider can supply an identity.

The following table lists the entries that appear in the message service and service provider sections in the MAPISVC.INF file.

Primary identity supplier	PR_RESOURCE_FLAGS setting
Message service	SERVICE_PRIMARY_IDENTITY
Not the message service	SERVICE_NO_PRIMARY_IDENTITY
Service provider	STATUS_PRIMARY_IDENTITY

Although multiple message services can declare their ability to provide a session's primary identity, only one message service is selected to do so. This selection can occur:

When a profile is created.
When a client calls IMsgServiceAdmin::SetPrimaryIdentity to explicitly establish a particular message service as the provider of the session identity.

When a profile is created, MAPI designates the first message service to be configured that includes a provider with the STATUS_PRIMARY_IDENTITY flag set in its PR_RESOURCE_FLAGS property to supply the primary identity. Within the designated message service, the first provider to be configured with this resource flag set is chosen to provide the identity for the service. The STATUS_PRIMARY_IDENTITY flag is cleared for all other providers in the designated service and other message services in the profile. If at any time the provider supplying primary identity is removed from the profile, MAPI assigns the role to the next provider to be configured that can supply identity. This is determined by the appearance of the PR_RESOURCE_FLAGS=STATUS_PRIMARY_IDENTITY entry in the provider's section in MAPISRV.INF.

When a client calls a message service's IMsgServiceAdmin::SetPrimaryIdentity method, it specifies the MAPIUID for a service provider within the target service. The service provider represented by the MAPIUID is assigned to supply the primary identity for the message service and for the session, and all of the other providers in the service will share this identity.

Every provider in the message service responsible for supplying the primary identity updates its row in the status table to include the following properties.

Primary identity property	Set to
PR_IDENTITY_DISPLAY	Display name of the object supplying the primary identity.
PR_IDENTITY_SEARCH_KEY	Search key for the object supplying the primary identity.
PR_IDENTITY_ENTRYID	Entry identifier for the object supplying the primary identity.

To retrieve the entry identifier for the object supplying the primary identity

Call the IMAPISession::QueryIdentity method.
QueryIdentity searches the status table for the row that contains the value STATUS_PRIMARY_IDENTITY in its PR_RESOURCE_FLAGS column and returns the corresponding PR_IDENTITY_ENTRYID as the entry identifier for the primary identity.