Custom Actions Keys

Updated: April 8, 2009

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 change how Connection Manager handles custom actions. To do this, you need to edit the service (.cms) file. The table in this topic covers the key names and values that pertain to the custom actions sections of the .cms file. This topic also describes the formats and conventions you should use in the .cms file.

Connection Manager creates service (.cms) files, which use the same format as Windows initialization (.ini) files and information (.inf) files. These files have several things in common:

  • Each file is divided into sections, with specific entries, called keys, assigned to the sections. A section heading is enclosed within brackets ([ ]). For example, [Strings] is a section containing text strings for messages. The keys for a section are not enclosed within brackets.

  • Each value specified for a numeric key 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.

  • Each comment in the file begins with a semicolon (;).

The following table shows the valid keys for custom actions in the .cms file, the function and use of each key, and where each key can be set. You can set different keys in the CMAK wizard or in the .cms file. If you change the .cms file with a text editor, rather than by using the Advanced Customization page of the CMAK wizard, you must rebuild the profile afterward with the CMAK wizard.

noteNote
In the following table, keys controlled by specific panes of the CMAK wizard are identified in the Set in column as CMAK. Although these keys appear in the .cms file, you should use the CMAK wizard to update these keys. If you change these keys by editing the .cms file, the CMAK wizard might overwrite them if you run it again on the same profile. Keys set in the Advanced Customization page of the CMAK wizard are identified as .cms or .cmp, as appropriate.

noteNote
Make sure that locations are specified either as the full path or in reference to the location of the .cmp file.

 

[Section] or key name Value Set in

[Pre-Init Actions]

Pre-init actions that run as soon as the profile is accessed. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[Pre-Connect Actions]

Pre-connect actions that run before a connection is established. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[Pre-Dial Actions]

Pre-dial actions that run immediately before dialing. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[Pre-Tunnel Actions]

Pre-tunnel actions that run after a connection is established but before a VPN connection is established. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[Connect Actions]

Post-connect actions that run after a connection is established and, if using a VPN connection, after the tunnel is established. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[Disconnect Actions]

Disconnect actions that run immediately before disconnecting. If a connection is prematurely dropped, these actions are run immediately after the disconnect. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[On-Cancel Actions]

On cancel actions that run when the user cancels a session after the connection attempt has been started (any time that the user clicks Connect and then clicks Cancel). This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[On-Error Actions]

On error actions that run when an error occurs. This section uses the following keys: #, #&Flags, and #&Description.

CMAK

.cms

[Auto Applications]

Monitored actions that run during a connection. Monitored actions are similar to custom actions, but they cause the disconnect sequence to start as soon as the last monitored application closes. This section uses the following keys: #, #&Flags, and #&Description. Unlike other custom actions, monitored actions do not support DLLs.

CMAK

.cms

#

A single custom action. The format of the value is # = Program, where # is an ID number from 0 to n and Program is the complete name of the program, including the extension and the path to the program. Programs start in sequence: 0 first, 1 next, and so on. Environmental variables, such as %UserName% and %ErrorCode%, are set in Connection Manager and can be used as parameters for custom action programs.

CMAK

#&Flags

Whether a custom action runs when a specific type of connection is established. The format of the value is #&Flags = n, where # is the ID number of a defined custom action and n is a value indicating how dial-up and direct connections for that custom action are handled:

  • If n = 0 (default), all connections trigger this custom action. (The default key does not appear in the .cms file.)

  • If n = 1, all direct tunnel connections trigger this custom action.

  • If n = 2 , all connections that involve dialing (direct or double) trigger this custom action.

  • If n = 4, only connections that use direct dial-up trigger this custom action.

  • If n = 8, only connections that involve a tunnel trigger this custom action.

  • If n = 16, specifies that the program requires interaction with the user.

  • If n = 32, specifies that the program requires elevation to operate.

CMAK

#&Description

A short description of a custom action. The format of the value is #&Description = text, where # is the number of a defined custom action and text is the descriptive information for that custom action. This option can provide useful information when a synchronous custom action does not run properly.

Default = the name of the custom action program.

CMAK

Community Additions

ADD
Show: