VkMsgFacility(3x)
VkMsgFacility - ViewKit simple interface to the ToolTalk message service
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
NAME VkMsgFacility - ViewKit simple interface to the ToolTalk message service HEADER FILE #include <Vk/VkMsgFacility.h> PUBLIC PROTOCOL SUMMARY Constructor/Destructor VkMsgFacility(Widget w, const char* ptid = NULL, const char* sessid = NULL); void ~VkMsgFacility(void); ToolTalk Service void connect(char* sessid = NULL); VkMsgStatus joinFile(char* filepath); Access Functions void setCallback(VkMsgFacilityCallback callback, void* client_data); char* getPtype(void); Message Patterns VkMsgPattern registerPattern(char* op, VkMsgCategory category = VK_MSG_OBSERVE); VkMsgPattern createPattern(char* op, VkMsgCategory category = VK_MSG_OBSERVE); VkMsgStatus registerPattern(VkMsgPattern pat); VkMsgStatus unregisterPattern(VkMsgPattern pat); VkMsgStatus destroyPattern(VkMsgPattern pat); 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); VkMsgMessage sendRequest(VkMsgMessage msg_out); 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); ToolTalk Session Information char* sessionID(void); Atom sessionProperty(void); void setDefaultSession(const char* sessid); char* computeSGISession(void); X RESOURCES ASSOCIATED WITH THIS CLASS defaultSyncTimeout Default limit for synchronous requests (60 sec) CLASS DESCRIPTION VkMsgFacility provides a simple C++ interface to the ToolTalk message service. It keeps track of ToolTalk details like sessions and process types, provides convenience routines for sending notices and requests, and provides a callback for dealing with received notices and replies. VkMsgFacility provides access to only a subset of ToolTalk functionality. It provides a more simplistic interface and assumes a message policy (session-scoped messages, patterns based only on message operator) that works for most applications. DERIVING SUBCLASSES It is not expected that the developer would subclass VkMsgFacility. Instead, subclass VkMsgService. VkMsgService is a subclass of VkMsgFacility that allows multiple, independent clients in the same process to send and receive messages. FUNCTION DESCRIPTIONS VkMsgFacility() VkMsgFacility(Widget w, const char* ptid = NULL, const char* sessid = NULL); void ~VkMsgFacility(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. connect() void connect(char* sessid = NULL); Join the ToolTalk session and enable sending and receiving messages. joinFile() VkMsgStatus joinFile(char* filepath); Informs the ToolTalk service that your process is interested in messages involving the file pathname. These messages must be sent using the scope VK_MSG_FILE_IN_SESSION. Use of file-scoped messages is not recommended, and VK_MSG_SESSION scoping is preferred. Refer to the ToolTalk Programmer's Guide for more details on file-scoped messages. setCallback() void setCallback(VkMsgFacilityCallback callback, void* client_data); The callback is called whenever a ToolTalk message (notice or request) is received. The reason argument is VK_MSG_FACILITY_NOTICE (notice), VK_MSG_FACILITY_REQUEST (request), VK_MSG_FACILITY_REQUEST_SPECIFIC (request matching an exact pattern), VK_MSG_FACILITY_REPLY (reply to a previous request), VK_MSG_FACILITY_FAILED (this request was not handled), or VK_MSG_FACILITY_STARTED (this request caused autostart of the handler). The msg_in argument is the ToolTalk message object. The op argument is the message operator, and the argc and argv arguments are the message arguments. getPtype() char* getPtype(void); Returns the process type (ptype) string provided in the VkMsgFacility constructor. createPattern() VkMsgPattern createPattern(char* op, VkMsgCategory category = VK_MSG_OBSERVE); Creates a message pattern 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. registerPattern() VkMsgPattern 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. VkMsgStatus registerPattern(VkMsgPattern pat); Register a pattern created by the createPattern method and express interest 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. 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 transfer 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-value 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 of the message 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. Returns the ToolTalk message object for the request. 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. VkMsgMessage sendRequest(VkMsgMessage msg_out); Send a pre-formatted request. 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. Remember to call this routine before starting a new argument 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. sessionID() char* sessionID(void); Returns the current ToolTalk session ID. sessionProperty() Atom sessionProperty(void); Returns the X property used to store the session ID on ViewKit windows (VkMsgWindow and subclasses). setDefaultSession() void setDefaultSession(const char* sessid); Changes the current ToolTalk session ID. Only valid before VkMsgFacility::connect is called. computeSGISession() char* computeSGISession(void); Returns the environment variable used to set the SGI ToolTalk session ID. This variable name depends on whether or not a ClearCase view is in effect (i.e. $CLEARCASE_ROOT is set). KNOWN DERIVED CLASSES VkMsgService CLASSES USED BY THIS CLASS VkApp KNOWN CLASSES THAT USE THIS CLASS VkMsgClient, VkMsgService SEE ALSO VkApp, VkMsgClient, VkMsgService 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