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.

Offers can only be sent with address TT_PROCEDURE. Attempting to send an Offer with any other address will generate an error of TT_ERR_ADDRESS.

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

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.