Retrieving Primary and Provider Identity

Service providers, typically address book providers, have the option of supplying an identity that can be used to represent the session in a variety of situations. Three properties describe a provider's identity:

PR_IDENTITY_ENTRYID

PR_IDENTITY_DISPLAY

PR_IDENTITY_SEARCH_KEY

These properties are set to the entry identifier, display name, and search key of the corresponding identity object, which is typically a messaging user. Providers that supply an identity also set the STATUS_PRIMARY_IDENTITY flag in their PR_RESOURCE_FLAGS property.

Depending on your needs, you might use a particular provider's identity or the primary identity for the session. For example, you can use the primary identity to include it on printouts. You can use a provider's identity also for display purposes or to retrieve properties, such as PR_RESOURCE_PATH. PR_RESOURCE_PATH, if set, contains the path to files used or created by the provider. Retrieve the PR_RESOURCE_PATH property for the provider supplying the primary identity when you want to locate files that pertain to the user of the session.

    To retrieve the identity of a specific provider

1. Call IMAPISession::GetStatusTable to access the status table.
2. Build a restriction using an SPropertyRestriction structure to match the PR_PROVIDER_DLL_NAME column with the name of the specified provider.
3. Call IMAPITable::FindRow to locate the provider's row. The provider's identity will be stored in the PR_IDENTITY_ENTRYID column, if it exists.

    To retrieve the primary identity for a session

• Call IMAPISession::QueryIdentity.

  QueryIdentity bases session identity on the existence of the STATUS_PRIMARY_IDENTITY value in the PR_RESOURCE_FLAGS column for one of the rows in the status table. If none of the status rows have this value set, QueryIdentity assigns identity to the first service provider that sets the three PR_IDENTITY properties. If no service provider supplies an identity, QueryIdentity returns MAPI_W_NO_SERVICE. When this happens, you should create a character string to represent a generic user that can serve as the primary identity.

Note Do not call QueryIdentity during session start up; it will unnecessarily increase the amount of time it takes to start your session. This is because to access the status table and query for the PR_IDENTITY properties, the MAPI spooler must be available. The extra time it takes to start up the MAPI spooler will add to your start up time.

    To explicitly set the primary identity for a session

• Call IMsgServiceAdmin::SetPrimaryIdentity. Pass the MAPIUID for the target service provider.