Including Connection Manager in custom applications

  • Article

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

Including Connection Manager in custom applications

You can include Connection Manager and a service profile with your own custom installation package. The Connection Manager installation program, cmstp.exe, has several parameters that control how a service profile package is installed. You can also call Connection Manager programmatically from within a custom application.

Note

  • If you use the Internet Explorer Administration Kit (IEAK) to integrate a Connection Manager service profile with an Internet Explorer installation package, the Internet Explorer Customization wizard incorporates the command-line parameters needed to integrate the two installation programs.

Delivering a custom installation package

Using command-line parameters, you can integrate Connection Manager in an installation package and deliver it to users in a variety of ways. For example, you might want to:

  • Distribute and install the Connection Manager service profile over a corporate network using Microsoft Systems Management Server (SMS) to automatically handle the process without user intervention.

  • Integrate the Connection Manager service profile with another product's installation package and install them both in a single process.

  • Post the Connection Manager service profile to a Web site to enable users to access and install the service profile in a standard way (specifying certain installation options for the user).

You can set up these distribution and installation options programmatically only after you have used the Connection Manager Administration Kit (CMAK) wizard to build your service profile.

Syntax

The command-line syntax for cmstp.exe follows one of two formats. One is for use with a service profile self-extracting executable (.exe) file, and the other is for use with a service profile information (.inf) file.

If you are building a custom installation or uninstallation package with the service profile executable file, you will want to use the following syntax:

ServiceProfileFileName**.exe** [/q:a] /c:"cmstp.exeServiceProfileFileName**.inf** [Parameters]"

If you are building a custom installation or uninstallation package without the service profile executable file, you must use the following format in your custom package, and you must know the full path to the .inf file:

cmstp.exe [Parameters] "[drive][full path]ServiceProfileFileName**.inf"**

Notes

  • ServiceProfileFileName is the file name of the service profile you build with the CMAK wizard.

  • The optional parameter, /q:a, prevents the profile from opening automatically after it has been installed. The verification message that the installation has succeeded will still appear.

  • The command, /c:"cmstp.exe, tells the extraction program to override the installation defaults.

  • Do not use brackets [] when specifying the full path to the .inf file.

  • Parameters are the command-line parameters supported by the cmstp.exe installer.

  • You can copy your service profile executable (.exe) file during installation and store it in a known directory. This action helps ensure that you will be able to refer to the file in the future.

Parameters

The following parameters are supported for installation:

  • /ni - Do not create a desktop icon (valid only on Windows 95, Windows 98, Windows NT 4.0, and Windows Millennium Edition). On these platforms, the desktop icon is the only method provided by Connection Manager to enable users to open or delete a profile. If you use this parameter, you must provide your users with a different way to open or delete the service profile.

  • /ns - Do not create a desktop shortcut to the connection in the Network and Dial-up Connections folder (Windows 2000 only) or the Network Connections folder (Windows XP and the Windows Server 2003 family only). Unless the silent install parameter is also specified, this only overrides the default user preference, so the user will still see the check box in the user interface. The first time a user installs a profile, the default is not to have a desktop shortcut. The user's preference is stored in the registry and is used for each subsequent installation.

  • /s - Install silently. This option allows automatic installation of the service profile without requiring user action to complete the installation. The profile will not automatically start after it is installed.

  • /sd - Set the installed profile as the default connection for Internet Explorer.

  • /su - Install for a single user (valid only on Windows 2000, Windows XP, and the Windows Server 2003 family). If this parameter is used, the user does not have the option to install the software for use by all users.

  • /au - Specifies that the service profile should be installed for all users. This parameter is only valid for computers running a member of the Windows Server 2003 family, Windows 2000, or Windows XP.

The parameters supported for uninstalling are as follows:

  • /u - Uninstall the service profile. The only other parameter that can be used with this parameter is the /s parameter.

Important

  • Any user can modify the .cms and .cmp file of a service profile that is installed on a computer running Windows 98 or Windows Millennium Edition. Users who install profiles for individual use on computers that are running Windows Server 2003, Windows XP, or Windows 2000 can modify .cms and .cmp files of the profiles they install. Only members of the Administrators or System Operators groups can modify .cms and .cmp files of profiles installed for All Users on computers that are running Windows Server 2003, Windows XP, or Windows 2000. Any member of the Administrators group on a local computer can modify the .cms and .cmp files of any service profile that is installed on that computer.

Notes

  • To display Help for the command-line installation parameters, type cmstp.exe /?.

  • To find the full path to the service profile information (.inf) file, you can use information extracted from registry keys, as shown in the examples below.

