VkMsgClient(3x)

NAME
     VkMsgClient - ViewKit application interface to the ViewKit Message
     Facility

HEADER FILE
     #include <Vk/VkMsgClient.h>

PUBLIC PROTOCOL SUMMARY
   Constructor/Destructor
          VkMsgClient(VkMsgFacilityCallback callback,
                      void *client_data);

          void ~VkMsgClient(void);


   Message Patterns
           void registerPattern(char* op,
                      VkMsgCategory category = VK_MSG_OBSERVE);

           void updatePatterns(void);

           VkMsgStatus registerPattern(VkMsgPattern pat);

           VkMsgStatus unregisterPattern(VkMsgPattern pat);

           VkMsgStatus destroyPattern(VkMsgPattern pat);


   Message Actions
           VkMsgPattern addAction(char* op, VkMsgClientAction proc,
                                  void *client_data,
                                  VkMsgActionType type,
                                  Boolean deleteMessage = True);

           VkMsgPattern createAction(char* op, VkMsgClientAction proc,
                                    void *client_data,
                                    VkMsgActionType type,
                                    Boolean deleteMessage = True);

           void removeAction(VkMsgPattern pat);

           Boolean findAction(char* name, VkMsgClientAction* proc,
                              void **client_data,
                              Boolean *deleteMessage);


   Message Translations
           void addTranslation(char* name,
                               VkMsgClientAction proc,
                               void *client_data,
                               Boolean deleteMessage = True);

           void removeTranslation(char* name);


   Sending Notices
           void sendNotice(char* op, int argc, VkMsgArg* argv);

           void sendNotice(char* op);

           void sendStringNotice(char* op ...);

           void sendIntNotice(char* op ...);

           void sendFileNotice(char* op, char* file,
                               int argc, VkMsgArg* argv);

           void sendFileNotice(char* op, char* file);

           void sendStringFileNotice(char* op, char* file ...);

           void sendIntFileNotice(char* op, char* file ...);


   Sending Requests
           VkMsgMessage sendRequest(char* op, int argc,
                                    VkMsgArg* argv);

           VkMsgMessage sendRequest(char* op);

           VkMsgMessage sendSyncRequest(char* op, int argc,
                                        VkMsgArg* argv,
                                int timeout = DEFAULT_SYNC_TIMEOUT);

           VkMsgMessage sendSyncRequest(char* op,
                                 int timeout = DEFAULT_SYNC_TIMEOUT);

           VkMsgMessage sendFileRequest(char* op, char* file,
                                         int argc, VkMsgArg* argv);

           VkMsgMessage sendFileRequest(char* op, char* file);

           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                                           int argv, VkMsgArg* argv,
                                 int timeout = DEFAULT_SYNC_TIMEOUT);

           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                                 int timeout = DEFAULT_SYNC_TIMEOUT);


   Composing Message Arguments
           void composeBegin(void);

           void composeAdd(VkMsgArg* arg);
           void composeAdd(char* val, VkMsgMode mode = VK_MSG_IN);

           void composeAdd(int ival, VkMsgMode mode = VK_MSG_IN);

           void composeAdd(unsigned char* bval, int len,
                           VkMsgMode mode = VK_MSG_IN);

           VkMsgArg* composeList(void);

           int composeNum(void);




CLASS DESCRIPTION
     VkMsgClient is the normal way application code interacts with the message
     facility.  There are methods for sending and receiving messages,
     installing message actions, and registering interest in message patterns.

