VkMsgFacility(3x)VkMsgFacility(3x)NAMEVkMsgFacility - 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);
Page 1
VkMsgFacility(3x)VkMsgFacility(3x)
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);
Page 2
VkMsgFacility(3x)VkMsgFacility(3x)
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 DESCRIPTIONVkMsgFacility 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 DESCRIPTIONSVkMsgFacility()
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,"
Page 3
VkMsgFacility(3x)VkMsgFacility(3x)
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.
Page 4
VkMsgFacility(3x)VkMsgFacility(3x)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 ...);
Page 5
VkMsgFacility(3x)VkMsgFacility(3x)
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.
Page 6
VkMsgFacility(3x)VkMsgFacility(3x)
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.
Page 7
VkMsgFacility(3x)VkMsgFacility(3x)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);
Page 8
VkMsgFacility(3x)VkMsgFacility(3x)
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
Page 9
VkMsgFacility(3x)VkMsgFacility(3x)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
Page 10
