Share via

Incorporating custom actions

  • Article

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

Incorporating custom actions

You can enhance the connection experience for your users by providing additional programs that start seamlessly during the connection to your service. You can use the Connection Manager Administration Kit (CMAK) wizard to include custom actions in your service profiles to automatically start programs when users connect to your service. These custom actions can use programs that users have already installed, or you can include the programs with your service profile.

What custom actions are supported and when do they run?

Using the CMAK wizard, you can specify custom actions to run at nine points during the connection process. You can run:

  • Pre-init actions

  • Pre-connect actions

  • Pre-dial actions (for dial-up connections only)

  • Pre-tunnel actions (for virtual private network (VPN) connections only)

  • Post-connect actions

  • Monitored actions

  • Disconnect actions

  • On cancel actions

  • On error actions

Pre-init actions

As soon as users start Connection Manager, it runs the pre-init actions you have specified in your service profile. These actions are run before the Connection Manager logon screen appears.

Note

  • Pre-init actions will run when the Properties dialog box is opened for the service profile.

Pre-connect actions

As soon as users click Connect, Connection Manager runs the pre-connect actions you have specified in your service profile. These are run before Connection Manager establishes a connection to your service. For actions that relate specifically to dialing, use pre-dial actions. For actions that relate specifically to tunneling, use pre-tunnel actions, not pre-dial actions.

You cannot set up a pre-connect action that requires an interaction with your service. If interaction is required for part of the action, split the action into a pre-connect action and either a pre-tunnel or post-connect action, depending on the interaction requirements.

For example, recording information to a local log at the start of the logon process can be a pre-connect action, but if you want the log to post to your service, you might set up a separate upload program to be run as a post-connect, or disconnect action.

Pre-dial actions

Connection Manager runs pre-dial actions after users click Connect but before the computer starts to dial the connection to your service. Pre-connect actions run before pre-dial actions.

For example, pre-dial actions might include a program to change the telephone number for the service profile, or they might include a program that affects how the profile dials the connection.

Pre-tunnel actions (for VPN connections only)

Connection Manager runs pre-tunnel actions after establishing a connection with the Internet server but before establishing a tunnel to the VPN server. This type of action is available only if you set up VPN in your service profile, and it will run only when users are using the VPN connection option.

For VPN connections, set up all custom actions that require interaction with an Internet server as pre-tunnel actions, because Connection Manager has limited access to an Internet server after a tunnel is established.

For example, this might be a program that verifies user credentials for accessing a corporate server behind a firewall or that checks the expiration dates of client certificates.

For direct VPN connections, Connection Manager runs both pre-connect and pre-tunnel actions before connecting.

Post-connect actions

Connection Manager runs post-connect actions after establishing a connection or, if using a VPN connection, after establishing the tunnel. Each post-connect action that you specify in the CMAK wizard runs every time the user connects to your service, whether the connection is a dial-up connection or a direct connection.

In the CMAK wizard Custom Actions pane, you might have the following built-in post-connect action:

  • Download phone-book updates. If you set up the service profile to automatically download phone book updates, Connection Manager includes this post-connect action which sends a phone book request to the server running Phone Book Service (PBS). The server compares the client phone-book version with the most recent files available at the server and then downloads any available phone-book updates. The next time the user starts Connection Manager, the updated access numbers are available. You must provide the name of the phone book and the URL of the PBS server in order to set up this custom action. For more information on phone book updates, see Connection Point Services and Connection Manager.

Note

  • If you have Connection Manager 1.0 service profiles that include connect actions, you should know that custom actions in Connection Manager 1.3 are the same as connect actions in Connection Manager 1.0. In fact, in Connection Manager 1.3, post-connect actions are specified in the [Connect Actions] section of the .cms file, as there is no section with the title of [Post-Connect actions]. This terminology has been maintained to support migration from the previous version.

Monitored actions

