ToolTalk User's Guide

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:

Perform the requested operation.

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

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


ToolTalk Function	Description
`tt_message_reject(Tt_message m)`	Rejects message
`tt_message_fail(Tt_message m)`	Fails message
`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.

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.