This chapter explains how messages are routed, and describes the ToolTalk message attributes and algorithm. It also describes how to create messages, fill in message contents, attach callbacks to requests, and send messages.
Applications can send two classes of ToolTalk messages, notices and requests. A notice is informational, a way for an application to announce an event. Applications that receive a notice absorb the message without returning results to the sender. A request is a call for an action, with the results of the action recorded in the message, and the message returned to the sender as a reply.
When you send an informational message, the notice takes a one-way trip, as shown in Figure 8–1.
The sending process creates a message, fills in attribute values, and sends it. The ToolTalk service matches message and pattern attribute values, then gives a copy of the message to one handler and to all matching observers. File-scoped messages are automatically transferred across session boundaries to processes that have declared interest in the file.
When you send a message that is a request, the request takes a round-trip from sender to handler and back; copies of the message take a one-way trip to interested observers. Figure 8–2 illustrates the request routing procedure.
The ToolTalk service delivers a request to only one handler. The handler adds results to the message and sends it back. Other processes can observe a request before or after it is handled, or at both times; observers absorb a request without sending it back.
Offers are messages similar to Requests. However, responses are not expected when data are sent. Also, you can tell how many potential recipients there are for the message at the time it is sent. You can also tell whether those recipients have accepted, rejected, or “abstained” the message. Consequently, Offers is less general than Notices and Requests.
To allow you to track the progress of a request you sent, you will receive a message every time the request changes state. You will receive these state change messages even if no patterns have been registered, or no message callbacks have been specified.
ToolTalk messages contain attributes that store message information and provide delivery information to the ToolTalk service. This delivery information is used to route the messages to the appropriate receivers.
ToolTalk messages are simple structures that contain attributes for address, subject (such as operation and arguments), and delivery information (such as class and scope.) Each message contains attributes from Table 8–1.
Table 8–1 ToolTalk Message Attributes
Message Attribute |
Value |
Description |
Who Can Complete |
---|---|---|---|
Arguments |
arguments or results |
Specifies arguments used in the operation. If the message is a reply, these arguments contain the results of the operation. |
Sender, receiver |
Class |
|
Specifies whether the recipient needs to perform an operation. |
Sender |
File |
char *pathname |
Specifies the file involved in the operation. If the scope of the message does not require a file, the file is an attribute only. |
Sender, ToolTalk |
Object |
char *objid |
Specifies the object involved in the operation. |
Sender, ToolTalk |
Operation |
char *opname |
Specifies the name of operation to be performed. |
Sender |
Otype |
char *otype |
Specifies the type of object involved in the operation. |
Sender, ToolTalk |
Address |
|
Specifies where the message should be sent. |
Sender |
Handler |
char *procid |
Specifies the receiving process. |
Sender, ToolTalk |
Handler_ptype |
char *ptype |
Specifies the type of receiving process. |
Sender, ToolTalk |
Disposition |
|
Specifies what to do if the message cannot be received by any running process. |
Sender, ToolTalk |
Scope |
|
Specifies the applications that will be considered as potential recipients based on their registered interest in a session or file. |
Sender, ToolTalk |
Sender_ptype |
char *ptype |
Specifies the type of the sending process. |
Sender, ToolTalk |
Session |
char *sessid |
Specifies the sending process's session. |
Sender, ToolTalk |
Status |
int status, char *status_str |
Specifies additional information about the status of the message. |
Receiver, ToolTalk |
Messages addressed to other applications can be addressed to a particular process or to any process that has registered a pattern that matches your message. When you address a message to a process, you need to know the process identifier (procid) of the other application. However, processes do not usually know each other's procid; more often, a sender does not care which process performs an operation (request message) or learns of an event (notice message).
Applications that use the ToolTalk service to communicate usually have something in common – the applications are running in the same session, or they are interested in the same file or data. To register this interest, applications join sessions or files (or both) with the ToolTalk service. This file and session information is used by the ToolTalk service with the message patterns to determine which applications should receive a message.
The scope attributes are restricted to NFS and UFS files systems; file scoping does not work across file systems (for example, a tmpfs file system.)
When a message is scoped to a file, only those applications that have joined the file (and match the remaining attributes) will receive the message. Applications that share interest in a file do not have to be running in the same session.
Table 8–2 describes the types of scopes that use files which you can use to scope messages with patterns.
Table 8–2 Scoping a Message with Patterns to a File
Type of Scope |
Description |
---|---|
|
Scopes to the specified file only. You can
set a session attribute on this type of pattern to provide a file-in-session-like
scoping but a tt_session_join call will not
update the session attribute of a pattern that is scoped to |
|
Scopes to the union of interest in the file and the session. A pattern with only this scope will match messages that are scoped to the file, or scoped to the session, or scoped to both the file and the session. |
|
Scopes to the intersection of interest in the file and the session. A pattern with only this scope will only match messages that are scoped to both the file and session. |
To scope to the union of TT_FILE_IN_SESSION
and TT_SESSION
,
add both scopes to the same pattern, as shown in Example 8–1.
TT_FILE_IN_SESSION
and TT_SESSION
Messages have the same types of file-based scoping mechanisms as patterns. Table 8–3 describes these scopes.
Table 8–3 Scoping Mechanisms for Messages
When a message is scoped to TT_FILE
or TT_BOTH
, the ToolTalk client
library checks the database server for all sessions that have clients that
are interested in the file and sends the message to all of the interested
ToolTalk sessions. The ToolTalk sessions then match the messages to the appropriate
clients. The message sender is not required to explicitly
call to tt_file_join.
If a message that is scoped to TT_FILE_IN_SESSION
or TT_SESSION
contains
a file, the database server is not contacted and the message is sent only
to clients that are scoped to the message's session.
When a message is scoped to a session, only those applications that have connected to that session are considered as potential recipients.
Tt_message m= tt_message_create(); tt_message_scope_set(m, TT_SESSION); tt_message_file_set(m, file); |
The first line creates message. The second line adds scope to message, and the last line adds file attribute that does not affect message scope.
Applications can be very specific about the distribution of a message by specifying TT_FILE_IN_SESSION for the message scope. Only those applications that have joined both the file and the session indicated are considered potential recipients.
Applications can also scope a message to every client that has registered interest in the message's session by specifying TT_SESSION with tt_message_file_set for the message scope. When the message is received by a client whose pattern matches, the receiving client can get the file name by calling tt_message_file.
Tt_message m= tt_message_create(); tt_message_scope_set(m, TT_FILE_IN_SESSION); tt_message_file_set(m, file); |
The first line creates message. The second line adds scope. The third line adds file to message scope.
The ToolTalk service supports three types of data for message arguments: integers, null-terminated strings, and byte strings.
To send any other data type in a ToolTalk message, the client must serialize the data into a string or byte string and then deserialize it on receipt. The new XDR argument API calls provided with the ToolTalk service now handles these serialization and deserialization functions. The client only needs to provide an XDR routine and a pointer to the data. After serializing the data into the internal buffer, the ToolTalk service treats the data in the same manner as it treats a byte stream.
To help you further understand how the ToolTalk service determines message recipients, this section describes the creation and delivery of both process-oriented messages and object-oriented messages.
For some process-oriented messages, the sending application knows the ptype or the procid of the process that should handle the message. For other messages, the ToolTalk service can determine the handler from the operation and arguments of the message.
Initialize.
The sender obtains a message handle and fills in the address, scope, and class attributes.
The sender fills in the operation and arguments attributes.
If the sender has declared only one ptype, the ToolTalk service fills in sender_ptype by default; otherwise, the sender must fill it in.
If the scope is TT_FILE
,
the file name must be filled in or defaulted. If the scope is TT_SESSION
, the session name must be filled
in or defaulted. If the scope is TT_BOTH
or TT_FILE_IN_SESSION
, both the
file name and session name must be filled in or defaulted.
The set of patterns checked for delivery depends on the scope
of the message. If the scope is TT_SESSION
, only patterns for processes in the same session are checked.
If the scope is TT_FILE
, patterns
for all processes observing the file are checked. If the scope is TT_FILE_IN_SESSION
or TT_BOTH
, both sets of processes are checked.
The sender may fill in the handler_ptype if known. However, this greatly reduces flexibility because it does not allow processes of one ptype to substitute for another. Also, the disposition attribute must be specified by the sender in this case.
Dispatch to handler.
The ToolTalk service compares the address, scope, message class, operation, and argument modes and types to all signatures in the Handle section of each ptype.
Only one ptype will usually contain a message pattern that matches the operation and arguments and specifies a handle. If a handler ptype is found, then the ToolTalk service fills in opnum, handler_ptype, and disposition from the ptype message pattern.
If the address is TT_HANDLER
,
the ToolTalk service looks for the specified procid and adds the message to
the handler's message queue. TT_HANDLER
messages cannot be observed because no pattern matching is done.
Dispatch to observers.
The ToolTalk service compares the scope, class, operation, and argument types to all message patterns in the Observe section of each ptype.
For all observe signatures that match the message and specify TT_QUEUE
or TT_START
, the ToolTalk service attaches a record (called an “observe
promise”) to the message that specifies the ptype and the queue or start
options. The ToolTalk service then adds the ptype to its internal ObserverPtypeList.
Deliver to handler.
If a running process has a registered handler message pattern that matches the message, the ToolTalk service delivers the message to the process; otherwise, the ToolTalk service honors the disposition (start or queue) options.
If more than one process has registered a dynamic pattern that matches the handler information, the more specific pattern (determined by counting the number of non-wildcard matches) is given preference. If two patterns are equally specific, the choice of handler is arbitrary.
Deliver to observers.
The ToolTalk service delivers the message to all running processes that have registered Observer patterns that match the message. As each delivery is made, the ToolTalk service checks off any observe promise for the ptype of the observer. After this process is completed and there are observe promises left unfulfilled, the ToolTalk service honors the start and queue options in the promises.
In this example, a debugger uses an editor to display the source around a breakpoint through ToolTalk messages.
The editor has the following Handle pattern in its ptype:
(HandlerPtype: TextEditor; Op: ShowLine; Scope: TT_SESSION; Session: my_session_id; File: /home/butterfly/astrid/src/ebe.c) |
When the debugger reaches a breakpoint, it sends a message
that contains the op (ShowLine), argument (the line number), file (the file
name), session (the current session id), and scope (TT_SESSION
)
attributes.
The ToolTalk service matches this message against all registered patterns and finds the pattern registered by the editor.
The ToolTalk service delivers the message to the editor.
The editor then scrolls to the line indicated in the argument.
Many messages handled by the ToolTalk service are directed at objects but are actually delivered to the process that manages the object. The message signatures in an otype, which include the ptype of the process that can handle each specific message, help the ToolTalk service determine process to which it should deliver an object-oriented message.
Initialize.
The sender fills in the class, operation, arguments, and the target objid attributes.
The sender attribute is automatically filled in by the ToolTalk service. The sender can either fill in the sender_ptype and session attributes or allow the ToolTalk service to fill in the default values.
If the scope is TT_FILE
,
the file name must be filled in or defaulted. If the scope is TT_SESSION
, the session name must be filled
in or defaulted. If the scope is TT_BOTH
or TT_FILE_IN_SESSION
, both the
file name and session name must be filled in or defaulted.
The set of patterns checked for delivery depends on the scope
of the message. If the scope is TT_SESSION
, only patterns for processes in the same session are checked.
If the scope is TT_FILE
, patterns
for all processes observing the file are checked. If the scope is TT_FILE_IN_SESSION
or TT_BOTH
, both sets of processes are checked.
Resolve.
The ToolTalk service looks up the objid in the ToolTalk database and fills in the otype and file attributes.
Dispatch to handler.
The ToolTalk service searches through the otype definitions for Handler message patterns that match the message's operation and arguments attributes. When a match is found, the ToolTalk service fills in scope, opnum, handler_ptype, and disposition from the otype message pattern.
Dispatch to object-oriented observers.
The ToolTalk service compares the message's class, operation, and argument attributes against
all Observe message patterns of the otype. When a match is found, if the message
pattern specifies TT_QUEUE
or TT_START
, the ToolTalk service attaches a
record (called an “observe promise”) to the message that specifies
the ptype and the queue or start options.
Dispatch to procedural observers.
The ToolTalk service continues to match the message's class, operation, and argument
attributes against all Observe message patterns of all ptypes. When a match
is found, if the signature specifies TT_QUEUE
or TT_START
, the
ToolTalk service attaches an observe promise record to the message, specifying
the ptype and the queue or start options.
Deliver to handler.
If a running process has a registered Handler pattern that matches the message, the ToolTalk service delivers the message to the process; otherwise, the ToolTalk service honors the disposition (queue or start) options.
If more than one process has registered a dynamic pattern that matches the handler information, the more specific pattern (determined by counting the number of non-wildcard matches) is given preference. If two patterns are equally specific, the choice of handler is arbitrary.
Deliver to observers.
The ToolTalk service delivers the message to all running processes that have registered Observer patterns that match the message. As each delivery is made, the ToolTalk service checks off any observe promise for the ptype of the observer. After this process is completed and there are observe promises left unfulfilled, the ToolTalk service honors the disposition (queue or start) options in the promises.
In this example, a hypothetical spreadsheet application named FinnogaCalc is integrated with the ToolTalk service.
FinnogaCalc starts and registers with the ToolTalk service by declaring its ptype, FinnogaCalc, and joining its default session.
FinnogaCalc loads a worksheet, hatsize.wks, and tells the ToolTalk service it is observing the worksheet by joining the worksheet file.
A second instance of FinnogaCalc (called FinnogaCalc2) starts, loads a worksheet, wardrobe.wks, and registers with the ToolTalk service in the same way.
The user assigns the value of cell B2 in hatsize.wks to also appear in cell C14 of wardrobe.wks.
So that FinnogaCalc can send the value to FinnogaCalc2, FinnogaCalc2 creates an object spec for cell C14 by calling a ToolTalk function. This object is identified by an objid.
FinnogaCalc2 then gives this objid to FinnogaCalc (for example, through the clipboard).
FinnogaCalc remembers that its cell B2 should appear in the object identified by this objid and sends a message that contains the value.
ToolTalk routes the message. To deliver the message, the ToolTalk service:
Examines the spec associated with the objid and finds that the type of the objid is FinnogaCalc_cell and that the corresponding object is in the file wardrobe.wks.
Consults the otype definition for FinnogaCalc_cell. From the otype, the ToolTalk service determines that this message
is observed by processes of ptype FinnogaCalc and that
the scope of the message should be TT_FILE
.
Matches the message against registered patterns and locates all processes of this ptype that are observing the proper file. FinnogaCalc2 matches, but FinnogaCalc does not.
Delivers the message to FinnogaCalc2.
FinnogaCalc2 recognizes that the message contains an object that corresponds to cell C14. FinnogaCalc2 updates the value in wardrobe.wks and displays the new value.
Sometimes you may need to send an object-oriented message without knowing the objid. To handle these cases, the ToolTalk service provides otype addressing. This addressing mode requires the sender to specify the operation, arguments, scope, and otype. The ToolTalk service looks in the specified otype definition for a message pattern that matches the message's operation and arguments to locate handling and observing processes. The dispatch and delivery then proceed as in messages to specific objects.
To send ToolTalk messages, your application must perform several operations: it must be able to create and complete ToolTalk messages; it must be able to add message callback routines; and it must be able to send the completed message.
The ToolTalk service provides three methods to create and complete messages:
General-purpose function
tt_message_create()
Process-oriented notice and request functions
tt_pnotice_create()
tt_prequest_create()
Object-oriented notice and request functions
tt_onotice_create()
tt_orequest_create()
The process- and object-oriented notice and request functions make message creation simpler for the common cases. They are functionally identical to strings of other tt_message_create() and tt_message_ attribute__set() calls, but are easier to write and read. Table 8–4 and Table 8–5 list the ToolTalk functions that are used to create and complete message
Table 8–4 Functions Used to Create Messages
ToolTalk Function |
Description |
---|---|
tt_onotice_create(const char *objid, const char *op) |
Creates an object-oriented notice. |
tt_orequest_create(const char *objid, const char *op) |
Creates an object-oriented request. |
tt_pnotice_create(Tt_scope scope, const char *op) |
Creates a process-oriented notice. |
tt_prequest_create(Tt_scope scope, const char *op) |
Creates a process-oriented request. |
tt_message_create(void) |
Creates a message. This function is the ToolTalk general purpose function to create messages. |
The return type for all the create functions is Tt_message.
ToolTalk Function |
Description |
---|---|
tt_message_address_set(Tt_message m, Tt_address p) |
Sets addressing mode (for example, point-to-point). |
tt_message_arg_add(Tt_message m, Tt_mode n, const char *vtype, const char *value) |
Adds a null-terminated string argument. |
tt_message_arg_bval_set(Tt_message m, int n, const unsigned char *value, int len) |
Sets an argument's value to the specified byte array. |
tt_message_arg_ival_set(Tt_message m, int n, int value) |
Sets an argument's value to the specified integer. |
tt_message_arg_val_set(Tt_message m, int n, const char *value) |
Sets an argument's value to the specified null-terminated string. |
tt_message_barg_add(Tt_message m, Tt_mode n, const char *vtype, const unsigned char *value, int len) |
Adds a byte array argument. |
tt_message_iarg_add(Tt_message m, Tt_mode n, const char *vtype, int value) |
Adds an integer argument. |
tt_message_context_bval(Tt_message m, const char *slotname, unsigned char **value, int *len); |
Gets a context's value to the specified byte array. |
tt_message_context_ival(Tt_message m, const char *slotname, int *value); |
Gets a context's value to the specified integer. |
tt_message_context_val(Tt_message m, const char *slotname); |
Gets a context's value to the specified string. |
tt_message_icontext_set(Tt_message m, const char *slotname, int value); |
Sets a context to the specified integer. |
tt_message_bcontext_set(Tt_message m, const char *slotname, unsigned char *value, int length); |
Sets a context to the specified byte array. |
tt_message_context_set(Tt_message m, const char *slotname, const char *value); |
Sets a context to the specified null-terminated string. |
tt_message_class_set(Tt_message m, Tt_class c) |
Sets the type of message (either notice or request) |
tt_message_file_set(Tt_message m, const char *file) |
Sets the file to which the message is scoped. |
tt_message_handler_ptype_set(Tt_message m, const char *ptid) |
Sets the ptype that is to receive the message. |
tt_message_handler_set(Tt_message m, const char *procid) |
Sets the procid that is to receive the message. |
tt_message_object_set(Tt_message m, const char *objid) |
Sets the object that is to receive the message. |
tt_message_op_set(Tt_message m, const char *opname) |
Sets the operation that is to receive the message. |
tt_message_otype_set(Tt_message m, const char *otype) |
Sets the object type that is to receive the message. |
tt_message_scope_set(Tt_message m, Tt_scope s) |
Sets the recipients who are to receive the message (file, session, both). |
tt_message_sender_ptype_set(Tt_message m, const char *ptid) |
Sets the ptype of the application that is sending the message. |
tt_message_session_set(Tt_message m, const char *sessid) |
Sets the session to which the message is scoped. |
tt_message_status_set(Tt_message m, int status) |
Sets the status of the message; this status is seen by the receiving application. |
tt_message_status_string_set(Tt_message m, const char *status_str) |
Sets the text that describes the status of the message; this text is seen be the receiving application. |
tt_message_user_set(Tt_message m, int key, void *v) |
Sets a message that is internal to the sending application. This internal message is opaque data that is not seen by the receiving application. |
tt_message_abstainer(Tt_message m, int n) |
Returns the procid of the n'th abstainer of the specified message. |
tt_message_abstainers_count(Tt_message m) |
Returns a count of the procids that are recorded in the |
tt_message_accepter(Tt_message m,int n) |
Returns the procid of the n'th accepter of the specified message. |
tt_message_accepters_count(Tt_message m) |
Returns a count of the procids that are recorded in the |
tt_message_rejecter(Tt_message m,int n) |
Returns the procid of the n'th rejector of the specified message. |
tt_message_rejecters_count(Tt_message m)
|
Returns a count of the procids that are recorded in the |
The return type for all the functions used to complete messages is Tt_status
You can use the general-purpose function tt_message_create() to create and complete ToolTalk messages. If you create a process- or object-oriented message with tt_message_create(), use the tt_message_attribute_set() calls to set the attributes.
Use TT_REQUEST
for messages that return values or status. You will be informed when the message
is handled or queued, or when a process is started to handle the request.
Use TT_NOTICE
for
messages that only notify other processes of events.
Use TT_OFFER
for
messages for which there are multiple intended recipients, and for which you
wish to determine how many of those recipients have accepted, rejected, or
abstained from participation in this message.
Use TT_PROCEDURE
to
send the message to any process that can perform this operation with these
arguments. Fill in op and args attributes of this message.
Use TT_OTYPE
to
send the message to this type of object that can perform this operation with
these arguments. Fill in otype, op, and args attributes of the message.
Use TT_HANDLER
to send the message to a specific process. Specify the handler attribute value.
Usually, one process makes a general request, picks the handler attribute from the reply, and directs further messages to that handler. If you specify the exact procid of the handler, the ToolTalk service will deliver the message directly — no pattern matching is done and no other applications can observe the message. This point-to-point (PTP) message passing feature enables two processes to rendezvous through broadcast message passing and then communicate explicitly with one another.
Offers can only be sent with address TT_PROCEDURE
. Attempting to send an Offer with any other address
will generate an error of TT_ERR_ADDRESS
.
Use TT_OBJECT
to send the message to a specific object that performs this operation with
these arguments. Fill in object, op,
and args attributes of this message.
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 will add the default session or file, or both to the message.
Note that Offers can only be sent in TT_SESSION
scope.
Fill in the operation that describes the notification or request that you are making. To determine the operation name, consult the ptype definition for the target recipient or the message protocol definition.
Fill in any arguments specific to the operation. Use the function that best suits your argument's data type:
tt_message_arg_add()
Adds an argument whose value is a zero-terminated character string.
tt_message_barg_add()
Adds an argument whose value is a byte string.
tt_message_iarg_add()
Adds an argument whose value is an integer.
For each argument you add (regardless of the value type), specify:
Tt_mode
Specify TT_IN
or TT_INOUT
. TT_IN
indicates that the argument is written by the sender and
can be read by the handler and any observers. TT_INOUT
indicates that the argument is written by the sender
and the handler and can be read by all. If you are sending a request that
requires the handler to provide an argument in return, use TT_INOUT.
Value Type
The value type (vtype) describes the type of argument data that is to be added. The ToolTalk service uses the vtype name when it compares a message to registered patterns to determine a message's recipients. The ToolTalk service does not use the vtype to process a message or pattern argument value.
The vtype name helps the message receiver interpret data. For example, if a word processor rendered a paragraph into a PostScript representation in memory, it could call tt_message_arg_add with the following arguments:
tt_message_arg_add (m, “PostScript”, buf);
In this case, the ToolTalk service would assume buf pointed to a zero-terminated string and send it.
Similarly, an application could send an enum value in a ToolTalk message; for example, an element of Tt_status:
tt_message_iarg_add(m, “Tt_status”, (int) TT_OK);
The ToolTalk service sends the value as an integer but the Tt_status vtype tells the recipient what the value means.
It is very important that senders and receivers define particular vtype names so that a receiver does not attempt to retrieve a value that was stored in another fashion; for example, a value stored as an integer but retrieved as a string.
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:
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).
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.
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:
Objid
Fill in the unique object identifier.
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.
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.
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.
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.
You can also add callbacks to static patterns by attaching a callback to the opnum of a signature in a ptype. When a message is delivered because it matched a static pattern with an opnum, the ToolTalk service checks for any callbacks attached to the opnum and runs them.
Use tt_otype_opnum_callback_add to attach the callback routine to the opnum of an osignature.
Use tt_ptype_opnum_callback_add to attach the callback routine to the opnum of a psignature.
When you have completed your message, use tt_message_send to send it.
If the ToolTalk service returns TT_WRN_STALE_OBJID
, it has found a forwarding pointer in the ToolTalk database
that indicates the object mentioned in the message has been moved. However,
the ToolTalk service will send the message with the new objid. You can then
use tt_message_object to retrieve the new objid from the
message and put it into your internal data structure.
If you will not need the message in the future (for example, if the message was a notice), you can use tt_message_destroy to delete the message and free storage space.
If you are expecting a reply to the message, do not destroy the message until you have handled the reply.
Example 8–5 illustrates how to create and send a pnotice.
Example 8–6 illustrates how an orequest is created and sent when the callback routine for cntl_ui_hilite_button is called.