When you send an informational message, the notice takes a one-way trip, as shown in Figure 5-1.

Figure 5-1. Notice Routing

The sending process creates a message, fills in attribute values, and sends it. The ToolTalk service matches message and pattern attribute values, then gives a copy of the message to one handler and to all matching observers. File–scoped messages are automatically transferred across session boundaries to processes that have declared interest in the file.

When you send a message that is a request, the request takes a round-trip from sender to handler and back; copies of the message take a one-way side trip to observers. Figure 5-2 illustrates the request routing procedure.

Figure 5-2. Request Routing

The ToolTalk service delivers a request to only one handler. The handler adds results to the message and sends it back. Other processes can observe a request before or after it is handled, or both; observers absorb a request without sending it back.

Messages addressed to other applications can be addressed to a particular process or any process that has registered a pattern that matches your message. When you address a message to a process, you need to know the process identifier (procid) of the other application. However, processes do not usually know each other's procid; more often, a sender does not care which process performs an operation (request message) or learns of an event (notice message).

Applications that use the ToolTalk service to communicate usually have something in common – the applications are running in the same session or they are interested in the same file or data. To register this interest, applications join sessions or files (or both) with the ToolTalk service. This file and session information is used by the ToolTalk service with the message patterns to determine which applications should receive a message.

For many process-oriented messages, the sending application knows the ptype or the procid of the process that should handle the message. For other messages, the ToolTalk service can determine the handler from the operation and arguments of the message.

(HandlerPtype: TextEditor;
Op:  ShowLine;
Scope: TT_SESSION;
Session: my_session_id;
File: /home/gondor/joe/src/ebe.c)

Many messages handled by the ToolTalk service are directed at objects but are actually delivered to the process that manages the object.The message signatures in an otype, which include the ptype of the process that can handle each specific message, help the ToolTalk service determine process to which it should deliver an object-oriented message.

Sometimes you may need to send an object-oriented message without knowing the objid. To handle these cases, the ToolTalk service provides otype addressing. This addressing mode requires the sender to specify the operation, arguments, scope, and otype. The ToolTalk service looks in the specified otype definition for a message pattern that matches the message's operation and arguments to locate handling and observing processes. The dispatch and delivery then proceed as in messages to specific objects.

The ToolTalk service provides three methods to create and complete messages:

The process- and object-oriented notice and request functions make message creation simpler for the common cases. They are functionally identical to strings of other tt_message_create() and tt_message_<attribute>_set() calls, but are easier to write and read. Table 5-2 is a list of theToolTalk functions that are used to create and complete messages.

You can use the general-purpose function tt_message_create()to create and complete ToolTalk messages. If you create a process- or object–oriented message with tt_message_create(), use the tt_message_<attribute>_set() calls to set the attributes.

Args

Fill in any arguments specific to the operation. Use the function that best suits your argument's data type:

tt_message_arg_add()		Adds an argument whose value is a zero-terminated character string.
tt_message_barg_add()		Adds an argument whose value is a byte string.
tt_message_iarg_add()		Adds an argument whose value is an integer. For each argument you add (regardless of the value type), specify:
Tt_mode		Specify TT_IN, TT_OUT, or TT_INOUT. TT_IN indicates that the argument is written by the sender and can be read by the handler and any observers. TT_INOUT indicates that the argument is written by the sender and the handler and can be read by all. If you are sending a request that requires the handler to provide an argument in return, use TT_INOUT. TT_OUT indicates that the argument is written by the handler and read by the sender.
vtype		The value type (vtype) describes the type of argument data that is to be added. The ToolTalk service uses the vtype name when it compares a message to registered patterns to determine a message's recipients. The ToolTalk service does not use the vtype to process a message or pattern argument value. The vtype name helps the message receiver interpret data. For example, if a word processor rendered a paragraph into a PostScript representation in memory, it could call tt_message_arg_add() with the following arguments: tt_message_arg_add (m, “PostScript”, buf); In this case, the ToolTalk service would assume buf pointed to a zero–terminated string and send it. Similarly, an application could send an enum value in a ToolTalk message; for example, an element of Tt_status: tt_message_iarg_add(m, “Tt_status”, (int) TT_OK); The ToolTalk service sends the value as an integer but the “Tt_status” vtype tells the recipient what the value means.