Connection Manager runs monitored actions after establishing a connection and, for a VPN connection, after establishing the tunnel. Each monitored action that you specify in the CMAK wizard runs every time the user connects to your service, whether the connection is a dial-up connection or a direct connection. Monitored actions cause the connection to end after specified programs have ended. For example, if you want to automatically run an e-mail program, and then automatically end the connection when the user quits the e-mail program, you must set up e-mail as a monitored action.

Monitored actions are similar to post-connect actions, except that:

  • All monitored actions must be .exe files, because monitored actions are run asynchronously. A dynamic-link library (DLL) runs synchronously, so it cannot be run as a monitored action.

  • Connection Manager automatically monitors the status of all monitored actions and starts the disconnect sequence when the last monitored action closes.

Note

  • When the last monitored action closes, Connection Manager provides a prompt to allow the user to override the disconnect sequence. The user can click Stay Online to prevent disconnection, click Disconnect Now to disconnect immediately, or do nothing to let the connection close automatically after 30 seconds have elapsed.

As with post-connect actions, you must provide the appropriate information for each monitored action specified in the service profile, including the application to run, whether to include the application in the service profile, and any command-line parameters that you want to run with the application. Unlike post-connect actions, you do not specify a descriptive name for a monitored action.

Important

  • Specify only applications that are complete program files. You can include only one file for each monitored action. If you specify an application that requires other files or is a self-extracting executable (.exe) file as a monitored action, these files might cause the program or connection to be interrupted. If a monitored action requires any files in addition to the executable file, you should specify them as Additional Files in the CMAK wizard. These files will be installed with the service profile but not run. For more information on how to include these support files in the service profile, see Including additional files.

You can specify a variety of applications as monitored actions. For example, you might want to include a commercially available e-mail application, a customized stock-ticker application, and an internal accounting application. The CMAK wizard can specify all three types of applications. You can also select whether the application for each monitored action is to be included in your service profile.

Notes

  • If you have Connection Manager 1.0 service profiles that include connect actions, you should know that Monitored Actions in Connection Manager 1.3 are the same as Auto Applications in Connection Manager 1.0. In fact, in Connection Manager 1.3, you specify monitored actions in the [Auto-Applications] section of the .cms file, because there is no section with the title of [Monitored Applications] in that file. This terminology has been maintained to support migration from the previous version.

  • If the application is one that users already have installed on their computers, do not include it in the service profile. Doing so will increase the size of your service profile and might cause problems on the users' computers.

  • You should not specify Internet Explorer 4.0 or 4.01 as a monitored action if your users have installed an active desktop. Upgrading your users to the most recent version of Internet Explorer is advisable if you want to specify Internet Explorer as a monitored action.

Disconnect actions

Connection Manager runs disconnect actions immediately before disconnecting from your service. You can use a disconnect action for routine administration. For example, you might set up a custom action to collect status information from your service, such as total minutes online (if this information is tracked by your service). This information can then be displayed for the user.

Important

  • Disconnect actions will run even if the disconnect was not initialized by Connection Manager. For example, if the user's connection is terminated by a disruption in telephone service, Connection Manager will attempt to run the disconnect actions specified in the service profile after the unexpected termination.

On cancel actions

As soon as users click Cancel during a connection attempt, Connection Manager runs the on cancel actions you have specified in the service profile. On cancel actions do not run if the user clicks the Cancel button to close the Connection Manager program. You might use on cancel actions to reverse any pre-init actions you specified in the service profile.

On error actions

Connection Manager runs on error actions whenever an error occurs during the connection. You might use on error actions to collect information about the error for later support.

What types of programs can be used as custom actions?

A custom action can be:

  • A dynamic-link library (DLL)

  • An executable file such as a .bat, .exe, or .cmd file

  • A shell-executable file, such as a .txt or .doc file

Only DLLs run synchronously, meaning that Connection Manager starts the action and then waits for the function to return before continuing. The first argument, specified as the Parameters in the Add/Edit Custom Actionspane of the CMAK wizard, is the function name within the DLL to call. The syntax for each of these custom actions is:

HRESULT WINAPI function
    [IN] HWND hWndParent
    [IN] HINSTANCE hinstDll
    [IN] LPCSTR pszCommandLine
    [IN] DWORD dwReserved

