EZwgl includes a mechanism for clients to exchange messages. An EZwgl client can send a message to one or to all EZwgl clients. A message is a piece of text together with some control information encoded in the following data structure. The various fields are filled by the parties when messages are sent or received.
typedef struct {
Atom messageType; /* message type identifier */
int messageLength;/* the length of the message */
char *message; /* the message: textual string */
int messageId; /* set by sender, message Id */
int replyId; /* set by sender, reply id */
int isReply; /* True if the message is a reply */
/* src info */
Window sender; /* sender's communication window id */
Atom senderClass; /* sender's class name: XrmQuark */
Atom senderInstance; /* sender's instance name XrmQuark */
int senderIsSelf; /* True if msg is originated from the client itself */
} EZ_Message;
Messages are handled by message handlers. A message handler is a procedure of the following type
To handle message, an application must register at least one message handler. Message handlers are registered by one of the following two commands.typedef void (*EZ_MessageHandler)(EZ_Message *msgIn, void *client_data);
void EZ_RegisterMessageHandler(Atom mtype, int mId, void *data,
EZ_MessageHandler handler, int timeout,
EZ_CallBack *timeoutCb, void *cdata);
void EZ_SetDefaultMessageHandler(EZ_MessageHandler handler, void *data);
The first procedure registers a specific message handler.
This handler will only handle
messages of the specified type mtype
and the specified message Id
mId
, and it will expire in timeout
seconds
if timeout>0
. When it expires, it executes timeroutCb(data, cdata)
if supplied. The second function registers the default message handler. The default
message handler handles all messages which are not handled by specific handlers.
To delete a message handler, use
void EZ_DeleteMessageHandler(Atom mtype, int mId, void *data,
EZ_MessageHandler handler);
To send a message to a spcific client, use
void EZ_SendMessage(Atom mtype, char *message, int length, int msgId,
Window recipient, int replayId, int isReply);
This function requires the id of the recipient's communication window,
which is known only after some dialogue has been initiated.
Normally, one broadcasts a message first to find an interested party.
When the party replies, the id of its communication window is
set in the sender
field of the message.
The meaning of the arguments are:
mtype
specifies the message type.
message
specifies the message.
length
specifies the length of the message.
msgId
specifies the transaction serial number.
recipient
specifies the recipient.
replyId
if the sender requires a reply, it specifies
the message id for the reply. If the recipient of this
message decides to reply, it should use this message id..
isReply
specifies whether this message is a reply.
To broadcast a message to all EZwgl clients, use
void EZ_BroadcastMessage(Atom mtype, char *message, int length,
int msgId, int replyId);
To reply a message, use
void EZ_ReplyMessage (EZ_Message *fromsg, char *reply, int replylength);
void EZ_ReplyMessageR (EZ_Message *fromsg, char *reply, int len, int replyId);
The second function replies a message and requests a further correspondence
from the recipient of the message.