EZwgl (9 Messages)

# 9 Messages

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

    typedef  void (*EZ_MessageHandler)(EZ_Message *msgIn, void *client_data);

To handle message, an application must register at least one message handler. Message handlers are registered by one of the following two commands.

    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.

HTML Documentation Maintainance:`Arturo Espinosa <arturo@nuclecu.unam.mx>`