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:

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

2. 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:

1. Objid

   Fill in the unique object identifier.

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

Adding Message Callbacks

When a request contains a message callback routine, the callback routine is automatically called when the reply is received to examine the results of the reply and take appropriate actions.

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

You use tt_message_callback_add to add the callback routine to your request. When the reply comes back and the reply message has been processed through the callback routine, the reply message must be destroyed before the callback function returns TT_CALLBACK_PROCESSED. To destroy the reply message, use tt_message_destroy, as illustrated in Example 8-4.

Example 8-4 Destroying a Message

Tt_callback_action
sample_msg_callback(Tt_message m, Tt_pattern p)
{
	... process the reply msg ...

	tt_message_destroy(m);
	return TT_CALLBACK_PROCESSED;
}

The following code sample is a callback routine, cntl_msg_callback, that examines the state field of the reply and takes action if the state is started, handled, or failed.

/*
 * Default callback for all the ToolTalk messages we send.
 */

Tt_callback_action
cntl_msg_callback(m, p)
     Tt_message m;
     Tt_pattern p;
{
	int		mark;
	char		msg[255];
	char		*errstr;


	mark = tt_mark();
	switch (tt_message_state(m)) {
	      case TT_STARTED:
		    xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER,
		       "Starting editor...", NULL);
		    break;
	      case TT_HANDLED:
		    xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER, "", NULL);
		    break;
	      case TT_FAILED:
		    errstr = tt_message_status_string(m);
		    if (tt_pointer_error(errstr) == TT_OK && errstr) {
			sprintf(msg,"%s failed: %s", tt_message_op(m), errstr);
		    } else if (tt_message_status(m) == TT_ERR_NO_MATCH) {
			sprintf(msg,"%s failed: Couldn't contact editor",
				tt_message_op(m),
				tt_status_message(tt_message_status(m)));
		    } else {
			sprintf(msg,"%s failed: %s",
				tt_message_op(m),
				tt_status_message(tt_message_status(m)));
		    }
		    xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER, msg, NULL);
		    break;
	      default:
		    break;
	}
	/*
	 * no further action required for this message. Destroy it
	 * and return TT_CALLBACK_PROCESSED so no other callbacks will
	 * be run for the message.
	 */
	tt_message_destroy(m);
	tt_release(mark);
	return TT_CALLBACK_PROCESSED;
}