ToolTalk User's Guide
Contents of Chapter:
- 11.1 Retrieving Messages
-
- Identifying and Processing Messages Easily
-
- Recognizing and Handling Replies Easily
-
- 11.2 Checking Message Status
-
- 11.3 Examining Messages
-
- 11.4 Callback Routines
-
- Callbacks for Messages Addressed to Handlers
-
- Attaching Callbacks to Static Patterns
-
- 11.5 Handling Requests
-
- Replying to Requests
-
- Rejecting or Failing a Request
-
- 11.6 Destroying 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.
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.
Figure 11-1 illustrates how to receive a message.
Figure 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. Figure 11-2 is an example of how you can check the message state for TT_HANDLED.
Figure 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.
11.2 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.
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. Figure 11-3 allocates storage, examines message contents, and releases the storage.
Figure 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
11.4 Callback Routines
You can tell the ToolTalk service to invoke a callback when a message arrives because a pattern has been matched.
p = tt_pattern_create();
tt_pattern_op_add(p, "EDIT");
... other pattern attributes
tt_pattern_callback_add(p, do_edit_message);
tt_pattern_register(p);
Note: Callbacks are called in reverse order of registration (for example, the most recently added callback is called first).
Figure 11-4 illustrates how the ToolTalk service invokes message and pattern callbacks when tt_message_receive is called to retrieve a new message.
Figure 11-4 How Callbacks Are Invoked
Callbacks for Messages Addressed to Handlers
After the ToolTalk service determines the receiver for a message addressed to a handler, it matches the message against any patterns registered by the receiver. (Messages explicitly addressed to handlers are point-to-point messages and do not use pattern matching.)
- If the message does not match a pattern, the message is delivered in the normal manner.
- If the message is matched to a pattern, any callbacks attached to the pattern are run.
Attaching Callbacks to Static Patterns
Numeric tags (opnums) can be attached to each signature in a ptype when a static pattern is created. A callback can now be attached to the opnum. When a message is delivered because it matched a static pattern with an opnum, the ToolTalk service checks for any callbacks attached to the opnum and, if any exists, runs them.
11.5 Handling Requests
When your process receives a request (class = TT_REQUEST), you must either reply to the request, or reject or fail the request.
When you reply to a request, you need to:
- Perform the requested operation.
- Fill in any argument values with modes of TT_OUT or TT_INOUT.
- Send the reply to the message.
Table 11-2 lists the ToolTalk functions you use to reply to requests.
Table 11-2 Functions to Reply to Requests
Rejecting or Failing a Request
If you have examined the request and your application is not currently able to handle the request, you can use the ToolTalk functions listed in Table 11-3 to reject or fail a request.
Table 11-3 Rejecting or Failing Requests
Rejecting a Request
If you have examined the request and your application is not currently able to perform the operation but another application might be able to do so, use tt_message_reject to reject the request.
When you reject a request, the ToolTalk service attempts to find another receiver to handle it. If the ToolTalk service cannot find a handler that is currently running, it examines the disposition attribute, and either queues the message or attempts to start applications with ptypes that contain the appropriate message pattern.
Failing a Request
If you have examined the request and the requested operation cannot be performed by you or any other process with the same ptype as yours, use tt_message_fail to inform the ToolTalk service that the operation cannot be performed. The ToolTalk service will inform the sender that the request failed.
To inform the sender of the reason the request failed, use tt_message_status_set or tt_message_status_string_set before you call tt_message_fail.
Note: The status code you specify with tt_message_status_set must be greater than TT_ERR_LAST.
After you have processed a message and no longer need the information in the message, use tt_message_destroy to delete the message and free storage space.
Generated with CERN WebMaker