#
# Copyright (c) 1992 Sun Microsystems, Inc.  All rights reserved.
#
:panel
Using TTSnoop
-------------
To observe messages select the Start setting choice.

To turn off message observation select the Stop
setting choice.

To limit the types of messages:
        1) Select Patterns button
        2) Enter the type of pattern you want
           to observe
        3) Select Apply button

To highlite information that is displayed:
        1) Select Display button
        2) Mark those items that you want to highlite
        3) Select Apply button

To send a message:
        1) Select the Messages button
        2) Compose the message
        3) Select the Send Message button

To store a message:
        1) Select the Message button
        2) Compose the message
        3) Select the Add Message button

To send a stored message:
        Select the message from the
        Send Message menu

To clear the message output window select the Clear button.

# 
:mode_setting
Start/Stop receiving and displaying messages.

# 
:clear_button
Clear the message window.

# 
:display_button
Brings up a panel that allows you to select
information that will be highlighted with
an arrow in the display.

Display
-------
When a message arrives for your process, a file
descriptor becomes active. Depending on the
particular structure of your tool, you can either
arrange for the window system toolkit to call a
callback when the file descriptor becomes active,
or include the file descriptor in a select(3)
call that blocks on a number of file
descriptors.  In either case, after the file
descriptor becomes active, you call
tt_message_receive() to get a handle for a
message containing the incoming message.
You can use the tt_message_*() calls to examine
the attributes of the message to determine the
action you should take. You can recognize replies
to messages you sent by comparing the handles, by
placing information meaningful to your
application in the message with the
tt_message_user_set() call, or by placing
specific callbacks on messages and patterns with
the tt_message_callback_add and
tt_pattern_callback_add calls.

# 
:send_button
Brings up a panel to define messages.

Messages
--------
To send a message, first allocate a new message,
fill in the proper information, then send it. Any
reply will show up in the same message. When
finished with the message free the storage for
the message. (for value returning requests, this
is after any needed return values are copied out;
for notifications, this is right after its been
sent),


To allocate the new message, use
tt_message_create(). It returns a "handle" or
"opaque pointer" to the message; use this handle
on succeeding calls to reference this message.


To fill in message information, use the
tt_message_*_set() calls; there is one of these
for each attribute of the message.

You should normally set Class, Address, Op and Args.

Send the message with tt_message_send().

# 
:receive_button
Brings up a panel to define a pattern
to watch for.

Patterns
--------
Since messages are not explicitly directed to a
particular receiver by the sending process, a
"pattern matching" method is used to determine
the receiver. Tools register descriptions of the
messages in which they are interested and
ToolTalk uses these descriptions to infer the
routing of the message. Separate sets of patterns
are kept to describe the messages the tool wants
to handle and the messages the tool wants to
observe. Tools wishing to receive messages
declare their interest either dynamically at run
time or statically at installation time. A
dynamic registration consists of a set of
patterns against which all messages are
compared.  If a message matches the pattern, the
tool which registered the pattern is eligible to
receive the message.

Before receiving procedural messages through
ToolTalk, a process must register with the
message passer. By registering, the process gives
patterns to ToolTalk; which then delivers
messages that match those patterns to the
process.  The patterns can be created in two
ways:

Statically. Through a ptype. A process can
declare its ptype to the message passer; ToolTalk
then generates patterns from each signature in
the ptype.  These generated patterns can be
modified by joining and quitting sessions and
files.

Dynamically. A process can create patterns "on
the fly" and register them with ToolTalk. A
typical use of this facility would be a message
logging utility that simply observes all messages
that go by, displaying them in a window; such a
utility would be useful in debugging message
protocols.

This application uses only the Dynamic patterns.

To register a pattern, first you must allocate a
new pattern, fill in the proper information, then
register it.  When you are through with the
pattern (which is only after you no longer are
interested in messages that match it), free the
storage for the pattern.

To allocate the new pattern, use
tt_pattern_create(). It returns a "handle" or
"opaque pointer" to the pattern; use this handle
on succeeding calls to reference this pattern.

To fill in pattern information, use the
tt_pattern_*_add() calls; there is one of these
for each attribute of the pattern. It is possible
to supply multiple values for each attribute in
the pattern; the pattern attribute matches a
message attribute if any of the values in the
pattern match the value in the message.

This application uses non-exclusive settings and
comma separated values for the multiple
attributes.

To match messages without regard to the value in
a particular attribute, simply omit the attribute
from the pattern.

If no pattern attribute is specified, the
ToolTalk service counts the message attribute as
matched. 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.

The attributes Category and Scope must always be
supplied.

When the pattern is complete, register the
pattern with tt_pattern_register(), and then join
sessions or files as required by SELECT'ing the
Apply button.

Since the primary effect of joining files and
sessions is to update currently registered
patterns, patterns that are registered after
the joins will not be updated. You should either
register all patterns before joining, or re-do
the joins after registering new patterns (alternatively
one can do session or file sets on the pattern
directly). This applies to patterns registered 
implicitly by joining ptypes, as well.

# 
:send_msg_button
As you add messages via the Messages window,
the menu attached to this button grows.  You
may send the defined message by selecting it.
