| Platform SDK: MAPI |
A profile stores information about service providers and message services that are installed on a workstation. For every session, a client at logon time selects one profile that describes the providers and services to be used. A client can choose from a collection of profiles and, if desired, establish one as the default. The default profile is the profile that is selected automatically when a client starts a session and has not explicitly specified a profile.
Profiles are divided into sections and it is these sections that clients and service providers access to display profile properties to users or to make configuration changes. A profile section is a MAPI object that implements the IProfSect interface, an interface that derives from IMAPIProp and has no additional methods. Its purpose is solely to manipulate the properties of a profile section. To retrieve an IProfSect pointer to a particular profile section, clients and service providers call the following methods:
| Clients can call: | IMAPISession::OpenProfileSection |
| Service providers can call: | IMAPISupport::OpenProfileSection |
| Either clients or providers can call: | IProviderAdmin::OpenProfileSection |
Profiles are organized hierarchically much like the MAPISVC.INF file. At the top of the hierarchy, there are profile sections that contain information relevant to the profile. The middle level includes sections that contain information about a particular message service and the lower level includes sections that contain information about one of the service providers in a message service.
Every profile has several required properties that are stored in one or more of the sections of the profile. For example, every profile has the PR_PROFILE_NAME and PR_SEARCH_KEY properties. A profile's search key is set to the value defined in MAPIGUID.H as MUID_PROFILE_INSTANCE and is always guaranteed to be unique among all profiles. Whereas it is possible for two profiles to have the same name, it is not possible for two profiles to have the same search key. Search keys should be treated as binary data rather than data of any particular type.
Message store providers are required to include their message stores' PR_DISPLAY_NAME property in the profile sections for the profile and for the message store provider and keep these entries synchronized. When a message store is created, the provider sets PR_DISPLAY_NAME based on the value stored in these profile sections.
There are two major differences between profile sections and other objects that inherit from IMAPIProp:
Because profile sections do not support transactions, any changes made with calls to IMAPIProp::CopyProps, CopyTo, or SetProps immediately take effect. Clients and service providers can call a profile section's IMAPIProp::SaveChanges method and it will succeed, but it has no affect on the profile section data. Having changes occur immediately can affect how service providers implement the property sheets that clients use to display profile properties to users. Service providers that want users to be able to postpone or undo changes must implement their property sheets with copies of profile sections rather than the real sections. With copies, users can make changes and later cancel those changes, leaving the original profile sections untouched.
The order in which information appears in a profile affects how MAPI configures resources and makes assignments in a session. The following assignments are affected by profile order:
MAPI sets the default message store to be the first message store in the profile that has the STATUS_DEFAULT_STORE flag set in its PR_RESOURCE_FLAGS property, indicating that it is capable of being the default store. Clients can override this setting by calling IMAPISession::SetDefaultStore.
MAPI sets the personal address book (PAB) to be the first container that has the AB_MODIFIABLE and AB_RECIPIENTS flags set in its PR_CONTAINER_FLAGS property, indicating that it can store messaging users and distribution lists. Clients can override this setting by calling IAddrBook::SetPAB.
After assigning the PAB, MAPI sets the default address book directory to the first container that has not been assigned as the PAB and has the AB_RECIPIENTS flag set in its PR_CONTAINER_FLAGS property. If the PAB is the only address book container in the profile that is able to hold recipients, then it is assigned as the default directory. Clients can set this directory explicitly by calling IAddrBook::SetDefaultDir.
MAPI assigns the default search path for the address book to be the PAB followed by each directory that has these property settings:
If there are no containers of type DT_GLOBAL, MAPI assigns the default path to be the PAB and the default directory. Clients can set the default path by calling IAddrBook::SetSearchPath.
MAPI creates a transport order for handling outgoing and incoming messages. When more than one transport provider has registered for a message of a particular type, MAPI uses this order to determine which provider should handle the message. MAPI sets the transport order to be the order in which the transport providers were added to the profile with one exception. The transports that set the STATUS_XP_PREFER_LAST flag in their PR_RESOURCE_FLAGS property are placed last in the order. Clients can set the transport order by calling IMsgServiceAdmin::MsgServiceTransportOrder.
These guidelines for ordering service providers and message services might sometimes conflict. If there is a conflict, include C or C++ code to resolve the conflict. You can use the Delivery and Addressing pages of the Mail and Fax Control Panel applet to inspect a profile that you have created to determine if the providers have been configured as expected.