This chapter describes how to provide message pattern information to the ToolTalk service. The ToolTalk service uses message patterns to determine message recipients. After receiving a message, the ToolTalk service compares the message to all current message patterns to find a matching pattern. Once a match is made, the message is delivered to the application that registered the message pattern.
You can provide message pattern information to the ToolTalk service using either dynamic or static methods, or both. The method you choose depends on the type of messages you want to receive.
If the types of messages you want to receive will vary while your application is running, the dynamic method allows you to add, change, or remove message pattern information after your application has started.
If you want a message to start your application or to be queued if your application is not running, the static method provides an easy way to specify these instructions. The static method also provides an easy way to specify the message pattern information if you want to receive a defined set of messages. For more information, see Chapter 10, Static Message Patterns.
Regardless of the method you choose to provide message patterns to the ToolTalk service, you will want to update these patterns with each current session and file information so that you receive all messages that reference the session or file in which you are interested.
The attributes in your message pattern specify the type of messages you want to receive. Although some attributes are set and have only one value, you can supply multiple values for most of the attributes you add to a pattern.
Table 3–1 provides a complete list of attributes you can put in your message patterns.
Table 3–1 ToolTalk Message Pattern Attributes
Pattern Attribute |
Value |
Description |
---|---|---|
Category |
|
Declares whether you want to perform the operation listed in a message or only observe a message. |
Scope |
|
Declares interest in messages about a session or a file, or both; Join a session or file after the message pattern is registered to update the sessid and filename. |
Arguments |
arguments or results |
Declares the positional arguments for the operation in which you are interested. |
Context |
<name, value> |
Declares the keyword or non-positional arguments for the operation in which you are interested |
Class |
|
Declares whether you want to receive notices, requests, offers, or all. |
File |
char *pathname |
Declares the files in which you are interested. If the scope of the pattern does not require a file, the file is an attribute only. |
Object |
char *objid |
Declares what objects in which you are interested. |
Operation |
char *opname |
Declares the operations in which you are interested. |
Otype |
char *otype |
Declares the type of objects in which you are interested. |
address |
|
Declares the type of address in which you are interested. |
disposition |
|
Instructs the ToolTalk service how to handle messages to your application if an instance is not currently running. |
sender |
char *procid |
Declares the sender in which you are interested. |
sender_ptype |
char *ptype |
Declares the type of sending process in which you are interested. |
session |
char *sessid |
Declares the session in which you are interested. |
state |
|
Declares the state of the message in which you are interested. |
All your message patterns must at least specify:
Category — Whether the application wants to perform operations listed in messages or only view messages.
Use TT_OBSERVE
if you only want to observe messages.
Use TT_HANDLE
if you want to perform operations requested by the messages.
Use TT_HANDLE_PUSH
if you want to use the most recently registered pattern of this category
(if any) before using any pattern of another HANDLE
category
Use TT_HANDLE_ROTATE
if you want to use TT_HANDLE
.
If no eligible TT_HANDLE_PUSH
patterns are found, use the TT_HANDLE_ROTATE
pattern that was least recently used to deliver a message before
using any TT_HANDLE
patterns.
Scope — Whether the application is interested in messages about a particular session or file.
Use TT_SESSION
to receive messages from other processes in your session.
Use TT_FILE
to
receive messages about the file you have joined.
Use TT_FILE_IN_SESSION
to receive messages for the file you have joined while in this session.
Use TT_BOTH
to
receive both messages for the file, the session, or the file and the session
you have joined.
The ToolTalk service compares message attributes to pattern attributes as follows:
The ToolTalk service counts the message attribute as matched if:
No pattern attribute is specified.
The pattern does not name a context slot.
The pattern has an empty context slot.
The fewer pattern attributes you specify, the more messages you become eligible to receive.
If there are multiple values specified for a pattern attribute, one of the values must match the message attribute value. If no value matches, the ToolTalk service will not consider your application as a receiver.
If context slots are contained in the message, the ToolTalk service will not consider your application as a receiver unless:
A value specified in a context slot of a pattern matches the value specified in the message context slot.
When multiple context slots are specified in a message, each context slot value in the message matches a corresponding context slot value in the pattern.
You can specify the following types of scopes in your message patterns:
Scope to a session only.
Scope to a file only.
Scope only to a file in a particular session.
Scope to either or both a file and a session.
File scopes are restricted to NFS and UFS file systems; you cannot scope a file across other types of file systems (for example, a tmpfs file system).
The type TT_SESSION
scopes to a session only. Static session-scoped patterns require an explicit tt_session_join call to set the scope value; dynamic session-scoped
patterns can be set with either the tt_session_join call
or the tt_pattern_session_add call.
The session specified by these calls must be the default session.
Example 3–1 shows a static session-scoped pattern; Example 3–2 shows a dynamic session-scoped pattern.
Obtain procid |
tt_open(); |
Ptype is scoped to session |
tt_ptype_declare(ptype); |
Join session |
tt_session_join(tt_default_session()); |
Obtain procid |
tt_open(); |
Create pattern |
Tt_pattern pat = tt_create_pattern(); |
Add scope to pattern |
tt_pattern_scope_add(pat, TT_SESSION); |
Add session to pattern |
tt_pattern_session_add (tt_default_session()); |
Register pattern |
tt_pattern_register(pat); |
The type TT_FILE
scopes to a file only. Example 3–3 shows a static file-scoped pattern; Example 3–4 shows a dynamic file-scoped pattern.
Obtain procid |
tt_open(); |
Ptype is scoped to file |
tt_ptype_declare(ptype); |
Join file |
tt_file_join(file); |
Obtain procid |
tt_open(); |
Create pattern |
Tt_pattern pat = tt_create_pattern(); |
Add scope to pattern |
tt_pattern_scope_add(pat, TT_FILE); |
Add file to pattern |
tt_pattern_file_add (pat, file); |
Register pattern |
tt_pattern_register(pat); |
The type TT_FILE_IN_SESSION
scopes to the specified file in the specified session only.
A pattern with this scope set will only match messages that are scoped to
both the file and the session. Example 3–5 adds the session and then registers the pattern.
Obtain procid |
tt_open(); |
Create pattern |
Tt_pattern pat = tt_create_pattern(); |
Add scope to pattern |
tt_pattern_scope_add(pat,TT_FILE_IN_SESSION); |
Add file to pattern |
tt_pattern_file_add(pat, file); |
Add session to pattern |
tt_pattern_session_add(pat, tt_default_session()); |
Register pattern |
tt_pattern_register(pat); |
Example 3–6 registers the pattern and then joins a session.
TT_FILE_IN_SESSION
-Scoped Pattern
Obtain procid |
tt_open(); |
Create pattern |
Tt_pattern pat = tt_create_pattern(); |
Add scope to pattern |
tt_pattern_scope_add(pat, TT_FILE_IN_SESSION); |
Add file to pattern |
tt_pattern_file_add(pat, file); |
Register pattern |
tt_pattern_register(pat); |
Join session |
tt_session_join(tt_default_session()); |
Example 3–7 sets the scope value for a static pattern.
TT_FILE_IN_SESSION
Static Pattern
Obtain procid |
tt_open(); |
Declare Ptype |
Tt_ptype_declare(ptype); |
Join File |
tt_file_join(file); |
Join session |
tt_session_join(tt_default_session()); |
A TT_BOTH
-scoped
pattern will match messages that are scoped to the file, the session, or the
file and the session. However, when you use this scope, you must explicitly
make a tt_file_join call; otherwise, the ToolTalk service
will only match messages that are scoped to both the file and session of the
registered pattern. Example 3–8 and Example 3–9 show examples of how to use this scope.
TT_BOTH
Scope
Obtain procid |
tt_open(); |
Create pattern |
Tt_pattern pat = tt_create_pattern(); |
Add scope to pattern |
tt_pattern_scope_add(pat, TT_BOTH); |
Add session to pattern |
tt_pattern_session_add(pat,tt_default_session()); |
Add file to pattern |
tt_pattern_file_add (pat, file); |
Register pattern |
tt_pattern_register(pat); |
TT_BOTH
Scope
Obtain procid |
tt_open(); |
Declare Ptype |
Tt_ptype_declare(ptype); |
Join file |
tt_file_join(file); |
Join session |
tt_session_join(tt_default_session()); |
To match TT_SESSION
-scoped messages and TT_SESSION
-scoped patterns that have the same file attributes, you can
add file attributes to TT_SESSION
-scoped
patterns with the tt_pattern_file_add call, as shown in Example 3–10.
The file attribute values do not affect the scope of the pattern.
Obtain procid |
tt_open(); |
Create pattern |
Tt_pattern pat = tt_create_pattern(); |
Add scope to pattern |
tt_pattern_scope_add(pat, TT_SESSION); |
Add session to pattern |
tt_pattern_session_add(tt_default_session()); |
Add first file attribute to pattern |
tt_pattern_file_add(pat, file1); |
Add second file attribute to pattern |
tt_pattern_file_add(pat, file2); |
Register pattern |
tt_pattern_register(pat); |
ToolTalk contexts are sets of <name, value> pairs explicitly included in both messages and patterns. ToolTalk contexts allow fine-grain matching.
You can use contexts to associate arbitrary pairs with ToolTalk messages and patterns, and to restrict the set of possible recipients of a message. One common use of the restricted pattern matching provided by ToolTalk context attributes is to create sub-sessions. For example, two different programs could be debugged simultaneously with tools such as a browser, an editor, a debugger, and a configuration manager active for each program. The message and pattern context slots for each set of tools contain different values; the normal ToolTalk pattern matching of these values keep the two sub-sessions separate.
Another use for the restricted pattern matching provided by ToolTalk context attributes is to provide information in environment variables and command line arguments to tools started by the ToolTalk service.
ToolTalk pattern arguments may be strings, binary data, or integer values which Tooltalk service uses to match against incoming messages.
Arguments differ from contexts in that arguments are positional paramaters while contexts are named paramaters. The order of arguments, set in a message, determines the order in which they are present in the sent and received message. That is, they must agree with the order and types of arguments set in a pattern. Since arguments are positional, you must add a “wildcard” argument for intermidiate arguments in a pattern if you wish to match an argument that is not the first argument in the incoming message. Wildcard arguments should have the vtype of “ALL” and the value of NULL.
You must use the pattern argument adding API call that matches the type of your argument (integer, binary data, or ASCII string). In particular, you should note that it is not possible to add a pattern argument with a wildcard value of NULL with tt_pattern_iarg_add(), since NULL, or 0 is a valid integer argument value. To add wildcard arguments, use tt_pattern_arg_add().
Disposition attributes instruct the ToolTalk service how to handle messages to your application if an instance of the application is not currently running.
The disposition value specified in the static type definition of a pattern
is the default disposition; however, if the message deposition specifies the
handler ptype the default disposition value is over-ridden. For example, a
message disposition specifies a static type definition for the ptype UWriteIt which includes the message signature Display. This message signature does not match any of the static signatures
in the pattern. The ToolTalk service will follow the instructions for the
disposition set in the message; for example, if the message disposition is TT_START
and the UWriteIt
ptype specifies a start string, the ToolTalk service will start an instance
of the application if one is not running.