To create message patterns, use the tt_pattern_create() function. You can use this funtion 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 asumes that you want any value to match. See Table 3-1 for a complete list of pattern attributes.

---

Note: Some attributes are set and, therefore, can only have one value.

---

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

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; 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 msg ...

	tt_message_destroy(m);
	return TT_CALLBACK_PROCESSED;
}

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);

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

When you join a session or file, the ToolTalk service updates your message pattern with the sessid. For example, if you have declared a ptype or registered a message pattern that specifies TT_SESSION or TT_FILE_IN_SESSION, use tt_session_join() join the default sessionThe following code sample shows how to join the default session.

/*
 * Join the default session
 */

tt_session_join(tt_default_session());

Table 3-3 lists the ToolTalk functions you use to join the session in which you are interested.

Once your patterns are updated, you will begin to receive messages scoped to the session you joined.

---

Note: If you had previously joined a session and then registered a ptype or a new message pattern, you must again join the same session or a new session to update your pattern before you will receive messages that match your new pattern.

---

When you no longer want to receive messages that reference the default session, use the tt_session_quit() function. This function removes the sessid from your session–scoped message patterns.

When you join a file, the ToolTalk service automatically adds the name of the file to your file-scoped message patterns. For example, if you have declared a process type or registered a message pattern that specifies TT_FILE or TT_FILE_IN_SESSION, use the tt_file_join() function to join files of interested. Table 3-4 lists the ToolTalk functions you use to express your interest in specific files.

When you no longer want to receive messages that reference the file, use the tt_file_quit() function to remove the file name from your file–scoped message patterns.