Controlling GroupWise 5 with Tokens
Articles and Tips: article
Technical Writer
GroupWare Division
01 Sep 1996
Describes the tokenization mechanism used by GroupWise 5 to enable your programs to control and monitor GroupWise client functions.
Introduction
Tokenization names low-level events such as "Save a file" or "Send mail." GroupWise 4.x used tokens to operate as a program. Your solution can control the GroupWise 5 client through a Visual Basic executable, through DLLs using the Third-Party Handler, and through DDE scripts.
The GroupWise 5 client Tools menu does not include Macro Play or Macro Record. However, it will let client users play executables from the menus, toolbar, and customized views.
This article describes GroupWise 5 tokens and explains how they can be used to obtain message IDs. It also explains how to use the Dynamic Data Exchange (DDE) and the GroupWise Third-Party Handler to let your DLLs monitor the GroupWise token stream.
Message IDs
GroupWise creates a unique message ID for each message and uses it to identify that message. GroupWise tokens require a message ID parameter to create mail messages, retrieve appointment or task lists, and perform general workgroup messaging.
Your solution can specify message IDs as command parameters but it cannot create or modify valid IDs. Only GroupWise itself can create, modify, or delete a message ID.
You can obtain valid message IDs using GroupWise tokens. For example, the ItemDelete token deletes a message:
ItemDelete( "X071F3CB43K01aR043b2f")
X071F3CB43K01aR043b2f is a parameter specifying the ID of the message to delete.
Message IDs from the Messaging API (MAPI) and other sources are compatible. For example, you can obtain a GroupWise message ID from MAPI, then use a DDE command to pass it to GroupWise.
Your solution can store message IDs outside GroupWise, then use them in GroupWise like other message IDs.
Full message IDs exist only for items stored in the GroupWise database. However, a special message ID, X00, refers to the top or last accessed GroupWise view. Use X00 to refer to:
Items being created because they include no messageID.
The current item without querying its messageID.
GroupWise maintains message IDs as long as the messages they represent remain uncorrupted in the database. After a long time or after exceptional system events, GroupWise may report an ID as invalid.
Dynamic Data Exchange
Dynamic Data Exchange (DDE) lets Windows applications communicate. Applications establish a DDE conversation and send messages to each other. A DDE conversation involves server and client applications. The server provides resources to the client. The client accepts processing or information from the server.
The DDE Management Library (DDEML) simplifies DDE management by providing a high-level interface. Use DdeInitialize( )to register an application with DDEML.
Use DdeConnect( ) to establish a conversation. A service parameter specifies an application to establish a conversation with. A topic parameter specifies the conversation topic.
A DDEML-registered application can establish a conversation with GroupWise including a service and topic name pair from the table below. The first pair is generally recommended.
DDE, GroupWise, and Your Solution
Your solution can:
Share GroupWise resources using DDEExecute().
Obtain GroupWise processing results using DDERequest().
GroupWise 5 Third-Party Handler
The Third-Party Handler (formerly WOAPI) lets your DLLs monitor the GroupWise token stream. Third-party DLLs can process tokens before GroupWise processes them, affect how GroupWise processes them, or process them instead of GroupWise.
The interaction between GroupWise and third-party DLLs is as follows:
GroupWise loads third-party DLLs at startup.
GroupWise passes tokens to the third-party DLL.GroupWise calls Entry once initially, then uses HandleToken to direct tokens.
DLLs return values indicating they did not process tokens. Otherwise, GroupWise does not process the token.
Installation
Third-party DLLs must provide their own installation and Windows Registry entries:
|
Key: |
"HKEY_CURRENT_USER\Software\Novell\GroupWise\5.0\ThirdParty" |
|
Item: |
"DLLx"(x is a number) |
|
ItemType: |
ANSISTRING |
|
ItemValue: |
<DLLpath and filename< |
DLL Loading
As GroupWise opens, it finds third-party DLLs in the Registry, then loads them in Item number order. For example, finding DLL1, DLL2, DLL4, then DLL0, GroupWise loads DLL1, then DLL2. GroupWise loads only consecutively numbered entries, starting with the first found. In the example above, GroupWise does not load DLL4 and DLL0.
Intercepting Tokens
A loaded DLL can monitor and intercept GroupWise tokens. It can then:
Let a token pass to GroupWise. DLLs can pass a token unprocessed or use a token value as a trigger to process a token, then pass it on, indicating it was unprocessed. DLLs can also generate, then pass new tokens.
Block a token. A DLL can return a token, indicating it was processed. Processed tokens are not passed to other DLLs or GroupWise. The DLL that processesa token must provide required return values.
Modify the token. DLLs can monitor the token stream, intercept a token, modify it, pass it to GroupWise as a new token, then indicate that the original token was processed or modify the token, then return a value indicating it was unprocessed.
Shared Code Removed
Novell has removed Shared Code from GroupWise 5. Shared Code no longer operates with the Third-Party Handler.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.