Example

In this example, a hypothetical spreadsheet application named FinnogaCalc is integrated with the ToolTalk service.

FinnogaCalc starts and registers with the ToolTalk service by declaring its ptype, FinnogaCalc, and joining its default session.
FinnogaCalc loads a worksheet, hatsize.wks, and tells the ToolTalk service it is observing the worksheet by joining the worksheet file.
A second instance of FinnogaCalc (called FinnogaCalc₂) starts, loads a worksheet, wardrobe.wks, and registers with the ToolTalk service in the same way.
The user assigns the value of cell B2 in hatsize.wks to also appear in cell C14 of wardrobe.wks.
So that FinnogaCalc can send the value to FinnogaCalc₂, FinnogaCalc₂ creates an object spec for cell C14 by calling a ToolTalk function. This object is identified by an objid.
FinnogaCalc₂ then gives this objid to FinnogaCalc (for example, through the clipboard).
FinnogaCalc remembers that its cell B2 should appear in the object identified by this objid and sends a message that contains the value.
ToolTalk routes the message. To deliver the message, the ToolTalk service:
1. Examines the spec associated with the objid and finds that the type of the objid is FinnogaCalc_cell and that the corresponding object is in the file wardrobe.wks.
2. Consults the otype definition for FinnogaCalc_cell. From the otype, the ToolTalk service determines that this message is observed by processes of ptype FinnogaCalc and that the scope of the message should be TT_FILE.
3. Matches the message against registered patterns and locates all processes of this ptype that are observing the proper file. FinnogaCalc₂ matches, but FinnogaCalc does not.
4. Delivers the message to FinnogaCalc₂.
FinnogaCalc₂ recognizes that the message contains an object that corresponds to cell C14. FinnogaCalc₂ updates the value in wardrobe.wks and displays the new value.

Otype Addressing

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.

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:

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


8. Sending Messages ToolTalk Message Delivery Algorithm Object-Oriented Message Delivery