1.1 Token APIs and Tokens Defined

The GroupWise Windows client uses 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 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:

A token in GroupWise is used to represent a structure of information. The token structure contains numerous properties, including

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 NewAppointment() 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];
}

Tokens are published internally as a result of low level events such as a mouse click or a key being pressed. These tokens are analogous to Windows messages (i.e. WM_SIZE). Tokens are also published as a result of higher level events like a user replying to a message. Whether or not a token works properly depends upon the context when the token is published. For example, the Type() (AFTKN_TYPE) token can be used to simulate the keyboard to type some text. If a message view is opened and the focus is on the message body field, then the context is valid because you can type text in the message body field. If the focus is on the list of messages in your mailbox, publishing the Type() token will return an error because the context is invalid. There is nothing to receive the text the token will type.

Another example of how a token works is when you press the reply button, the client will publish the ItemReply (BFTKN_REPLY) token. The token router functionality in the client will call the proper token handler to process the token. This token handler causes the reply message view to be displayed and the proper information inserted into the view. In the ItemReply() token, the token parameters contain information on whether the reply is to go to everyone or just the sender of the original message, and whether or not the original message text is inserted into the reply message.