Modifying Applications to Send ToolTalk Messages

To send ToolTalk messages, your application must perform several operations: it must be able to create and complete ToolTalk messages; it must be able to add message callback routines; and it must be able to send the completed message.

Creating Messages

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

1. General-purpose function

   • tt_message_create()

2. Process-oriented notice and request functions

   • tt_pnotice_create()

   • tt_prequest_create()

3. Object-oriented notice and request functions

   • tt_onotice_create()

   • tt_orequest_create()

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. and list the ToolTalk functions that are used to create and complete message

Table 8-4 Functions Used to Create Messages

Table 8-5 Functions Used to Complete Messages

Using the General-Purpose Function to Create ToolTalk 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.

Class

• Use TT_REQUEST for messages that return values or status. You will be informed when the message is handled or queued, or when a process is started to handle the request.

• Use TT_NOTICEfor messages that only notify other processes of events.

• Use TT_OFFER for messages for which there are multiple intended recipients, and for which you wish to determine how many of those recipients have accepted, rejected, or abstained from participation in this message.

Address

• Use TT_PROCEDUREto send the message to any process that can perform this operation with these arguments. Fill in op and args attributes of this message.

• Use TT_OTYPE to send the message to this type of object that can perform this operation with these arguments. Fill in otype, op, and args attributes of the message.

• Use TT_HANDLER to send the message to a specific process. Specify the handler attribute value.

  Usually, one process makes a general request, picks the handler attribute from the reply, and directs further messages to that handler. If you specify the exact procid of the handler, the ToolTalk service will deliver the message directly — no pattern matching is done and no other applications can observe the message. This point-to-point (PTP) message passing feature enables two processes to rendezvous through broadcast message passing and then communicate explicitly with one another.

• Use TT_OBJECT to send the message to a specific object that performs this operation with these arguments. Fill in object, op, and args attributes of this message.

Scope

Fill in the scope of the message delivery. Potential recipients could be joined to:

• TT_SESSION

• TT_FILE

• TT_BOTH

• TT_FILE_IN_SESSION

Depending on the scope, the ToolTalk service will add the default session or file, or both to the message.

Note that Offers can only be sent in TT_SESSION scope.

Op

Fill in the operation that describes the notification or request that you are making. To determine the operation name, consult the ptype definition for the target recipient or the message protocol definition.

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 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.

• Value Type

  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.

Creating Process-Oriented Messages

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:

1. Scope

   Fill in the scope of the message delivery. Potential recipients could be joined to:

   • TT_SESSION

   • TT_FILE

   • TT_BOTH

   • TT_FILE_IN_SESSION

   Depending on the scope, the ToolTalk service fills in the default session or file (or both).

2. Op

   Fill in the operation that describes the notice or request you are making. To determine the operation name, consult the ptype definition for the target process or other protocol definition.

You use the tt_message_attribute_set calls to complete other message attributes such as operation arguments.

Creating and Completing Object-Oriented Messages

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:

1. Objid

   Fill in the unique object identifier.

2. Op

   Fill in the operation that describes the notice or request you are making. To determine the operation name, consult the ptype definition for the target process or other protocol definition.

You use the tt_message_attribute_set calls to complete other message attributes such as operation arguments.

Adding Message Callbacks

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 reply message has been processed through the callback routine, the reply message must be destroyed before the callback function returns TT_CALLBACK_PROCESSED. To destroy the reply message, use tt_message_destroy, as illustrated in .

Example 8-4 Destroying a Message

Tt_callback_action
sample_msg_callback(Tt_message m, Tt_pattern p)
{
    ... process the reply 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;
}

You can also add callbacks to static patterns by attaching a callback to the opnum of a signature in a ptype. 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 runs them.

• Use tt_otype_opnum_callback_add to attach the callback routine to the opnum of an osignature.

• Use tt_ptype_opnum_callback_add to attach the callback routine to the opnum of a psignature.

Sending a Message

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.