VkMsgClient(3x)VkMsgClient(3x)NAMEVkMsgClient - 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);
Page 1
VkMsgClient(3x)VkMsgClient(3x)
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);
Page 2
VkMsgClient(3x)VkMsgClient(3x)
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 DESCRIPTIONVkMsgClient 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 DESCRIPTIONSVkMsgClient()
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);
Page 3
VkMsgClient(3x)VkMsgClient(3x)
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()
Page 4
VkMsgClient(3x)VkMsgClient(3x)
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 ...);
Page 5
VkMsgClient(3x)VkMsgClient(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 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.
Page 6
VkMsgClient(3x)VkMsgClient(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.
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.
Page 7
VkMsgClient(3x)VkMsgClient(3x)
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()
Page 8
VkMsgClient(3x)VkMsgClient(3x)
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
Page 9