FUNCTION DESCRIPTIONS
   VkMsgClient()
           VkMsgClient(VkMsgFacilityCallback callback,
                      void *client_data);

           void ~VkMsgClient(void);


          The callback is called whenever messages are received for this
          client.

          However, usually messages are handled through message-specific
          callbacks (actions).  See the addAction() method.

   registerPattern()
           void registerPattern(char* op,
                         VkMsgCategory category = VK_MSG_OBSERVE);


          Express interest in messages whose operator string match the first
          argument.  The second argument should be VK_MSG_OBSERVE or
          VK_MSG_HANDLE to deal with notices or requests, respectively.

          However, usually messages are handled through message-specific
          callbacks (actions).  See the addAction() method, which
          automatically creates and register patterns.

   updatePatterns()
           void updatePatterns(void);

          Call updatePatterns when you want to add new message patterns after
          connecting to the ToolTalk service.  To be safe, call this method
          after you are done using the addAction() and registerPattern()
          methods.

   addAction()
           VkMsgPattern addAction(char* op,
                                  VkMsgClientAction proc,
                                  void *client_data,
                                  VkMsgActionType type,
                                  Boolean deleteMessage = True);


          Add a message-specific callback.  The first argument is the message
          operator string.  The second and third arguments are the callback
          and callback data to call.  The fourth argument is the type of
          action, VK_MSG_ACTION_OBSERVE (notices), VK_MSG_ACTION_HANDLE
          (requests), VK_MSG_ACTION_HANDLE_SPECIFIC (requests matching the
          exact pattern), VK_MSG_ACTION_REPLY (replies to requests),
          VK_MSG_ACTION_FAIL (failed requests), VK_MSG_ACTION_START (autostart
          of handlers to service requests).  The last argument specifies
          deletion of the message after the callback returns.

          Be sure to add your message actions before entering any Xt event
          loop.  Otherwise, messages may be received before the action is
          registered, and they will not be processed as expected.  The Xt
          event loop is entered when you call VkApp::run(), or when you post a
          ViewKit dialog and a short, secondary event loop is entered.

   createAction()
           VkMsgPattern createAction(char* op,
                                     VkMsgClientAction proc,
                                     void *client_data,
                                     VkMsgActionType type,
                                     Boolean deleteMessage = True);


          Creates a message action, but doesn't register it yet.  You can then
          use ToolTalk routines like VkMsgPatternArg() to add argument types
          and values to the pattern before registering it with the
          registerPattern() method.  Use the registerPattern() method to
          register your pattern.

   removeAction()
           void removeAction(VkMsgPattern pat);


          Removes an action.  The pattern is automatically unregistered.

   addTranslation()

           void addTranslation(char* name,
                               VkMsgClientAction proc,
                               void *client_data,
                               Boolean deleteMessage = True);


          When using resource-specified patterns (vkmsgTranslations), adds a
          callback for the named translation.  Similar to the addAction()
          method.

   removeTranslation()
           void removeTranslation(char* name);


          Removes a translation.

   findAction()
           Boolean findAction(char* name,
                              VkMsgClientAction* proc,
                              void **client_data,
                              Boolean *deleteMessage);


          Looks for a named action in this client for the operator string.
          Returns the callback, callback-data, and whether to delete the
          message after the callback returns.

   sendNotice()
           void sendNotice(char* op, int argc, VkMsgArg* argv);


          Send a notice.  The first argument is the operator string, the
          second argument is the number of message arguments, and the third
          argument is the array of message arguments.  Message arguments come
          in three types, VK_MSG_INT_MSG_ARG_TYPE, VK_MSG_STRING_MSG_ARG_TYPE,
          and VK_MSG_BSTRING_MSG_ARG_TYPE.  Message arguments come in three
          modes, VK_MSG_IN, VK_MSG_OUT, and VK_MSG_INOUT.


           void sendNotice(char* op);


          Send a notice.  The first argument is the operator string, and the
          composed message arguments list is used (see the composeBegin and
          composeAdd methods).

   sendStringNotice()
           void sendStringNotice(char* op ...);

          Send a notice with only string arguments.  The first argument is the
          operator string.  The remaining arguments are a NULL-terminated list
          of string arguments for the message.

   sendIntNotice()
           void sendIntNotice(char* op ...);


          Send a notice with only integer arguments.  The first argument is
          the operator string.  The remaining arguments are a NULL-terminated
          list of integer arguments for the message.  Note that you cannot
          send any zero arguments, since NULL terminates the list.

   sendFileNotice()
           void sendFileNotice(char* op, char* file,
                               int argc, VkMsgArg* argv);


          Same as the sendNotice() method, except sets the filename attribute
          to the second argument.

           void sendFileNotice(char* op, char* file);


          Same as the sendNotice() method, except sets the filename attribute
          to the second argument.

   sendStringFileNotice()
           void sendStringFileNotice(char* op, char* file ...);


          Same as the sendStringNotice() method, except sets the filename
          attribute to the second argument.

   sendIntFileNotice()
           void sendIntFileNotice(char* op, char* file ...);


          Same as the sendIntNotice() method, except sets the filename
          attribute to the second argument.

   sendRequest()
           VkMsgMessage sendRequest(char* op, int argc,
                                    VkMsgArg* argv);


          Send a request.  The first argument is the operator string, the
          second argument is the number of message arguments, and the third
          argument is the array of message arguments.

           VkMsgMessage sendRequest(char* op);


          Send a request.  The first argument is the operator string, and the
          composed message arguments list is used (see the composeBegin() and
          composeAdd() methods).

   sendSyncRequest()
           VkMsgMessage sendSyncRequest(char* op, int argc,
                                        VkMsgArg* argv,
                              int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the sendRequest() method, but simulates a synchronous request
          where we wait for the reply message.  The reply message is returned,
          NULL if no reply was received within the timeout period.  The last
          argument specifies the timeout period in seconds, and defaults to
          60.  The resource value for "defaultSyncTimeout" will override this
          default.  Using a timeout of zero will disable the timeout
          completely.  Use VkMsgDestroy to destroy the reply when done.

           VkMsgMessage sendSyncRequest(char* op,
                       int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the sendSyncRequest() method, but uses the composed message
          arguments list.

   sendFileRequest()
           VkMsgMessage sendFileRequest(char* op, char* file,
                                        int argc, VkMsgArg* argv);


          Like the sendRequest() method, but sets the filename attribute to
          the second argument.

           VkMsgMessage sendFileRequest(char* op, char* file);


          Like the sendRequest() method, but sets the filename attribute to
          the second argument.

   sendSyncFileRequest()
           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                                           int argv, VkMsgArg* argv,
                               int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the sendSyncRequest() method, but sets the filename attribute
          to the second argument.

           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                           int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the sendSyncRequest() method, but sets the filename attribute
          to the second argument.

   composeBegin()
           void composeBegin(void);


          Initialize and clear the composed message arguments list.

   composeAdd()
           void composeAdd(VkMsgArg* arg);


          Add an argument to the composed message arguments list.  The
          VkMsgArg structure contains the type, value, and mode of the
          argument.

           void composeAdd(char* val,
                           VkMsgMode mode = VK_MSG_IN);


          Add a string argument to the composed message arguments list.  The
          second argument indicates the mode, and defaults to VK_MSG_IN.

           void composeAdd(int ival,
                           VkMsgMode mode = VK_MSG_IN);


          Add an integer argument to the composed message arguments list.  The
          second argument indicates the mode, and defaults to VK_MSG_IN.

           void composeAdd(unsigned char* bval,
                           int len,
                           VkMsgMode mode = VK_MSG_IN);


          Add a binary string argument to the composed message arguments list.
          The second argument indicates the mode, and defaults to VK_MSG_IN.

   composeList()
           VkMsgArg* composeList(void);


          Returns the composed message arguments list.

   composeNum()

           int composeNum(void);


          Returns the size of the composed message arguments list.

   registerPattern()
           VkMsgStatus registerPattern(VkMsgPattern pat);


          Register a pattern created by the createPattern method and express
          interests in those messages.  Once a pattern is registered, messages
          will be received which match the pattern.

   unregisterPattern()
           VkMsgStatus unregisterPattern(VkMsgPattern pat);


          Unregister a previously-registered pattern from the registerPattern
          method.  Messages will no longer be received for that pattern.

   destroyPattern()
           VkMsgStatus destroyPattern(VkMsgPattern pat);


          Destroy patterns created by the registerPattern or createPattern
          methods.  Destroying a pattern automatically unregisters it.

CLASSES USED BY THIS CLASS
     VkMsgFacility, VkMsgService

KNOWN CLASSES THAT USE THIS CLASS
     VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgService, VkMsgWindow

SEE ALSO
     VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgFacility, VkMsgService,
     VkMsgWindow
     ViewKit Programmer's Guide
     The X Window System, DEC Press, Bob Sheifler and Jim Gettys
     The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
     The OSF/Motif Programmers Reference, Prentice Hall, OSF