Supported DLL parameters are:

Parameter Result

hWndParent

Handle to the Connection Manager logon dialog box or NULL; used as the parent window for any user interface displayed by the custom action.

hinstDll

Handle to the instance of this DLL.

pszCommandLine

String pointer to the command-line arguments.

dwReserved

Reserved for future use.

DLLs often have a comment (entered in the description field of the CMAK wizard) that appears while it is being run. This comment has the form Running Custom Action Description. The Connection Manager window is frozen and does not accept input while this type of action runs.

Custom action DLLs require a return value. If the return value is less than 0, the DLL call failed (SUCCEEDED macro returns False). In the case of a failure, an error message (including the return value) is displayed in the form "Custom Action Description failed return value." If a pre-init, pre-dial, pre-connect, pre-tunnel, or post-connect DLL action fails, the connection attempt is ended.

The DLL is unloaded after the function call.

Notes

  • For .dll files that require extended times for the program to run, you should implement WM_PAINT messages in the .dll file to ensure that graphics are not disrupted by user actions.

  • You must provide the exact name of exported functions when building custom action DLLs. If you are using a language that changes the exported name (such as C++), you can use a .def file to preserve the exported function names.

Including executable files

This type of custom action is run asynchronously, which means that Connection Manager starts the executable, including any command-line parameters, and continues without waiting for the process to exit. No comment appears in the Connection Manager status pane while these programs are run.

Including shell-executable files

These actions run asynchronously. Each shell-executable file needs to be opened by a particular program.

If this program is not included in Microsoft operating systems, you might need to include it with your service profile.

How to specify a custom action

In the CMAK wizard Custom Actions pane, click New to add a custom action or Edit to edit an existing custom action. A dialog box will appear, where you must provide the following information for each custom action:

  • Description: Provide a short description of the program to run. If you do not provide a description, the CMAK wizard uses the program name (specified in the Program to run) as the description.

  • Program to run: Specify the file name of the program or file, including the file extension (such as .dll, .exe, .bat, or .cmd).

  • Parameters: Specify any command-line parameters that you want to run with the program. The following special command-line parameter macros are supported:

    Macro Replaced with

    %ServiceName%

    The service name of the profile.

    %UserPrefix%

    The user-name prefix used for this connection.

    %UserSuffix%

    The user-name suffix used for this connection.

    %UserName%

    The user name, without any specified realm user-name prefix or suffix.

    %Profile%

    The location and file name of the active connection profile (.cmp) file.

    %ServiceDir%

    The path to the profile directory.

    %Domain%

    The domain for the connection.

    %InetUserName%

    The user name for the Internet connection.

    %ConnectionType%

    A value that identifies the connection type, 0, 1 or 2.

    0 = dial-up

    1 = direct

    2 = double-dial (also known as VPN)

    %DialRasPhoneBook%

    The full path to the phone book file.

    %TunnelRasPhoneBook%

    The full path to the phone book file used for the VPN portion of this connection.

    %DialRasEntry%

    The service name or remote access entry name for the dial-up connection.

    %TunnelRasEntry%

    The service name or remote access entry name for the tunnel connection.

    %AutoRedial%

    A Boolean value that is 1 if this dial attempt is an automatic redial, or 0 if not an automatic redial.

    %PopName%

    The description for the phone number in the CM phone book.

    %ErrorCode%

    The Win32 error code.

    %LastErrorSource%

    The origin of the last error.

    %CurrentFavorite%

    The location settings selected in the Use settings for box.

    %TunnelServerAddress%

    The IP or DNS address of the VPN server, if any.

    %ClientIPAddress%

    The IP address of the computer on which the Connection Manager profile is installed.

    %ServerIPAddress%

    The IP address of the remote access server, if any.

    %Interactive%

    A Boolean value, used in a custom action to determine whether or not to display a user interface. You can incorporate this macro in a custom action to display an interactive user interface (such as an error message) only when Connection Manager is running in an interactive state, and to take other action (such as failing gracefully without an error message) when Connection Manager is running in a non-interactive state. This macro was designed to be used in conjunction with the Program interacts with the user check box. For example, if you deselect Program interacts with the user, you should add the %interactive% macro to the custom action parameters so that the custom action can behave according to the state in which Connection Manager is run. This might require modification to the custom action itself.

