VkMsgService(3x)

NAME
     VkMsgService - ViewKit object-oriented interface to the ToolTalk message
     service

INHERITS FROM
     VkMsgFacility

HEADER FILE
     #include <Vk/VkMsgService.h>

PUBLIC PROTOCOL SUMMARY
   Constructor/Destructor
           VkMsgService(Widget w,
                        const char* ptid = NULL,
                        const char* sessid = NULL);

           void ~VkMsgService(void);


   Registry
           void registerPatterns(VkMsgClient* client, Widget w);

           void registerClient(VkMsgClient* client,
                               VkMsgFacilityCallback callback,
                               void* client_data);

           void unregisterClient(VkMsgClient* client);

           void updatePatterns(void);

           char* mangleTranslationName(char* name,
                                       VkMsgClient* client,
                                       Boolean useCounter);


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

           VkMsgMessage sendRequest(VkMsgClient* client, char* op);

           VkMsgMessage sendRequest(VkMsgClient* client,
                                    VkMsgMessage msg_out);

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

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

   Message Actions
           VkMsgPattern addAction(char* op, char* action,
                                  VkMsgActionType type,
                                  VkMsgClient* client);

           VkMsgPattern createAction(char* op, char* action,
                                     VkMsgActionType type,
                                     VkMsgClient* client);

           void removeAction(VkMsgPattern pat);

           VkMsgServicePair* findAction(VkMsgPattern pat);




X RESOURCES ASSOCIATED WITH THIS CLASS
     vkmsgTranslations        String to automatically register message
     patterns

CLASS DESCRIPTION
     VkMsgService is a subclass of VkMsgFacility that adds object-level
     dispatch rather than the process-level dispatch that the ToolTalk service
     provides.  It keeps track of which clients (VkMsgClient) send which
     messages, and routes the replies to the correct object.  It also manages
     the different message actions corresponding to each client.



FUNCTION DESCRIPTIONS
   VkMsgService()
           VkMsgService(Widget w,
                        const char* ptid = NULL,
                        const char* sessid = NULL);

           void ~VkMsgService(void);


          The VkMsgFacility constructor opens a ToolTalk connection and sets
          up its callback for received messages and replies.  The second
          argument can be used to provide a ToolTalk process type (ptype).
          The third argument specifies the ToolTalk session ID.  If "default,"
          connects to the default ToolTalk session ID.  If "nodefault,"
          creates a private ToolTalk session.

   registerPatterns()
           void registerPatterns(VkMsgClient* client, Widget w);


          Checks for a vkmsgTranslations resource value for the widget and if
          found, registers the specified message patterns.  The client must
          still register message actions.  This mechanism is not recommended.
   registerClient()
           void registerClient(VkMsgClient* client,
                               VkMsgFacilityCallback callback,
                               void* client_data);


          Adds a client.  The callback is called when this client receives a
          message.

   unregisterClient()
           void unregisterClient(VkMsgClient* client);


          Removes the client.  Patterns and actions must be removed by the
          client.

   sendRequest()
           VkMsgMessage sendRequest(VkMsgClient* client,
                                    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.  Returns the ToolTalk
          message object for the request.

           VkMsgMessage sendRequest(VkMsgClient* client, 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).

           VkMsgMessage sendRequest(VkMsgClient* client,
                                    VkMsgMessage msg_out);


          Send a pre-formatted request.

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


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

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

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

   addAction()
           VkMsgPattern addAction(char* op, char* action,
                                  VkMsgActionType type,
                                  VkMsgClient* client);


          Adds a message action.  The first argument is the message operator
          string.  The second argument is the name of the action (this will
          usually be the same as the message operator, but different if a
          translation is used).  The third argument specifies 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).

          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, char* action,
                                     VkMsgActionType type,
                                     VkMsgClient* client);


          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 unregistered.

   findAction()
           VkMsgServicePair* findAction(VkMsgPattern pat);


          Lookup the information associated with the message pattern.  This
          information contains the message operator string, the action name,
          the message reason for that action, the message pattern, and the
          message client.

   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.

INHERITED MEMBER FUNCTIONS
   Inherited from VkMsgFacility
          connect(), joinFile(), setCallback(), getPtype(), registerPattern(),
          createPattern(), registerPattern(), unregisterPattern(),
          destroyPattern(), sendNotice(), sendNotice(), sendStringNotice(),
          sendIntNotice(), sendFileNotice(), sendFileNotice(),
          sendStringFileNotice(), sendIntFileNotice(), sendRequest(),
          sendRequest(), sendSyncRequest(), sendSyncRequest(),
          sendFileRequest(), sendFileRequest(), sendSyncFileRequest(),
          sendSyncFileRequest(), sendRequest(), composeBegin(), composeAdd(),
          composeAdd(), composeAdd(), composeAdd(), composeList(),
          composeNum(), sessionID(), sessionProperty(), setDefaultSession(),
          computeSGISession(), startPrivateSession(), getCaseSession(),
          getCaseProperty(), getDefaultSession(), breakOutOfEventLoop(),
          findReplyWaitInfo(), newReplyWaitInfo(), popReplyWaitInfo(),
          getRootProperty(), receiveReply(), connectToXt(), receiveMessage(),
          callCallback(), makePathExplicit(), messageScope(), waitForReply(),
          waitTimeOut(), receive_message(), receive_reply(), callback,
          callbackData, msg, compose, composeSize, composeCount, sgi_session,
          _sessionProperty, ptype, sessionId, numReplyWait, sizeReplyWait,
          replyWaitInfo, firstConnect, selectionAtom


CLASSES USED BY THIS CLASS
     VkMsgClient, VkMsgFacility

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

SEE ALSO
     VkMsgFacility, VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgFacility,
     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