If you do not specify parameters for the cmstp.exe file, the following defaults are used:

  • On a computer running Windows 95, Windows 98, Windows NT 4.0, or Windows Millennium Edition, a desktop icon is created, the profile is installed for all users, and the profile automatically starts after it is installed.

  • On a computer running Windows 2000, the profile is installed for use by all users. If the Connection Manager software is included in the profile, that software is also installed.

  • On a computer running Windows XP or a member of the Windows Server 2003 family, the profile is installed for use by all users, but Connection Manager is not installed.

  • If a user is not logged on as an Administrator on a computer running Windows 2000, Windows XP, or a member of the Windows Server 2003 family, the software is installed for use by a single user.

Integrating the Connection Manager software within a custom application

You can start Connection Manager from within a custom application. A Connection Manager service profile presents a customized connection experience for your users. By integrating Connection Manager with a custom application, you can ensure that all your users connect in exactly the same way.

If you are writing an application for computers running Windows 2000, Windows XP, or a member of the Windows Server 2003 family and you want to open the Connection Manager logon screen, you can use the RasDialDlg function. If you want to open the Properties dialog box (for instance, if you want the users to select a phone number before dialing), you can use the RasEntryDlg function. For more information about these functions and how to use them, search for these function names on the Microsoft Web site or consult the Microsoft Platform Software Development Kit.

The RasDialDlg and RasEntryDlg functions are not supported for Windows 95, Windows 98, or Windows Millennium Edition. Although these functions are supported on Windows NT 4.0, using them in conjunction with a Connection Manager service profile is not supported. If you are writing an application for computers running one of these operating systems, you can instead use a function such as ShellExecute or CreateProcess to start cmmgr32.exe. To open the Connection Manager logon screen, use cmmgr32.exe, followed by the full path to the .cmp file of the service profile you want to open. For example, to open the Awesome Computers service profile on a computer running Windows 98, use:

cmmgr32.exe "c:\Windows\All Users\Application Data\Microsoft\Network\Connections\Cm\Awesome1.cmp"

If you want to open the Properties dialog box, use cmmgr32.exe followed by /settings followed by the full path to the .cmp file. For example, to open the Properties dialog box for the Awesome Computers service profile on a computer running Windows 98, use:

cmmgr32.exe /settings "c:\Windows\All Users\Application Data\Microsoft\Network\Connections\Cm\Awesome1.cmp"

Notes

  • Cmmgr32 runs as an asynchronous action. No response is returned to your program unless you add a custom action to the service profile to provide one. You can also wait for cmmgr32 to finish.

  • If the path to the service profile includes spaces, use double quotes (") around the path.

Examples

The following examples describe a possible installation and a possible uninstallation for the Awesome Computers service profile.

Installation example for Awesome Computers

Awesome Computers wants to build a custom installation package and include a service profile, Awesome1.exe, in the package. The company wants a silent install. The company does not want to create a desktop icon or a desktop shortcut to the profile. The company would like the Awesome1 service profile to become the default connection for Internet Explorer.

In its custom installation package, Awesome Computers includes this command:

Awesome1.exe /q:a c:"cmstp.exe Awesome1.inf /s /ni /ns /sd"

Uninstallation example for Awesome Computers

Awesome Computers wants to build a custom uninstallation package. The company does not know whether its users still have the Awesome1.exe file on their computers, so the company must get the .cmp path from the registry and extrapolate the .inf path from that information. The company wants a silent uninstall.

  1. The custom uninstallation application queries one of two registry keys.

    All users profile:

    HKLM\Software\Microsoft\Connection Manager\Mappings

    Single user profile:

    HKCU\Software\Microsoft\Connection Manager\Mappings

    The call provides a name value of Awesome Computers (the full service profile name) and returns a data value of the full path to the Awesome1.cmp file.

  2. The custom uninstall application changes the Awesome1.cmp path into the Awesome1.inf path by replacing Awesome1.cmp with Awesome1\Awesome1.inf. For example, a .cmp path of C:\Documents and Settings\All Users\Application Data\Microsoft\Network\Connections\Cm\Awesome1.cmp must be converted to C:\Documents and Settings\All Users\Application Data\Microsoft\Network\Connections\Cm\Awesome\Awesome1.inf.

  3. The custom uninstallation application includes this command:

    cmstp.exe /u /s "c:\Documents and Settings\All Users\Application Data\Microsoft\Network\Connections\Cm\Awesome\Awesome1.inf"

Notes

  • The credentials of the user installing or uninstalling the package will affect how cmstp.exe operates. If the user does not have administrative credentials, he or she will not be able to install or uninstall a profile for all users. The profile will be installed for his or her own use.

  • If you use the following key, the initial portion of the data value might contain a system macro. HKCU\Software\Microsoft\Connection Manager\Mappings

For more information, see Verifying customization and Troubleshooting process.