Callback Routines

You can tell the ToolTalk service to invoke a callback when a message arrives because a pattern has been matched.

p = tt_pattern_create();
   tt_pattern_op_add(p, "EDIT");
   ... other pattern attributes
   tt_pattern_callback_add(p, do_edit_message);
   tt_pattern_register(p);

Note - Callbacks are called in reverse order of registration (for example, the most recently added callback is called first).

Figure 11-1 illustrates how the ToolTalk service invokes message and pattern callbacks when tt_message_receive is called to retrieve a new message.

Figure 11-1 How Callbacks Are Invoked

Callbacks for Messages Addressed to Handlers

After the ToolTalk service determines the receiver for a message addressed to a handler, it matches the message against any patterns registered by the receiver. (Messages explicitly addressed to handlers are point-to-point messages and do not use pattern matching.)

• If the message does not match a pattern, the message is delivered in the normal manner.

• If the message is matched to a pattern, any callbacks attached to the pattern are run.

Attaching Callbacks to Static Patterns

Numeric tags (opnums) can be attached to each signature in a ptype when a static pattern is created. A callback can now be attached to the opnum. 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, if any exists, runs them.

Handling Requests

When your process receives a request (class = TT_REQUEST), you must either reply to the request, or reject or fail the request.

Replying to Requests

When you reply to a request, you need to:

1. Perform the requested operation.

2. Fill in any argument values with modes of TT_OUT or TT_INOUT.

3. Send the reply to the message.

   Table 11-2 lists the ToolTalk functions you use to reply to requests.

   Table 11-2 Functions to Reply to Requests

   ToolTalk Function	Description
   tt_message_arg_mode(Tt_message m, int n)	The argument mode (in, out, inout). Return type is Tt_mode.
   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. Return type is Tt_status.
   tt_message_arg_ival_set(Tt_message m, int n, int value)	Sets an argument's value to the specified integer. Return type is Tt_status.
   tt_message_arg_val_set(Tt_message m, int n, const char *value)	Sets an argument's value to the specified string. Return type is Tt_status.
   tt_message_arg_xval_set(Tt_message m, int n, xdrproc_t xdr_proc, void *value)	Return type is Tt_status.
   tt_message_context_set(Tt_message m, const char *slotname, const char *value);	Sets a context to the specified string. Return type is Tt_status.
   tt_message_bcontext_set(Tt_message m, const char *slotname, unsigned char *value, int length);	Sets a context to the specified byte array. Return type is Tt_status.
   tt_message_icontext_set(Tt_message m, const char *slotname, int value);	Sets a context to the specified integer. Return type is Tt_status.
   tt_message_xcontext_set(Tt_message m, const char *slotname, xdrproc_t xdr_proc, void *value)	Return type is Tt_status.
   tt_message_reply(Tt_message m)	Replies to message. Return type is Tt_status.

Rejecting or Failing a Request

If you have examined the request and your application is not currently able to handle the request, you can use the ToolTalk functions listed in Table 11-3 to reject or fail a request.

Table 11-3 Rejecting or Failing Requests

The return type for these requests is Tt_status.

Rejecting a Request

If you have examined the request and your application is not currently able to perform the operation but another application might be able to do so, use tt_message_reject to reject the request.

When you reject a request, the ToolTalk service attempts to find another receiver to handle it. If the ToolTalk service cannot find a handler that is currently running, it examines the disposition attribute, and either queues the message or attempts to start applications with ptypes that contain the appropriate message pattern.

Failing a Request

If you have examined the request and the requested operation cannot be performed by you or any other process with the same ptype as yours, use tt_message_fail to inform the ToolTalk service that the operation cannot be performed. The ToolTalk service will inform the sender that the request failed.

To inform the sender of the reason the request failed, use tt_message_status_set or tt_message_status_string_set before you call tt_message_fail.

Note - The status code you specify with tt_message_status_set must be greater than TT_ERR_LAST.

Observing Offers

When your process receives an offer (class = TT_OFFER) in state TT_SENT, it must eventually do one of five things:

1. Accept the offer by calling tt_message_accept() on the message. This will tell the sending procid that the receiving procid has accepted the offer.

2. Reject the offer by calling tt_message_reject() on the message. This will tell the sending procid that the receiving procid has rejected the offer.

3. Abstain from the offer by calling tt_message_destroy() on the message without accepting or rejecting it first. This will tell the sending procid that the receiving procid has abstained from the offer.

4. Abstain from the offer by calling tt_message_receive() again without accepting or rejecting the offer first. This also will tell the sending procid that the receiving procid has abstained from the offer.

5. Disconnect from the ToolTalk service by calling tt_close(), or by exiting (normally or abnormally). In this case the ttsession process to which the client process is connected will mark the client process as abstaining from the offer.

When the handler (if any) and all the observers have accepted, rejected, or abstained from the message, the message state (Tt_state) will be set to TT_RETURNED. Intermediate states on an offer that will not be seen on other message classes are defined as:

1. TT_ACCEPTED--an Offer will enter this state whenever a receiver does a tt_message_accept() on it.

2. TT_REJECTED--an Offer will enter this state whenever a receiver does a tt_message_reject() on it.

3. TT_ABSTAINED--an Offer will enter this state whenever a receiver does choice 3, 4, or 5 above on it.