Custom Commands

You can add custom functions to your Mail menus with custom commands. A custom command is one that you add to a menu to perform a unique function tailored to your needs.

There is a second type of custom command not associated with any menu, but which can be set to run whenever the user starts Mail, exits Mail, or receives a new message.

A custom command is implemented as a dynamic-link library (DLL). Any executable code — including batch files or applications — can be run from a custom command. Here are some examples of how custom commands can be used to tailor Mail for specific needs:

• Display a window that contains information specific to where the user works, such as a parts list or a list of stock quotes.
• Query a database without leaving Mail.
• Launch another application and open a specific file. For example, users can create a command to open a MEMOS.TXT file in the Windows Notepad application.

Installing Custom Commands

You can install custom commands on the local computer for use by a single user or centrally on the postoffice to be shared by all users. Installing the command on the postoffice eases installation and administrative tasks, and saves space on other users' hard disks.

Once installed, these custom commands can appear to users as built-in features. You can install up to 1000 custom commands in Mail. If you install several custom commands, you can add separator bars between groups of commands to help organize the menu's appearance.

To install custom commands for a user on an individual computer, you need to modify the Registry on that computer for each custom command and supply the appropriate DLLs. To install custom commands for everyone who uses a postoffice, you need to modify the Registry for each user, modify the SHARED32.INI file on the postoffice computer, and add the DLLs to the postoffice computer.

Note Typically, the Setup program that installs the custom commands automatically modifies entries in your computer's Registry and in the postoffice computer's SHARED32.INI file. The information in the following sections is for your reference if you need to make the modifications yourself.

Starting Separate Applications

Mail expects that a custom command will be implemented as a DLL. A custom command can launch an application. The DLL can pass information about the command to the application when it starts.

Although Mail always calls a DLL, the DLL can pass information to an application by using Windows dynamic data exchange (DDE), command-line parameters, or a disk file. If the called application is already running, the DLL transfers information most efficiently using DDE. If the DLL uses a disk file, care should be taken so that multiple temporary files are not added to the user's disk. The application that implements the custom command runs independently of Mail.

Installing a Custom Command for a Single User

To install a custom command for a single user on an individual computer, follow these steps:

1. Copy the DLL for the custom command to the SystemRoot\SYSTEM32 directory of your hard drive.
2. Add a custom command entry to the Registry on your computer in HKEY_CURRENT_USER\Software\Microsoft\Mail\Custom Commands. For information on how to do this, see "Custom Command Entries for Mail" in Chapter 14, "Registry Value Entries."
3. Quit Mail if it is running, and then restart it. Mail reads your Registry and adds the custom command.

Installing a Custom Command on the Postoffice

If you have a custom command that you want to make available to multiple users, you can install the command on the postoffice instead of in each user's Registry. When you create a new custom command, you must include a SharedExtensionsDir entry in this key in each user's Registry:

HKEY_CURRENT_USER\Software\Microsoft\Mail\Microsoft Mail

This entry instructs Mail to check the server's SHARED32.INI file for custom command entries.

Mail finds the SharedExtensionsDir entry in the user's Registry, then reads entries for custom commands in SHARED32.INI before returning to the user's Registry to read any custom command entries there.

For example in Figure 8.4, Mail reads the SharedExtensionsDir entry in the user's Registry first. Then it reads the entries in the [Custom Commands] section of SHARED32.INI (in this case, the lines labeled tagA= and tagB=). After reading all of the custom command entries in SHARED32.INI, Mail reads entries in the key of the user's Registry (in this case, the entries labeled tag1 and tag2):

HKEY_CURRENT_USER\Software\Microsoft\Mail\Custom Commands

Figure 8.4 File Interaction with Shared Custom Commands

The directory on the postoffice share specified by SharedExtensionsDir in the Registry contains the SHARED32.INI file as well as the DLLs that implement shared custom commands.

Mail can check a server for custom commands and custom messages in the following ways:

• When you use a dynamic connection to the postoffice
• When you manually connect to the postoffice before starting Mail

The syntax you use with the SharedExtensionsDir entry in the Registry reflects the way you choose to connect. The SharedExtensionsDir entry uses the following syntax:

SharedExtensionsDir:REG_SZ:\\server\share\pathname [password]

– Or –

SharedExtensionsDir:REG_SZ:pathname

When you want to dynamically connect to the server's shared disk, use the \\server\share\pathname option with SharedExtensionsDir. Use the pathname option with SharedExtensionsDir to point to a manual connection to the server's shared disk.

To install a shared custom command, follow these steps:

1. Create a shared Mail extensions directory on the postoffice.
2. Copy the custom command DLL to the shared extensions directory.
3. A sample SHARED32.INI file is included on the Windows NT Resource Guide disks. Copy this file to the shared extensions directory.
4. Add custom command entries to the [Custom Commands] section of the SHARED32.INI file on the postoffice, using the following syntax:

   tag=Mail version; menu; name; position; DLL name; command;
   event map; status text; Help file; Help context

Note The custom command entries should be a single command line in the SHARED32.INI file. Don't add any carriage returns even if line-wrapping occurs.

Values are defined in the following table.

5. In the Registry on your computer, add a SharedExtensionsDir entry to reference the shared extensions directory in the following key:

   HKEY_CURRENT_USER\Software\Microsoft\Mail\Microsoft Mail

   For information about SharedExtensionsDir, see "Microsoft Mail Entries" in Chapter 14, "Registry Value Entries."

6. If you have chosen the manual connection method, make the necessary network connection using File Manager.
7. Quit Mail if it is running, and then restart it.

   Mail rereads your Registry and adds the shared custom command to the specified menu.

8. Test the shared custom command.
9. When the custom command works successfully on your computer, modify each user's Registry to have access to the shared extensions directory. (See step 5.)