ToolTalk User's Guide

Defining Dynamic Messages

To create and register a dynamic message pattern, you allocate a new pattern object, fill in the proper information, and register it. When you are done with the pattern (that is, when you are no longer interested in messages that match it), either unregister or destroy the pattern. You can register and unregister dynamic message patterns as needed.

The ToolTalk functions used to create, register, and unregister dynamic message patterns are listed in Table 9–1.

Table 9–1 Functions for Creating, Updating, and Deleting Message Patterns


ToolTalk Function	Description
`tt_pattern_create(void)`	Create Pattern
`tt_pattern_arg_add(Tt_pattern p, Tt_mode n, const char vtype, const char value)`	Add string arguments
`tt_pattern_barg_add(Tt_pattern m, Tt_mode n, const char vtype, const unsigned char value, int len)`	Add byte array arguments
`tt_pattern_iarg_add(Tt_pattern m, Tt_mode n, const char *vtype, int value)`	Add integer arguments
`tt_pattern_xarg_add(Tt_pattern m, Tt_mode n, const char vtype, xdrproc_t xdr_proc, void value)`	Adds an xdr argument to a byte array
`tt_pattern_bcontext_add(Tt_pattern p, const char slotname, const unsigned char value, int length);`	Add byte array contexts
`tt_pattern_context_add(Tt_pattern p, const char slotname, const char value);`	Add string contexts
`tt_pattern_icontext_add(Tt_pattern p, const char *slotname, int value);`	Add integer contexts
`tt_pattern_address_add(Tt_pattern p, Tt_address d)`	Add address
`tt_pattern_callback_add(Tt_pattern p, Tt__message_callback_action f)`	Add message callback
`tt_pattern_category_set(Tt_pattern p, Tt_category c)`	Set category
`tt_pattern_class_add(Tt_pattern p, Tt_class c)`	Add class
`tt_pattern_disposition_add(Tt_pattern p, Tt_disposition r)`	Add disposition
`tt_pattern_file_add(Tt_pattern p, const char *file)`	Add file
`tt_pattern_object_add(Tt_pattern p, const char *objid)`	Add object
`tt_pattern_op_add(Tt_pattern p, const char *opname)`	Add operation
`tt_pattern_opnum_add(Tt_pattern p, int opnum)`	Add operation number
`tt_pattern_otype_add(Tt_pattern p, const char *otype)`	Add object type
`tt_pattern_scope_add(Tt_pattern p, Tt_scope s)`	Ad scope
`tt_pattern_sender_add(Tt_pattern p, const char *procid)`	Add sending process identifier
`tt_pattern_sender_ptype_add(Tt_pattern p, const char *ptid)`	Add sending process type
`tt_pattern_session_add(Tt_pattern p, const char *sessid)`	Add session identifier
`tt_pattern_state_add(Tt_pattern p, Tt_state s)`	Add state
`tt_pattern_user_set(Tt_pattern p, int key, void *v)`	Set user
`tt_pattern_register(Tt_pattern p)`	Register pattern
`tt_pattern_unregister(Tt_pattern p)`	Unregister pattern
`tt_pattern_destroy(Tt_pattern p)`	Destroy message pattern

Note –

The return type for all functions except tt_pattern_create is Tt_status; tt_pattern_create returns Tt_pattern.

Creating a Message Pattern

To create message patterns, use the tt_pattern_create function. You can use this function to get a handle or opaque pointer to a new pattern object, and then use this handle on succeeding calls to reference the pattern.

To fill in pattern information, use the tt_pattern_attribute_add and tt_pattern_attribute_set calls. You can supply multiple values for each attribute you add to a pattern. The pattern attribute matches a message attribute if any of the values in the pattern match the value in the message. If no value is specified for an attribute, the ToolTalk service assumes that you want any value to match. Some attributes are set and, therefore, can only have one value.

Adding a Message Pattern Callback

To add a callback routine to your pattern, use the tt_pattern_callback_add function.

Note –

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

When the ToolTalk service matches a message, it automatically calls your callback routine to examine the message and take appropriate actions. When a message that matches a pattern with a callback is delivered to you, it is processed through the callback routine. When the routine is finished, it returns TT_CALLBACK_PROCESSED and the API objects involved in the operation are freed. You can then use tt_message_destroy to destroy the message, which frees the storage used by the message, as illustrated in the following code sample.

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

	tt_message_destroy(m);
	return TT_CALLBACK_PROCESSED;
}

Registering a Message Pattern

To register the completed pattern, use the tt_pattern_register() function. After you register your pattern, you join the sessions or files of interest.

The following code sample creates and registers a pattern.

	/*
	 * Create and register a pattern so ToolTalk 
 * knows we are interested
	 * in “ttsample1_value” messages within 
 * the session we join.
	 */

	pat = tt_pattern_create();
	tt_pattern_category_set(pat, TT_OBSERVE);
	tt_pattern_scope_add(pat, TT_SESSION);
	tt_pattern_op_add(pat, “ttsample1_value”);
	tt_pattern_register(pat);

Deleting and Unregistering a Message Pattern

Note –

If delivered messages that matched the deleted pattern have not been retrieved by your application (for example, the messages might be queued), the ToolTalk service does not destroy these messages.

To delete a message pattern, use the tt_pattern_destroy() function. This function first unregisters the pattern and then destroys the pattern object.

To stop receiving messages that match a message pattern without destroying the pattern object, use the tt_pattern_unregister() to unregister the pattern.

The ToolTalk service will automatically unregister and destroy all message pattern objects when you call tt_close.