Receiving Messages

This chapter describes how to retrieve messages delivered to your application and how to handle the message once you have examined it. It also shows you how to send replies to requests that you receive.

To retrieve and handle ToolTalk messages, your application must perform several operations: it must be able to retrieve ToolTalk messages; it must be able to examine messages; it must provide callback routines; it must be able to respond to requests; and it must be able to destroy the message when it is no longer needed.

Retrieving Messages

When a message arrives for your process, the ToolTalk-supplied file descriptor becomes active. When notified of the active state of the file descriptor, your process must call tt_message_receive to get a handle for the incoming message.

Example 11-1 illustrates how to receive a message.

Example 11-1 Receiving a Message

/*
 * When a ToolTalk message is available, receive it; if it's a
 * ttsample1_value message, update the gauge with the new value.
 */
void
receive_tt_message()
{
	Tt_message msg_in;
	int mark;
	int val_in;

	msg_in = tt_message_receive();

	/*
	 * It's possible that the file descriptor would become active
	 * even though ToolTalk doesn't really have a message for us.
	 * The returned message handle is NULL in this case.
	 */

	if (msg_in == NULL) return;

Handles for messages remain constant. For example, when a process sends a message, both the message and any replies to the message have the same handle as the sent message. Example 11-2 is an example of how you can check the message state for TT_HANDLED.

Example 11-2 Code Checking the Message State

Tt_message m, n;
m = tt_message_create();
...
tt_message_send(m);

... wait around for tt_fd to become active

n = tt_message_receive();
if (m == n) {
	/* This is the reply to the message we sent */
	if (TT_HANDLED == tt_message_state(m) ) {
			/* The receiver has handled the message so we can go
on */
			...
	}
} else {
	/* This is a new message coming in */
)

Identifying and Processing Messages Easily

To easily identify and process messages received by you:

• Add a callback to a dynamic pattern with tt_pattern_callback_add. When you retrieve the message, the ToolTalk service will invoke any message or pattern callbacks. See Chapter 9, Dynamic Message Patterns for more information on placing callbacks on patterns.

• Retrieve the message's opnum if you are receiving messages that match your ptype message patterns.

Recognizing and Handling Replies Easily

To easily recognize and handle replies to messages sent by you:

• Place specific callbacks on requests before you send them with tt_message_callback_add. See Chapter 8, Sending Messages for more information on placing callbacks on messages.

• Compare the handle of the message you sent with the message you just received. The handles will be the same if the message is a reply.

• Add information meaningful to your application on the request with the tt_message_user_set call.

Checking Message Status

When you receive a message, you must check its status. If the status is TT_WRN_START_MESSAGE, you must either reply, reject, or fail the message even if the message is a notice, or issue a tt_message_accept call. Programs started using the ToolTalk service that receive a status of TT_WRN_START_MESSAGE should check tt_message_uid() and tt_message_gid(). You may want to fail the request with TT_DESKTOP_EACCES if the UNIX UID and/or GID do not agree with the request. Similarly, applications already running may want to reject requests with TT_DESKTOP_EACCES if there is UID or GID disagreement. This will cause serial rejection of the message until either a matching-ID handler is found, or an autostarted handler fails the request.

Examining Messages

When your process receives a message, you examine the message and take appropriate action.

Before you start to retrieve values, obtain a mark on the ToolTalk API stack so that you can release the information the ToolTalk service returns to you all at once. Example 11-3 allocates storage, examines message contents, and releases the storage.

Example 11-3 Allocating, Examining, and Releasing Storage

        /*
         * Get a storage mark so we can easily free all the data
         * ToolTalk returns to us.
         */

        mark = tt_mark();

        if (0==strcmp("ttsample1_value", tt_message_op(msg_in))) {
                tt_message_arg_ival(msg_in, 0, &val_in);
                xv_set(gauge, PANEL_VALUE, val_in, NULL);
        }

        tt_message_destroy(msg_in);
        tt_release(mark);
        return;

Table 11-1 lists the ToolTalk functions you use to examine the attributes of a message you have received.

Table 11-1 Functions to Examine Message Attributes