When parameters are specified, Connection Manager reads the parameter string and passes it to the pszCommandLine parameter of the .dll or sends it as part of the command line to an executable (available through the Windows API GetCommandLine).

If the custom action is a DLL, then the first token of the parameter string is the function entry point to call. This token is removed from the parameters before the string is passed to the DLL (so the pszCommandLine string does not start with the .dll entry point name as the first parameter). When creating the DLL, ensure that the exported name of the DLL matches the name specified as the first parameter, as name decoration can result in different names. (For example, in C++, name decoration can cause the exported name to be different from the actual function name.)

If you use the macros shown in the previous table, Connection Manager replaces them with the actual run-time information for the parameter. For instance, if you wanted a custom action to collect information about which users are using which POPs, you might create a .dll (or other executable) for this purpose, and Connection Manager could pass it information such as user name (using the **%UserName%**macro), realm information (using the %Prefix% or %Suffix% macro), and POP name (using the %PopName% macro). To do this, in Parameters, type the following: LogUserAndPopToServer %UserPrefix% %UserName% %UserSuffix% %PopName% https://logserver.awesome.microsoft.com%AutoRedial%

Depending on the user connection method, the information passed to the DLL might be:

NULL jobrown @awesome.microsoft.com "Seattle 28,800" https://logserver.awesome.microsoft.com0

Connection Manager cannot denote a null pointer in a string, so it passes the string NULL (which it passes for all undefined parameters). Only use quotes when a parameter contains spaces, such as "Seattle 28,800". The number variables have to be parsed from the string. If you are using an executable other than a DLL, the function name (in the above example, LogUserAndPopToServer) is not required.

  • Action Type: Specify the time at which the action is performed by selecting Pre-init, Pre-connect, Pre-dial, Pre-tunnel, Post-connect, Monitored, Disconnect, On cancel, or On error.

  • Run this custom action for: Specify what kinds of connections for which this custom action should be run. You can choose to run this action for All connections, All connections that involve dial-up, All connections that involve a tunnel, Connections that use only a tunnel, or Connections that use only dial-up.

  • Include the custom action program with this service profile. Select this check box to include the program with the service profile. If the program you want to run is not part of a standard Windows operating system or is not otherwise available to your users, you should include the program in your service profile. The custom action program is installed in the service profile folder.

  • Program interacts with the user. This check box is selected by default. If this check box is selected, Connection Manager will not run the custom action if it is in a non-interactive state. If this check box is not selected, a program called by the custom action that interacts with the user will halt the connection process indefinitely, waiting for a response from the user. For more deterministic behavior, you can deselect this check box and use the %interactive% macro.

Specify only programs that are complete program files. You can include one program file per custom action. If any non-executable files are required to support a custom action, you should include them as additional files, not as custom actions. These additional files should be files that are installed with the service profile but do not have to be run. For more information on how to include these support files in the service profile, see Including additional files.

Important

  • If a custom action runs when users log on to Windows, the custom action runs with system permissions. You should ensure that any custom actions that you enable do not pose unintended security risks.

Notes

  • Custom actions are run in the order shown in the CMAK wizard.

  • Not all system macros are supported on all Windows operating systems.

  • By default, custom actions are not run when a profile is used to log on to Windows. For more information about whether to enable custom actions for use when logging on to Windows, see Incorporating Connection Manager with logon security.

  • If you want settings not found in the Connection Manager macros, other settings can be accessed programmatically through remote access Application Programming Interfaces (APIs), which are documented in the Microsoft Web site.

  • Sample code for a custom action that dynamically updates the proxy server setting for direct Internet connection users based on their selection of a VPN server is available in the Remote Access Service sample section of the Microsoft Platform Software Development Kit. For more information, see the Microsoft Web site.