---

Note: It is very important that senders and receivers define particular vtype names so that a receiver does not attempt to retrieve a value that was stored in another fashion; for example, a value stored as an integer but retrieved as a string.

---

You can easily create process–oriented notices and requests. To get a handle or opaque pointer to a new message object for a procedural notice or request, use the tt_pnotice_create() or tt_prequest_create() function. You can then use this handle on succeeding calls to reference the message.

When you create a message with tt_pnotice_create() or tt_prequest_create(), you must supply the following two attributes as arguments:

You use the tt_message_<attribute>_set calls to complete other message attributes such as operation arguments.

You can easily create object–oriented notices and requests. To get a handle or opaque pointer to a new message object for a object-oriented notice or request, use the tt_onotice_create() or tt_orequest_create() function. You can then use this handle on succeeding calls to reference the message.

When you create a message with tt_onotice_create() or tt_orequest_create(), you must supply the following two attributes as arguments:

You use the tt_message_<attribute>_set calls to complete other message attributes such as operation arguments.

When a request contains a message callback routine, the callback routine is automatically called when the reply is received to examine the results of the reply and take appropriate actions.

You use tt_message_callback_add() to add the callback routine to your request. When the reply comes back and the message has been processed through the callback routine, the message must be destroyed before the callback function returns TT_CALLBACK_PROCESSED. To destroy the message, use tt_message_destroy(), as illustrated in the following sample code.

Tt_callback action
sample_msg_callback(Tt_message m, Tt_pattern p)
{
   ... process the msg ...

   tt_message_destroy(m);
   return TT_CALLBACK_PROCESSED;
}

The following code sample is a callback routine, cntl_msg_callback, that examines the state field of the reply and takes action if the state is started, handled, or failed.

/*
 * Default callback for all the ToolTalk messages we send.
 */

Tt_callback_action
cntl_msg_callback(m, p)
     Tt_message m;
     Tt_pattern p;
{
 int    mark;
 char   msg[255];
 char   *errstr;


mark = tt_mark();
switch (tt_message_state(m)) {
      case TT_STARTED:
         xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER,
            "Starting editor...", NULL);
      break;
   case TT_HANDLED:
      xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER, "",NULL);
      break;
   case TT_FAILED:
      errstr = tt_message_status_string(m);
      if (tt_pointer_error(errstr) == TT_OK && errstr) {
   sprintf(msg,"%s failed: %s", tt_message_op(m), errstr);
    } else if (tt_message_status(m) == TT_ERR_NO_MATCH) 
{
   sprintf(msg,"%s failed: Couldn't contact editor",
     tt_message_op(m),
     tt_status_message(tt_message_status(m)));
     } else {
   sprintf(msg,"%s failed: %s",
     tt_message_op(m),
     tt_status_message(tt_message_status(m)));
    }
    xv_set(cntl_ui_base_window, 
FRAME_LEFT_FOOTER,msg,NULL);
           break;
        default:
           break;
}
/*
 * no further action required for this message. Destroy it
 * and return TT_CALLBACK_PROCESSED so no other callbacks 
 * will be run for the message.
 */
tt_message_destroy(m);
tt_release(mark);
return TT_CALLBACK_PROCESSED;
}

When you have completed your message, use tt_message_send() to send it.

If the ToolTalk service returns TT_WRN_STALE_OBJID, it has found a forwarding pointer in the ToolTalk database that indicates the object mentioned in the message has been moved. However, the ToolTalk service will send the message with the new objid. You can then use tt_message_object() to retrieve the new objid from the message and put it into your internal data structure.

If you will not need the message in the future (for example, if the message was a notice), you can use tt_message_destroy() to delete the message and free storage space.

---

Note: If you are expecting a reply to the message that you will want to compare against your request, do not destroy the message until you have handled the reply.

---