Including Connection Manager in Custom Applications
Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2, Windows Server 2008, Windows Server 2008 Foundation, Windows Server 2008 R2, Windows Server 2012, Windows Vista
You can include Connection Manager and a connection profile with your own custom installation package. The Connection Manager installation program, cmstp.exe, has several parameters that control how a connection profile package is installed. You can also call Connection Manager programmatically from within a custom application.
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 connection profile over a corporate network using Microsoft System Center Configuration Manager to automatically handle the process without user intervention.
Integrate the Connection Manager connection profile with another product's installation package and install them both in a single process.
Post the Connection Manager connection profile to a Web site to enable users to access and install the connection profile in a standard way (specifying certain installation options for the user).
You can set up these distribution and installation options only after you have used the Connection Manager Administration Kit (CMAK) wizard to build your connection profile.
The command-line syntax for cmstp.exe follows one of two formats. One is for use with a connection profile self-extracting executable (.exe) file, and the other is for use with a connection profile information (.inf) file.
If you are building a custom installation or uninstallation package with the connection profile executable file, you will want to use the following syntax:
ProfileFileName.exe [/q:a] /c:"cmstp.exeProfileFileName.inf [Parameters]"
If you are building a custom installation or uninstallation package without the connection 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\ProfileFileName.inf"
ProfileFileName is the file name of the connection 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.
Parameters are the command-line parameters supported by the cmstp.exe installer.
You can copy your connection 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.
The following parameters are supported for installation:
/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 later versions of Windows). 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 connection 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. 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 connection profile should be installed for all users.
The parameters supported for uninstalling are as follows:
- /u - Uninstall the connection profile. The only other parameter that can be used with this parameter is the /s parameter.
Users who install profiles for individual use 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. Any member of the Administrators group on a local computer can modify the .cms and .cmp files of any connection profile that is installed on that computer.
To display Help for the command-line installation parameters, type cmstp.exe /?.
To find the full path to the connection 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 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 later version of Windows, the profile is installed for use by all users, but Connection Manager is installed only if required.
If a user is not logged on as an Administrator, 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 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 and you want to open the Connection Manager log on 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 VPN server before connecting), you can use the RasEntryDlg function. For more information about these functions and how to use them, search for these function names on the MSDN Web site (http://go.microsoft.com/fwlink/?LinkId=140), or consult the Microsoft Windows Platform Software Development Kit.
The following examples describe a possible installation and a possible uninstallation for the Awesome Computers connection profile.
Installation example for Awesome Computers
Awesome Computers wants to build a custom installation package and include a connection 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 connection 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.
The custom uninstallation application queries one of two registry keys.
All users profile:
Single user profile:
The call provides a name value of Awesome Computers (the full connection profile name) and returns a data value of the full path to the Awesome1.cmp file.
The custom uninstall application changes the Awesome1.cmp path into the Awesome1.inf path by replacing Awesome1.cmp with Awesome1\Awesome1.inf. For example, on a computer running Windows 7, a .cmp path of C:\Users\All Users\Microsoft\Network\Connections\Cm\Awesome1.cmp must be converted to C:\Users\All Users\Microsoft\Network\Connections\Cm\Awesome\Awesome1.inf.
The custom uninstallation application includes this command:
cmstp.exe /u /s "c:\Users\All Users\Microsoft\Network\Connections\Cm\Awesome\Awesome1.inf"
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