2.5 Subscribing To Tokens

This section covers the following:

As mentioned earlier, all tokens are passed to the TPH method HandleToken(). This is the heart of the TPH. The HandleToken() method contains three parameters. The first parameter is the token data structure. It contains all the token specific information about the token being published. The second parameter is the handle to the link window. This is always the GroupWise client. The third parameter is the link window execute message. This is the message the client received that caused it to publish the token. This message has no meaning in the client.

The following lines of code are added to the HandleToken() method. Here we want to “trap” the toolbar properties token DTKN_BTNBAR_EDIT. Because all external tokens are passed to the HandleToken() method, we just need to evaluate the wTokenID property. If the wTokenID was the token we were looking for, we would then call our processing code. In this case, we return the DLL_HAN_NO_ERROR value which indicates to GroupWise that we processed the token and that the GroupWise client or other TPH DLLs in the TPH chain don’t have process it. In effect it is removed from the token stream.

2.5.1 C++

int WINAPI HandleToken(LPTPH_RETURNVAL lpTokenData,
     HWND hLinkWnd,
     WORD msg )
{
     // Is the wTokenID the Toolbar edit token?
     if (DTKN_BTNBAR_EDIT == lpTokenData->lpToken->wTokenId) 
     {
          // Return the value indicating we processed the token so the
          // GroupWise client doesn't have to.
          return DLL_HAN_NO_ERROR;
     }

     return DLL_HAN_NOT_HANDLED;
}

2.5.2 Delphi

Function HandleToken(lpTokenData: LPTPH_RETURNVAL; hLinkWnd: HWND; msg: Word): SmallInt; export;  stdcall;
begin
     if (DTKN_BTNBAR_EDIT == lpTokenData.lpToken.wTokenId) then
     begin
          result := SmallInt(DLL_HAN_NO_ERROR);
     end;

     result := SmallInt(DLL_HAN_NOT_HANDLED);
end;

Now we want to alter the client functionality. Instead of discarding the edit toolbar functionality, we use it to trigger different functionality. The following code will publish the AboutDlg() (DTKN_ABOUT) token in response to the user selecting the toolbar properties menu. This shows how a TPH can intercept certain events, and inserts custom functionality in between, or instead of the default functionality. Both of the functions below use a custom method called Publish() to publish tokens using the Token Commander API. This Publish() method is defined in the sample files.

2.5.3 C++

int WINAPI HandleToken(LPTPH_RETURNVAL lpTokenData,
     HWND hLinkWnd,
     WORD msg )
{
     LPTSTR lpReturn = NULL; // Used with the Publish method
     if (DTKN_BTNBAR_EDIT == lpTokenData->lpToken->wTokenId) 
     {
          // Display the About Dialog instead by publishing a token

          lpReturn = Publish(L"AboutDlg()");
          // If lpReturn = NULL then there was an error,
          // otherwise it will be an allocated string that may or may not
          // contain a value.  You must release it when you are done.
          if ( lpReturn )
          {
               // Evaluate and process the return value here.
               // ...

               // Cleanup
               delete lpReturn;
               lpReturn = NULL;
          }

          // Return the value indicating we processed the token so the
          // GroupWise client doesn’t have to.

          return DLL_HAN_NO_ERROR;
     }

     return DLL_HAN_NOT_HANDLED;
}

2.5.4 Delphi

Function HandleToken(lpTokenData: LPTPH_RETURNVAL; hLinkWnd: HWND; msg: Word): SmallInt; export;  stdcall;
var
     sResult : String;
begin
     if (DTKN_BTNBAR_EDIT == lpTokenData.lpToken.wTokenId) then
     begin
          sResult := Publish(‘AboutDlg()’);
          if ( sResult <> '' )
          begin
               // Evaluate and process the return value here.
               // ...

          end;
          result := SmallInt(DLL_HAN_NO_ERROR);
      end;

     result := SmallInt(DLL_HAN_NOT_HANDLED);
 end;