Installing a Message Handler

Message handlers must be registered before they can be used. The following registry key example shows the four registry keys that you must set in order to install and register a message handler.

[HKEY_CLASSES_ROOT\CLSID\{14EF11D0-3EC7-11d2-90BF-0000F80272E4}]
Default="stock translator"
[HKEY_CLASSES_ROOT\CLSID\{14EF11D0-3EC7-11d2-90BF-0000F80272E4}\InprocServer32]
Default="\\windows\\stock.dll"
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WIS\Routers\{14EF11D0-3EC7-11d2-90BF-0000F80272E4}]
"Type"="Translator"
Default=hex:60,2C,2A,2A,20,53,74,6F,63,6B,73,20,2A,2A
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WIS\Control\Device1\Stocks]
"PredefinedRouter"=hex:21,60,2C,2A,2A,3,74,6F,63,6B,73,20,2A,2A
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WIS\Control\Device1\News]
"MaxMsgs"=dword:10

The first two keys are COM object registry entries.

The third key registers the handler as a translator and sets the tag to be used by the router to refer to the handler. The first hexadecimal value is the constant 0x60, the second hexadecimal value is 0x20 plus the number of bytes for the tag name, and the rest of the values make up a unique ASCII name. Because the tag in this example is 12 bytes long, the second value is 0x2c.

The fourth key defines how the router routes messages through the handler. Because the first hexadecimal value is 0x20 plus the number of handlers, which is always 1, this value is 0x21. The rest of the values are the tag from the third key.

This example shows a fifth, optional, registry entry that places a limit on the number of messages held in a PMail folder for messages that arrive on this address.

This information is provided in case you need to search the registry for a problem. Wireless Services provides two functions, RegisterHandler and UnregisterHandler, that simplify the process of registering and deregistering message handlers. RegisterHandler enables you to register a message handler in any of the following ways:

• As the handler for messages received by a specific radio device and address
• As the default handler for messages received by a radio device, but that do not have an address-level handler
• As the overall default handler for any messages that do not have message handlers specified at either the radio device or the device-and-address levels

To use these functions in your program, include the Riohlp.h header file.

    To register a message handler

1. Specify the device for which the handler is to be registered.
2. Specify the address for which the handler is to be registered.

   If this value is NULL, the handler is assigned as the default handler for the device.

3. Specify a string containing the name of the DLL in which the handler is stored.
4. Call RegisterHandler, and check the return value for success.

If you want a message handler to stop handling messages received for an address or device, use UnregisterHandler. You can deregister a message handler for a specific device and address or for all device addresses.

    To deregister a message handler

1. Specify the device for which the handler is to be deregistered.
2. Specify the address for which the handler is to be deregistered.

   If this value is NULL, the handler is deregistered for all addresses on this device.

3. Specify the handler class identifier (CLSID).
4. Call UnregisterHandler, and check the return value for success.