1.3 Subscribe and Publish
GroupWise Tokens is comprised of three APIs that subscribe and publish the tokens, as shown below.
Figure 1-2 Subscribe and Publish Tokens
The APIs include:
-
One Token Subscribing API: Third-Party Handler DLL API
-
Two Token Publishing APIs:
-
Token Commander API
-
Dynamic Data Exchange (DDE) API
-
All three of the APIs use tokens at the core. Tokens are subscribed by or published by one of the token APIs.
1.3.1 Token Subscribing
Subscribing to tokens is the process whereby a third-party application is given a token as it is published before the GroupWise default token handler processes the token. The Token Commander and DDE are ways to publish token events.
Third-Party Handler DLL API
The TPH DLL API allows you to enhance the user’s experience with the GroupWise client by allowing third-party applications to subscribe to internal token events. The TPH DLL API is the mechanism that allows a third-party application DLL to subscribe to token events. A TPH DLL can monitor the token stream listening for tokens that are of interest to the application. TPH DLLs are automatically loaded by the GroupWise client at startup. TPH DLLs are loaded before GroupWise C3PO DLLs are loaded.
The set of all TPH DLLs for a particular workstation are referred to as the third-party DLL chain. The DLLs in the third-party chain have the opportunity to process a token before it is processed by GroupWise. Tokens are always first passed to the third-party chain where any TPH DLL can modify, remove, or ignore any given token. If a TPH DLL modifies or removes a token, all subsequent TPH DLLs in the chain will receive the modified token, or will not receive the deleted token. After all TPH DLLs in the third-party chain have evaluated the token, if it is still in the token stream GroupWise will process the resulting token.
The following figure illustrates the behavior of TPH during initialization, operation, and shutdown of the GroupWise client.
Figure 1-3 TPH Behavior
TPH Interface Requirements
The TPH DLL Interface requires the following:
-
A Windows Registry entry must be added informing the GroupWise client that the TPH DLL wants to be added to the third-party chain.
Key "HKEY_CURRENT_USER\Software\Novell\GroupWise\Client\Third Party"
Item Name "DLLx" (where x is a number starting at 1)
Item Type STRING
Item Data <DLL path and file name>
When inserting a TPH DLL entry into the registry, care should be taken to not overwrite any existing TPH DLL entries already registered. Do not always assume your TPH DLL will be DLL1.
You can also register your TPH DLL under HKEY_LOCAL_MACHINE (in addition to HKEY_CURRENT_USER). The full path and contents of the registry entry are the same for HKEY_LOCAL_MACHINE. This allows a TPH DLL to be registered once per machine (rather than requiring it to be registered for each user on a specific machine).
DLLS that were registered using HKEY_CURRENT_USER get priority in the call chain over those that were registered with HKEY_LOCAL_MACHINE. For example, if DLL1 and DLL2 were each registered under HKEY_CURRENT_USER, they would both be called before anything registered under HKEY_LOCAL_MACHINE.
DLLs that were registered using HKEY_LOCAL_MACHINE use the same naming convention for the reg entries (DLL1, DLL2, etc.,) regardless of what might be registered under HKEY_CURRENT_USER. (One DLL might be registered as DLL1 under HKEY_CURRENT_USER and another DLL might be registered as DLL1 under HKEY_LOCAL_MACHINE.)
-
The following platform specific requirements must be met:
-
For C++ DLLs, the C++ Structure Member Alignment must be set to 1-byte alignment. On some compilers 8-byte alignment is the default. The GroupWise client was written in C++ and was compiled with 1-byte alignment. If the TPH DLL alignment is not 1-byte, you can experience random memory errors in the Kernel32.dll, and the token data structures will not contain discernible data. In C++, make sure the methods are declared with the WINAPI calling convention. For example, the Exit method would be written as: WORD WINAPI Exit(void)
-
In Delphi, make sure the methods are declared with the stdcall calling convention. For example, the Exit method would be written as: Function Exit: SmallInt; export; stdcall;
-
Visual Basic and other programming languages that can create Win32 DLLs, can be used to create TPH DLLs.
-
The DLL is required to export seven methods in a specific order to allow GroupWise to load the DLL. The TPH DLL entry points are called using their ordinal values.
The methods are to be exported in the following order:
|
Export Order |
Description |
|---|---|
|
1. TPHVersion |
Reserved. Even though it is currently not called by GroupWise, it must be included. |
|
2. Compatibility |
Called during the initialization process. It passes the GroupWise client version to the TPH via this method. You can determine the version by evaluating the high and low order bytes of the AppVersion parameter. |
|
3. TimeStamp |
Reserved. Even though it is currently not called by GroupWise, it must be included. |
|
4. Entry |
Used to initialize your TPH specific data. The GroupWise client language is also passed as a parameter to the TPH via this method. You can determine the language by evaluating the high and low order bytes of the wLanguage parameter. |
|
5. Exit |
Called during the shut down process. It is where you can clean up any memory you allocated. |
|
6. HandleToken |
Called whenever a token is published by the GroupWise client. The token is then passed as a parameter.This is the heart of the TPH process. By evaluating the token parameter, you can determine what token was published as well as any token related data in the token structure. |
|
7. ValidateToken |
Reserved. Even though it is currently not called by GroupWise, it must be included. |