Creating and Configuring a Profile

See Message Services and Profiles for more information about creating a profile using MAPI, adding message services to it and configuring them, and establishing certain default settings in the profile.

Design Tasks

1. Understand what message services your profile requires, and whether you wish to give your user any choice of services.
2. Choose your tool. There are several tools available for creating profiles. Alternatives include:
   • Not creating one and using the messaging client's profile. This is usually the best choice for interpersonal (IPM) applications, especially if you want to use the same message store as the messaging client.
   • Using the Profile Wizard to create a profile and having your user select message services interactively. For this technique to succeed, the services you require must all support wizard-based configuration, and your application must tolerate uncertainty in its configuration. See Creating a Profile with the Profile Wizard.
   • Using the NEWPROF.EXE utility and a template contained in a .PRF file to create a profile from a setup program or batch environment, or by spawning the utility from your own program. See Creating a Profile with NEWPROF.
   • Writing C or C++ code to create a profile. This is often the best choice for a noninteractive application which requires a specific set of message services. See Creating a Profile with Custom Code.
3. Understand in what order to add services. Following are guidelines for ordering service providers. These guidelines will occasionally conflict; when they do, you will have to write C or C++ code to configure one or more of the provider orders. You can use the Delivery and Addressing pages of the Mail and Fax control panel applet to inspect a profile you have created and see if the providers have been ordered as you expected.
   • Default message store. The first message store added to a profile which is capable of being the default store becomes the default store. Ordinarily, the service you intend to contain the default store should be listed first. See IMAPISession::SetDefaultStore.
   • Personal address book (PAB), default directory, and address book search order. The PAB, if not set explicitly, is the first container that is writeable and can contain names (according to its PR_CONTAINER_FLAGS property). The default directory is the first container in the hierarchy that contains names and is not the PAB (unless the PAB is the only container that can contain names). The default search path is the PAB, followed by each directory that is of display type DT_GLOBAL, has names, and does not have the AB_NOT_DEFAULT flag set in PR_CONTAINER_FLAGS. If there are no directories of type DT_GLOBAL, the default search path is just the PAB and the default directory. See Resolving a Name, IAddrBook::SetPAB, and IAddrBook::SetSearchPath.
   • Transport order. If the transport order is not explicitly set, MAPI services transports in the same order they were added to the profile, except that transports which set the STATUS_XP_PREFER_LAST flag are serviced last. The transport order is unimportant unless your profile contains two or more transports which handle the same e-mail address type. See IMsgServiceAdmin::MsgServiceTransportOrder.

If your application must run unattended, perhaps as a background application or a Windows NT service, some special cautions apply. See Writing an Automated Client and Windows NT Service Client Applications.

If your application requires a specific profile other than the default profile, you must save its name in your own configuration database or use a specific naming convention. MAPI does not expose any profile attributes other than the name and default flag in the profile table, and the default profile flag is reserved for the messaging client and related IPM applications.

Implementation Tasks

    To create a .PRF file for use with the NEWPROF.EXE utility

1. Assemble information from existing .PRF files. For each service you plan to use, copy the section that lists the name, type, and property identifier for each configuration property. The section must have the same name as the service. Services implemented by Microsoft are listed in Section 4 of the DEFAULT.PRF file that is installed with MAPI.
2. Place the profile name in the ProfileName= line of the [General] section.
3. Create the [Service List] section, in Section 2 of the file. In this section, list each service you require and the name of the section that contains its configuration properties. Refer to the earlier guidelines to establish the order of services.
4. For each service listed in the [Service List] section, create a section that lists the value for each configuration property; the section must have the same name as the service. This information appears in Section 3 of the file.
5. Invoke the utility. On 32-bit operating systems, it can be run from a command line or batch file. On 16-bit Windows, NEWPROF.EXE cannot be run from an MS-DOS shell; it can be run by a Windows-based setup script, by the Run command on the File menu in Program Manager or File Manager, or by the WinExec system call. It takes command line parameters as follows:
   • -P descriptor-file-path

     An absolute path to the .PRF file. The default value is DEFAULT.PRF in the Windows directory.

   • -S

     If this option is present, NEWPROF.EXE displays a logging window showing what is being executed and any errors it encounters. By default no window is displayed.

   • -X

     If this option is present, NEWPROF.EXE immediately creates the profile. By default, it waits until the user chooses the Execute button in its window. This option is required if NEWPROF.EXE is to run without displaying its window.

   • -Z

     If this option is present, NEWPROF.EXE displays error messages and other debugging information in its window. By default this information is not displayed.

Note References to Sections 1, 2, 3, and 4 in the preceding procedure refer to comments in the DEFAULT.PRF file distributed with the Platform SDK.

    To write custom C or C++ code to create a profile

1. Read the header file for each service. Understand what properties you need to configure and what values you will use.
2. Call the MAPIAdminProfiles function to obtain an IProfAdmin interface. Call the CreateProfile method to create your profile, and the AdminServices method to obtain an IMsgServiceAdmin interface.
3. Add message services to the profile. Refer to the previous guidelines for the order you should use. For each service, use the IMsgServiceAdmin interface to:
   1. Call the CreateMsgService method.
   2. Obtain the MAPIUID structure of the service you just created.
   1. Call the GetMsgServiceTable method to obtain an IMAPITable interface.
   2. Call the HrQueryAllRows function to retrieve all rows from the table.
   3. Get the PR_SERVICE_UID column from the last row. This is the MAPIUID structure of the last service added. You may wish to check with an assertion that other properties of the service are as you expect.
   3. Call the ConfigureMsgService method, passing the MAPIUID structure of the service you just created and a property value array with its configuration properties.
4. If you must make configuration calls that require an IMAPISession interface, such as IMAPISession::SetDefaultStore, IAddrBook::SetPAB, or IAddrBook::SetABSearchPath, pass the MAPI_NO_MAIL flag to the MAPILogonEx function.
5. To make your profile temporary, call the IProfAdmin::DeleteProfile method immediately after logging on to the profile. It will be deleted after you log off, and will not be visible to other applications in the meantime.

About Sample Source Code

None available at this time.