Advanced Customization Options for Connection Manager
The CMAK wizard supports most of the customization features that administrators need to build a custom Connection Manager service profile. However, you can customize additional features by editing the service-profile files and changing the manner in which Connection Manager implements certain functions.
You can edit service-profile files to customize functions and features that are not controlled through the CMAK wizard. To do this advanced customization, you can edit two sets of service-profile files:
The template files that are used by the CMAK wizard to build all service profiles
The files that are built when you run the CMAK wizard to create a specific service profile
Service-profile files consist of the following file types:
Service provider (.cms) files - These files specify the configuration of the phone book and most of the other functions of your service profiles. Most advanced customization for a service profile is done by editing the .cms file for that service profile.
Connection profile (.cmp) files - These files contain information specified by the user. You should not edit the .cmp files because any changes you make can be overwritten by the user.
Information (.inf) files - These files specify the installation information for your service profiles. Although you can edit some setup and removal information in an .inf file, you must be extremely cautious to avoid installation problems.
Connection profile (.sed) files - These files contain the instructions for building a self-extracting executable (.exe) file for your service profiles. You should never edit any .sed file.
Important Be careful when you modify these files. Troubleshooting the changes made to these files is difficult. Never modify the original file, and always make backup copies. A basic understanding of system-configuration files is assumed.
You can edit either the template files or the specific service-profile files, or both, depending on whether you want your customization options applied globally to all service profiles or only to a specific service profile.
When you install the CMAK, the following template files are installed in the \Program Files\CMAK\Support folder:
Template.cms
Template.cmp
Template.inf
Template.sed
These files contain the default settings that the CMAK wizard uses to build the service profiles. If you want to incorporate custom functions in all service profiles that you build, edit the template files before building the service profiles.
Generally, you should edit only the .cms template file.
When you use the CMAK wizard to build a service profile, the wizard creates a self-extracting .exe file and several other files that contain the settings that you specify. The service-profile files are saved in the following folder: \Program Files\CMAK\Profiles\ ServiceProfileFileName
All service-profile files have the name ServiceProfileFileName , which you specify in the CMAK wizard. In addition to the .exe file, the wizard creates the following files for each service profile:
ServiceProfileFileName .cms
ServiceProfileFileName .cmp
ServiceProfileFileName. inf
ServiceProfileFileName .sed
For all files except the .cmp files, the built files take precedence over the template files. After editing a service-profile file, you must run the CMAK wizard again to rebuild the service profile with your customized settings.
Connection Manager creates service (.cms) files, which use the same format as Windows .ini files and information (.inf) files. In these files:
Each file is divided into sections, with specific entries assigned to the sections. A section heading is enclosed within brackets ( [ ] ). For example, [Strings] is a section that contains text strings for messages. The entries for a section are not enclosed within brackets.
Each value specified for a numeric entry must be an integer. Any noninteger value is truncated to an integer or ignored as invalid data. For example, 1.1 is truncated to 1, or ignored.
The order in which sections appear is not important; a particular section can be placed anywhere in the file.
Any comment in the file begins with a semicolon ( ; ).
For more information about these formats and conventions, see the Microsoft Platform Software Development Kit.
You should customize the entries only in the .cms and .inf files, and only as specified in this chapter.
By editing an .inf file, you can specify commands that run when the user sets up or removes your service profile. For example, you can specify:
Setup programs that integrate any custom software that you include
Programs that automatically display a readme file
Configuration utilities or cleanup programs
To add custom set-up and uninstall commands to your service profile, you must first create the service profile by running the CMAK wizard and incorporate any files needed to run your custom commands by specifying each of them as an additional file. After you have built the service profile, specify the custom commands in the appropriate sections of the .inf file.
The .inf file contains the following four sections that you can edit to incorporate setup and uninstall commands, each of which controls the commands that are run at a specific point in the process. Use only file names of eight characters or less (do not use spaces).
RunPreSetupCommands - Commands specified in this section run before installation of your service profile.
RunPostSetupCommands - Commands specified in this section run after the setup program finishes the service profile.
RunPreUnInstCommands - Commands specified in this section run before the uninstall program begins.
RunPostUnInstCommands - Commands specified in this section run after the uninstall program runs.
Each command should include the name of the program to be run and any command-line parameters. Each command specified in the .inf file is run only once during an installation or removal process.
Important Incorrectly specified entries can cause significant installation problems. You should not edit any of the entries in the .inf file except those previously specified. Thoroughly test all service profiles that contain custom .inf entries for version, file, or other conflicts. Be sure that the file location is specified correctly.
When upgrading to a new version of the Connection Manager Administration Kit, the new .inf file replaces the previous .inf file. After the upgrade, you must add your custom entries to the new .inf file if you want to continue using your custom setup and uninstall commands in the service profiles that you build.
Long file names are not supported.
Editing a .cms file can change the implementation of many of the Connection Manager functions. For example, you can do the following:
Edit the RedialDelay entry, which controls the delay between redials.
Edit the PasswordHandling entry, which specifies case sensitivity for passwords.
Edit the HideRememberPassword entry, which controls whether the Save password check box appears.
Edit the HideDialAutomatically entry, which controls whether the Connect automatically check box appears.
Edit the ResetPassword entry, which controls whether a New button appears in the Connection Manager logon dialog box.
Edit the HideDomain entry, which controls whether the Logon domain field appears.
Edit settings in the [Server&EntryName ] and [TCP/IP&EntryName ] sections, which enables you to specify additional settings that control the way in which Dial-Up Networking entries are handled in Connection Manager. Many of these settings are controlled through the CMAK wizard; however, some must be edited in the .cms file, such as the IP_Header_Compress setting.
The following table shows the valid entries for each section of the .cms and .cmp files, the function and use of each entry, and where each entry can be set - in the CMAK wizard, .cms file, and/or .cmp file.
Notes
Do not edit any entry in the .cms file if it can be set by using the CMAK wizard, because the CMAK wizard may overwrite entries in the .cms file.
If an entry is valid in both .cms and .cmp files, edit only the .cms entry.
Make sure that locations are specified either as the full path or in reference to the location of the .cmp file.
[Section] or entry |
Specifies |
Set in |
---|---|---|
[Connection Manager] |
Miscellaneous service-profile settings. |
.cms .cmp |
Dialup |
Whether dial-up connections are supported. |
.cms |
Direct |
Whether direct connections are supported. |
.cms |
ConnectionType |
The connection method used. |
.cms .cmp |
PBMessage |
Text in the Phone Book dialog box next to the More access numbers box when the phone book is displayed and alternate access numbers are available for the selected geographic region. Maximum = approximately 100 characters. |
CMAK .cms |
CMSFile |
Name of the service-profile file ( \Path\ServiceProfileFileName . cms ). |
CMAK .cmp |
ServiceName |
Text appearing in the Connection Manager logon dialog box as the service name, and as the name of the connection object. This is the key identifier for the profile. |
CMAK .cms |
ServiceMessage |
Connection Manager logon dialog box service message, usually a customer-support number for the service. |
CMAK .cms |
UserName |
User name typed by the user. |
.cmp |
UserNamePrefix |
Prefix appended to the user name. Enables access to a service requiring a realm name as a prefix. |
CMAK .cms |
UserNameSuffix |
Suffix appended to the user name. Enables access to a service requiring a realm name as a suffix. |
CMAK .cms |
MaxUserName |
Maximum length of the user name that can be typed by the user. UserNamePrefix and UserNameSuffix are not included. |
.cms |
UserNameOptional |
Whether the user must type a user name at the Connection Manager logon dialog box. |
.cms |
HideUserName |
Whether the User name box appears in the Connection Manager logon dialog box when using dial-up connections. |
.cms |
Password |
Password typed by the user. |
.cmp |
PasswordHandling |
Method of handling the password during the logon process. |
.cms |
MaxPassword |
Maximum length of the password that can be typed by the user. |
.cms |
PasswordOptional |
Whether the user must specify a password in the Connection Manager logon dialog box. |
.cms |
RememberPassword |
Whether the user selected the Save password check box in the Connection Manager logon dialog box. |
.cmp |
HidePassword |
Whether the Password box appears in the Connection Manager logon dialog box when using dial-up connections. |
.cms |
HideRememberPassword |
Whether to display the Save password check box in the Connection Manager logon dialog box of Connection Manager and on the Internet Logon tab. Service profiles built to support VPN connections contain this additional tab. |
.cms |
Domain |
Logon domain name typed by the user. |
.cmp |
MaxDomain |
Maximum length of the domain name that can be typed by the user. |
.cms |
HideDomain |
Whether the Logon Domain box appears in the Connection Manager logon dialog box when using dial-up connections. |
.cms |
HideInternetUsername |
Whether the Username box appears on the Internet Logon tab in the Properties dialog box. |
.cms |
HideInternetPassword |
Whether the Password box appears on the Internet Logon tab in the Properties dialog box. |
.cms |
DialAutomatically |
Whether the user selected the Connect automatically check box in the Connection Manager logon dialog box. |
.cmp |
HideDialAutomatically |
Whether the Connect automatically check box appears in the Connection Manager logon dialog box. |
.cms |
InternetUserName |
User name for VPN connections, typed by the user. |
.cmp |
InternetPassword |
Password for VPN connections, typed by the user. |
.cmp |
RememberInternetPassword |
Whether the user selected the Save password check box in the Internet Logon dialog box. |
.cmp |
Phone0 |
Primary phone number typed or selected by the user. |
.cmp |
PhoneCanonical0 |
The canonical format of the primary phone number last selected from the phone book or typed in using the canonical format. |
.cmp |
PhoneCountry0 |
TAPI country/region code for the primary phone number. |
.cmp |
UseDialingRules0 |
How dialing rules are applied to the primary phone number. |
.cms .cmp |
PhoneSource0 |
Service profile for the primary phone number. |
.cmp |
Description0 |
Description of the primary phone number. Appears in the Phone Book dialog box as a POP name. |
.cmp |
DUN0 |
Dial-Up Networking entries used for the primary phone number. |
.cmp |
Phone1 |
Backup phone number, entered by the user. |
.cmp |
PhoneCanonical1 |
The canonical format of the backup number last selected from the phone book or typed in using the canonical format. |
.cmp |
PhoneCountry1 |
TAPI country/region code for the backup phone number. |
.cmp |
UseDialingRules1 |
How dialing rules are applied to the backup number. |
.cms .cmp |
PhoneSource1 |
Service profile for the backup phone number. |
.cmp |
Description1 |
Description of the backup phone number. Appears in the Phone Book dialog box as a POP name. |
.cmp |
DUN1 |
Dial-Up Networking entries used for the backup phone number. |
.cmp |
Modem0 |
Name of the modem device to use for the primary phone number. |
.cmp |
Modem1 |
Name of the modem device to use for the backup phone number. |
.cmp |
NoPromptReconnect |
Whether the user is prompted for reconnection. |
.cms |
ServiceType0 |
Service type that the user most recently selected from the phone book for the primary phone number. |
.cmp |
ServiceType1 |
Service type that the user most recently selected from the phone book for the backup phone number. |
.cmp |
Region0 |
State or province that the user most recently selected from the phone book for the primary phone number. |
.cmp |
Region1 |
State or province that the user most recently selected from the phone book for the backup phone number. |
.cmp |
Version |
Version of the phone book. |
.cms |
DUN |
Dial-Up Networking entries used when Dial-Up Networking in the phone book is blank. |
.cms |
RedialCount |
Number of redials to attempt. |
.cms .cmp |
RedialDelay |
Delay (in seconds) between dials. The delay is the elapsed time between the point of failure of the first call and the dialing of the first digit of the next phone number. |
.cms |
IdleTimeout |
Length of time (in minutes) that the connection must be idle before disconnecting. |
.cms .cmp |
IdleThreshold |
Maximum bytes per minute that can be received if an idle state is to be detected for the connection. |
.cms |
Logo |
Location of the .bmp file displayed in the Connection Manager logon dialog box. |
CMAK .cms |
PBLogo |
Location of the .bmp file for the Phone Book dialog box. |
CMAK .cms |
Icon |
Location of the icon (.ico) file for the large program icon. |
CMAK .cms |
SmallIcon |
Location of the .ico file for the small title-bar icon. |
CMAK .cms |
TrayIcon |
Name of the .ico file for the status-area icon. |
CMAK .cms |
HideTrayIcon |
Whether to display the status-area icon in the Windows taskbar. |
.cms |
HelpFile |
Location (including name) of the custom Help file. |
CMAK .cms |
DownloadDelay |
Time (in seconds) to delay before downloading phone book updates. |
.cms |
HideDelay |
Time (in seconds) to delay before displaying the Phone-Book Updates dialog box (with progress indicators and message). |
.cms |
PBUpdateMessage |
Text that appears in the dialog box during a phone book update. |
.cms |
Tunnel |
Whether VPN connections are enabled for the service profile. |
CMAK .cms |
TunnelDUN |
Dial-Up Networking entries used for VPN connections. |
.cms |
TunnelAddress |
IP address or domain name for the VPN server. |
CMAK .cms |
TunnelReferences |
Whether VPN connections are enabled for phone numbers taken from referenced phone books. |
CMAK .cms |
UseSameUserName |
Whether to use a separate user name and password when connecting to the Internet service provider (for a VPN connection). |
CMAK .cms |
ResetPassword |
Whether the New button appears in the Connection Manager logon dialog box to enable a user to reset the password. You can use this button to set up a custom password option. Type the location (including name) of the executable program you use to support this process. You must provide an executable program for this option and include it as an additional file when you run the CMAK wizard. |
.cms |
AnimatedLogo |
Whether an animation is used instead of a static bitmap in the Connection Manager logon dialog box. |
.cms |
CheckOSComponents |
Whether Connection Manager checks the operating-system components. |
.cms |
DoNotCheckBindings |
Whether to include the TCP/IP bindings in the TCP/IP check. |
.cms |
AutoReconnect |
Whether Connection Manager attempts to re-establish a connection that is dropped by the network. |
.cms |
LanaTimeout |
The time (in seconds) to wait before attempting connection to a VPN server. |
.cms |
[Profile Format] |
Service-profile version. |
.cms .cmp |
Version |
Format version of the profile or service file. |
.cms .cmp |
[ISP] |
Service types (such as Modem or ISDN) that you want to list in the Phone Book dialog box, and how you want phone numbers to appear for each service type. The Mask and Match lines control where a phone number is listed in the Phone Book dialog box. You can specify whether the number is listed under Access Numbers or under More Access Numbers. Each Mask and Match line has a corresponding service option in Phone Book Administrator. |
.cms |
PBFile |
Location of the phone book (.pbk) file used by the service profile. |
CMAK .cms |
RegionFile |
Location of the region (.pbr) file used by the service profile. |
CMAK .cms |
PBURL |
Uniform Resource Locator (URL) for the phone book update. |
CMAK .cms |
Mask& FilterName |
Mask value for FilterName . |
.cms |
Match& FilterName |
Match value for FilterName . |
.cms |
FilterA& ServiceProfile |
List of filter names to be applied to the access numbers' phone-book settings field - for example, FilterA& = NosurchargeSignon. The selected phone numbers are listed in the Access Numbers box in the Connection Manager Phone Book dialog box. |
.cms |
FilterB& ServiceProfile |
List of filter names to be applied to the referenced phone book options field - for example, FilterB& = SurchargeSignon. The selected phone numbers are listed in the More Access Numbers box in the Connection Manager Phone Book dialog box. |
.cms |
References |
Service profiles merged through the CMAK wizard. Profile names are separated by commas or spaces. Each name is used as a reference to that profile. |
CMAK .cms |
CMSFile& MergedProfile |
Location of the merged service file (.cms file). The format is CMSFile& MergedProfile = Location , where MergedProfile is the name of the merged service profile and Location is the location of the .cms file for the merged service profile - for example: |
CMAK .cms |
FilterA& MergedProfile |
List of filter names to be applied to the referenced phone book options field. The format is FilterA& Reference = FilterName , where MergedProfile is the name of the merged service profile, as specified in the CMSFile MergedProfile entry, and FilterName is the name of the filter to be applied - for example: |
CMAK .cms |
FilterB& MergedProfile |
List of filter names to be applied to the referenced phone book options field. The format is FilterB& MergedProfile = FilterName , where MergedProfile is the name of the merged service profile, as specified in the CMSFile Reference entry, and FilterName is the name of the filter to be applied - for example: |
CMAK .cms |
[Service Types] |
Items that are listed in the Phone Book dialog box under Service Type. |
.cms |
ServiceType |
A service type as a filter name to be applied to the referenced phone book options field. The format of the entry is ServiceType = FilterName , where ServiceType is the name as it appears in the Service Type list in the Phone Book dialog box, and FilterName is the name of the filter to be associated with the entry - for example: |
.cms |
[Pre-Connect Actions] |
Optional pre-connect actions to run before a connection is established. The following environment variables are set in Connection Manager and can be implemented in connect actions as command-line options: Profile, UserName, UserPrefix, UserSuffix, ServiceName, DialRasPhoneBook, TunnelRasPhoneBook, AutoRedial, PopName, RasErrorCode, DialRasEntry, TunnelRasEntry. (Other settings are available through the RAS connection.) |
.cms |
# |
A single pre-connect action. The format of the entry is # = Program , where # is a number from 0 to x , and Program is the complete name of the program (including the .exe or .dll file and associated parameters). Programs start in sequence: 0 first, 1 next, and so on. |
CMAK .cms |
# &Flags |
Whether a pre-connect action runs when a specific type of connection is established. The format of the entry is # &options = x , where # is the number of a defined pre-connect action and x is a value indicating how dial-up and direct connections for that pre-connect action are handled: |
CMAK .cms |
# &Description |
A short description of a pre-connect action. The format of the entry is # &Description = text , where # is the number of a defined pre-connect action and text is the descriptive information for that pre-connect action. This option can provide useful information when a synchronous connect action does not run properly. |
CMAK .cms |
[Pre-Tunnel Actions] |
Optional pre-tunnel actions to run after a connection is established but before a VPN connection is established. Pre-tunnel actions use the same format as other connect actions (as shown in the [Pre-Connect Actions] section, the # , # &option, and # &Description entries). |
.cms |
[Connect Actions] |
Optional post-connect actions to run after a connection is established and, if using a VPN connection, after the tunnel is established. Post-connect actions use the same format as other connect actions (as shown in the [Pre-Connect Actions] section, the # , # &option, and # &Description entries). |
.cms |
[Disconnect Actions] |
Optional disconnect actions to run immediately before disconnecting. Disconnect actions use the same format as other connect actions (as shown in the [Pre-Connect Actions] section, the # , # &option, and # &Description entries). |
.cms |
[Pre-Dial Actions] |
Optional pre-dial actions to run immediately before dialing. Pre-dial actions use the same format as other connect actions (as shown in the [Pre-Connect Actions] section, the # , # &option, and # &Description entries), but they cannot be set in the CMAK wizard. |
.cms |
[On-Cancel Actions] |
Optional on-cancel actions to run when the user cancels a session after the connection has been started. On-cancel actions use the same format as other connect actions (as shown in the [Pre-Connect Actions] section, the # , # &option, and # &Description entries), but they cannot be set in the CMAK wizard. |
.cms |
[On-Error Actions] |
Optional on-error actions to run when an error occurs. On-error actions use the same format as other connect actions (as shown in the [Pre-Connect Actions] section, the # , # &option, and # &Description entries), but they cannot be set in the CMAK wizard. |
.cms |
[Auto-Applications] |
Optional auto-applications to run during a connection. Auto-applications are similar to connect actions, but they cause the connection to close as soon as the final auto-application finishes. (Auto-applications use the same format as shown in the [Pre-Connect Actions] section, the # entry). Unlike pre-connect actions, auto-applications do not use the # &option or # &Description entries. |
.cms |
[Menu Options] |
Shortcut menu that appears when a user right-clicks the status-area icon for your service. |
.cms |
MenuItemName |
Command to be run from the shortcut menu. Shortcut menu commands use the format MenuItemName = Program , where MenuItemName is the descriptive name that appears on the shortcut menu and Program is the name of the executable file (.exe or .dll), including any parameters required for the program. For example, if you wanted to add Notepad to the menu with the command name "Editor," the [Menu Options] line would be Editor = Notepad.exe . |
CMAK .cms |
[Animated Logo] |
Animation for the Connection Manager logon dialog box. AnimatedLogo in the [Connection Manager] section determines whether an animation is used. |
.cms |
Movie |
Location of the optional animation file displayed in place of the static bitmap in the logon dialog box. Settings in the [Animated Actions] section control how the optional animation plays based on the connection state. |
.cms |
Parameter |
Other animation parameters passed from software used to create the animation, such as Quality = 3. |
.cms |
[Animated Actions] |
When to play segments of the animation. |
.cms |
Initial |
Starting frame number; plays when Connection Manager starts. |
.cms |
Dialing0 |
Starting frame number; plays while the primary phone number is dialed. |
.cms |
Pausing |
Starting frame number; plays during pauses between dials. |
.cms |
Dialing1 |
Starting frame number; plays while the backup phone number is dialed. |
.cms |
Authenticating |
Starting frame number; plays during user authentication. |
.cms |
Tunneling |
Starting frame number; plays while establishing a VPN connection. |
.cms |
Connected |
Starting frame number; plays when a connection is established. |
.cms |
Error |
Starting frame number; plays at any connection error. |
.cms |
[Server&EntryName ] |
Dial-Up Networking configuration. To store settings for multiple Dial-Up Networking entries, the name of the Dial-Up Networking entry is appended to each section header for that entry - for example, Server&Awesome1. |
.cms |
NetworkLogon |
Whether to log on to the network. |
.cms |
SW_Compress |
Whether to negotiate PPP software compression of data. |
.cms |
Disable_LCP |
Whether to enable Link Control Protocol (LCP) extensions. |
.cms |
PW_Encrypt |
Whether to encrypt password when authenticating. |
.cms |
Negotiate_TCP/IP |
Whether to negotiate TCP/IP. |
.cms |
Negotiate_IPX |
Whether to negotiate IPX protocol. |
.cms |
Negotiate_NetBEUI |
Whether to negotiate NetBEUI protocol. |
.cms |
[TCP/IP&EntryName ] |
Dial-Up Networking configuration. The name of the Dial-Up Networking entry is appended to each section header for that entry - for example, [TCP/IP&Awesome1] . |
.cms |
Specify_IP_Address |
Whether to specify a static IP address. |
.cms |
IP_Address |
Static IP address. |
.cms |
Specify_Server_Address |
Whether to specify static DNS and WINS addresses. |
CMAK .cms |
DNS_Address |
DNS address. |
CMAK .cms |
DNS_Alt_Address |
Alternate DNS address. |
CMAK .cms |
WINS_Address |
WINS address. |
CMAK .cms |
WINS_Alt_Address |
Alternate WINS address. |
CMAK .cms |
IP_Header_Compress |
Whether to enable IP header compression. |
.cms |
Gateway_On_Remote |
Whether to use the default gateway on the remote private network. |
.cms |
[Networking&EntryName ] |
Dial-Up Networking configuration. The name of the Dial-Up Networking entry is appended to each section header for that entry - for example, [Networking&Awesome1]. |
.cms |
VpnStrategy |
Which tunneling protocol to use when establishing a VPN connection. |
.cms |
[Scripting&EntryName ] Section |
Location (path and file name) of the script (.scp) file for the Dial-Up Networking entry. The name of the Dial-Up Networking entry is appended to each section header for that entry - for example, [Scripting&Awesome1]. |
.cms |
Name |
Location (including file name) of the script (.scp) file for the Dial-Up Networking entry. |
CMAK .cms |
.