Creating Messages (ToolTalk User's Guide)

ToolTalk User's Guide

Creating Messages

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

General-purpose function
- tt_message_create()
Process-oriented notice and request functions
- tt_pnotice_create()
- tt_prequest_create()
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. Table 8-4 and Table 8-5 list the ToolTalk functions that are used to create and complete message

Table 8-4 Functions Used to Create Messages


ToolTalk Function	Description
`tt_onotice_create(const char objid, const char op)`	Creates an object-oriented notice.
`tt_orequest_create(const char objid, const char op)`	Creates an object-oriented request.
`tt_pnotice_create(Tt_scope scope, const char *op)`	Creates a process-oriented notice.
`tt_prequest_create(Tt_scope scope, const char *op)`	Creates a process-oriented request.
`tt_message_create(void)`	Creates a message. This function is the ToolTalk general purpose function to create messages.

Note -

The return type for all the create functions is Tt_message.

Table 8-5 Functions Used to Complete Messages


ToolTalk Function	Description
`tt_message_address_set(Tt_message m, Tt_address p)`	Sets addressing mode (for example, point-to-point).
`tt_message_arg_add(Tt_message m, Tt_mode n, const char vtype, const char value)`	Adds a null-terminated string argument.
`tt_message_arg_bval_set(Tt_message m, int n, const unsigned char *value, int len)`	Sets an argument's value to the specified byte array.
`tt_message_arg_ival_set(Tt_message m, int n, int value)`	Sets an argument's value to the specified integer.
`tt_message_arg_val_set(Tt_message m, int n, const char *value)`	Sets an argument's value to the specified null-terminated string.
`tt_message_barg_add(Tt_message m, Tt_mode n, const char vtype, const unsigned char value, int len)`	Adds a byte array argument.
`tt_message_iarg_add(Tt_message m, Tt_mode n, const char *vtype, int value)`	Adds an integer argument.
`tt_message_context_bval(Tt_message m, const char slotname, unsigned char value, int len);`	Gets a context's value to the specified byte array.
`tt_message_context_ival(Tt_message m, const char slotname, int value);`	Gets a context's value to the specified integer.
`tt_message_context_val(Tt_message m, const char *slotname);`	Gets a context's value to the specified string.
`tt_message_icontext_set(Tt_message m, const char *slotname, int value);`	Sets a context to the specified integer.
`tt_message_bcontext_set(Tt_message m, const char slotname, unsigned char value, int length);`	Sets a context to the specified byte array.
`tt_message_context_set(Tt_message m, const char slotname, const char value);`	Sets a context to the specified null-terminated string.
`tt_message_class_set(Tt_message m, Tt_class c)`	Sets the type of message (either notice or request)
`tt_message_file_set(Tt_message m, const char *file)`	Sets the file to which the message is scoped.
`tt_message_handler_ptype_set(Tt_message m, const char *ptid)`	Sets the ptype that is to receive the message.
`tt_message_handler_set(Tt_message m, const char *procid)`	Sets the procid that is to receive the message.
`tt_message_object_set(Tt_message m, const char *objid)`	Sets the object that is to receive the message.
`tt_message_op_set(Tt_message m, const char *opname)`	Sets the operation that is to receive the message.
`tt_message_otype_set(Tt_message m, const char *otype)`	Sets the object type that is to receive the message.
`tt_message_scope_set(Tt_message m, Tt_scope s)`	Sets the recipients who are to receive the message (file, session, both).
`tt_message_sender_ptype_set(Tt_message m, const char *ptid)`	Sets the ptype of the application that is sending the message.
`tt_message_session_set(Tt_message m, const char *sessid)`	Sets the session to which the message is scoped.
`tt_message_status_set(Tt_message m, int status)`	Sets the status of the message; this status is seen by the receiving application.
`tt_message_status_string_set(Tt_message m, const char *status_str)`	Sets the text that describes the status of the message; this text is seen be the receiving application.
`tt_message_user_set(Tt_message m, int key, void *v)`	Sets a message that is internal to the sending application. This internal message is opaque data that is not seen by the receiving application.
`tt_message_abstainer(Tt_message m, int n)`	Returns the procid of the n'th abstainer of the specified message.
`tt_message_abstainers_count(Tt_message m)`	Returns a count of the procids that are recorded in the `TT_OFFER` m as having abstained from it.
`tt_message_accepter(Tt_message m,int n)`	Returns the procid of the n'th accepter of the specified message.
`tt_message_accepters_count(Tt_message m)`	Returns a count of the procids that are recorded in the `TT_OFFER` m as having accepted it.
`tt_message_rejecter(Tt_message m,int n)`	Returns the procid of the n'th rejector of the specified message.
`tt_message_rejecters_count(Tt_message m)`	Returns a count of the procids that are recorded in the `TT_OFFER` m as having rejected it.

Note -

The return type for all the functions used to complete messages is Tt_status

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

Note -

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.

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.

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:

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

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:

Objid

Fill in the unique object identifier.
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.