I am new to GroupWise programming and have...
Articles and Tips: qna
01 May 2002
Q.
I am new to GroupWise programming and have been told that programming using API Tokens is the best way to go. What can you tell me about tokens and how to use them?
A.
The GroupWise 16-bit and 32-bit Windows clients use tokens to perform various different internal functions. A tokenized application is one where low-level events are packaged into a meaningful representation or tokens, such as "Save the current message to a file" or "Create a new mail message."
These tokens are often processed by the application and become the basis for everything the application does. The GroupWise Token APIs are client-based and will work with both the 16-bit and 32-bit Windows clients.
The GroupWise client must be running for a token to be processed. If the client is not running, the Token Commander API will start up the client and then process the token. However, on some operating systems the token can be processed before the client is fully running, resulting in token failure. This problem can be solved in one of two ways:
Make sure that the GroupWise client is fully up and running before trying to access the Token Commander
Provide a delay in the application code after calling the Token Commander (such as providing a "sleep" loop) before throwing any tokens
GroupWise Tokens History... The GroupWise 4.1a 16-bit client used WordPerfect Shared Code to accomplish many features. Part of the shared code was the Macro Facility and Macro Interpreter. These programs facilitated macro recording and playback capabilities across the various different shared code-enabled applications. Tokens are the basis for the shared code macro language; macro files were analyzed and converted to the corresponding application tokens.
The GroupWise 5 16-bit client still uses shared code and has macro record and playback capabilities. The GroupWise 5 32-bit client does not use shared code. With the macro facility and macro interpreter no longer available to the 32-bit client, you cannot record or playback macros. You can however, publish tokens directly to the 32-bit client.
Note: Shared code added many tokens to the 16-bit client macro language that are no longer valid in the 32-bit client; although, there are still many 16-bit client tokens available in the 32-bit client.
What Is a Token?... A token in GroupWise is used to represent a structure of information. The token structure contains numerous properties, including:
The token ID (the token identifier)
The token parameter count
The token parameters specific to the token ID
Note that the term token and token ID often refer the same thing: the token ID. The token ID is a numeric representation for the functionality the token structure relates to.
Third-party applications can use the token identifier or the numeric value when working with the token ID. For example, the token used to display a new appointment message view is NewAppointment(). The numeric token identifier is BFTKN_SEND_STDAPPT or the decimal number 182. The term NewAppoint- ment() is the text representation of the token ID.
To maintain future compatibility, it is recommended that the numeric token identifier is used instead of the numeric value in the event the numeric values change in the future. The token structure is defined as follows:
typedef struct _tagMAC_TOKEN
{
HSZ hszCommand;
MAC_IPCVERSION Version;
HSZ hszRequestor;
MAC_MACROID dwMacroID;
ATOM atomApp;
WORD wReserved;
MAC_TOKENID wTokenId;
MAC_COUNT cParam;
DWORD dwFlags;
DWORD dwReserved;
MAC_PARAM rgParam[1];
}
For a detailed look at GroupWise Tokens, see http://developer.novell.com/ndk/doc/gwtoken/index.html?gwtokens/data/a6lsnkq.html.
* 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.