[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
1.1 XEmacs ToolTalk API Summary | ||
1.2 Sending Messages | ||
1.3 Receiving Messages |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Emacs Lisp interface to ToolTalk is similar, at least in spirit, to the standard C ToolTalk API. Only the message and pattern parts of the API are supported at present; more of the API could be added if needed. The Lisp interface departs from the C API in a few ways:
'TT_SESSION
. This
simplifies building lists that represent messages and patterns.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
1.2.1 Example of Sending Messages | ||
1.2.2 Elisp Interface for Sending Messages |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here’s a simple example that sends a query to another application and then displays its reply. Both the query and the reply are stored in the first argument of the message.
(defun tooltalk-random-query-handler (msg) (let ((state (get-tooltalk-message-attribute msg 'state))) (cond ((eq state 'TT_HANDLED) (message (get-tooltalk-message-attribute msg arg_val 0))) ((memq state '(TT_FAILED TT_REJECTED)) (message "Random query turns up nothing"))))) (defvar random-query-message '( class TT_REQUEST scope TT_SESSION address TT_PROCEDURE op "random-query" args '((TT_INOUT "?" "string")) callback tooltalk-random-query-handler)) (let ((m (make-tooltalk-message random-query-message))) (send-tooltalk-message m))
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Create a ToolTalk message and initialize its attributes. The value of attributes must be a list of alternating keyword/values, where keywords are symbols that name valid message attributes. For example:
(make-tooltalk-message '(class TT_NOTICE scope TT_SESSION address TT_PROCEDURE op "do-something" args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
Values must always be strings, integers, or symbols that represent
ToolTalk constants. Attribute names are the same as those supported by
set-tooltalk-message-attribute
, plus args
.
The value of args
should be a list of message arguments where
each message argument has the following form:
‘(mode [value [type]])’ or just ‘value’
Where mode is one of TT_IN
, TT_OUT
, or
TT_INOUT
and type is a string. If type isn’t
specified then int
is used if value is a number; otherwise
string
is used. If type is string
then value
is converted to a string (if it isn’t a string already) with
prin1-to-string
. If only a value is specified then mode
defaults to TT_IN
. If mode is TT_OUT
then
value and type don’t need to be specified. You can find out
more about the semantics and uses of ToolTalk message arguments in
chapter 4 of the ToolTalk Programmer’s Guide.
Send the message on its way. Once the message has been sent it’s almost
always a good idea to get rid of it with
destroy-tooltalk-message
.
Send a reply to this message. The second argument can be reply
,
reject
or fail
; the default is reply
. Before
sending a reply, all message arguments whose mode is TT_INOUT
or
TT_OUT
should have been filled in – see
set-tooltalk-message-attribute
.
Returns the indicated ToolTalk message attribute. Attributes are
identified by symbols with the same name (underscores and all) as the
suffix of the ToolTalk ‘tt_message_<attribute>’ function that
extracts the value. String attribute values are copied and enumerated
type values (except disposition) are converted to symbols;
e.g. ‘TT_HANDLER’ is 'TT_HANDLER
, ‘uid’ and ‘gid’
are represented by fixnums (small integers), ‘opnum’ is converted
to a string, and ‘disposition’ is converted to a fixnum. We
convert ‘opnum’ (a C int) to a string (e.g. 123
⇒
"123"
) because there’s no guarantee that opnums will fit within
the range of Emacs Lisp integers.
[TBD] Use the plist
attribute instead of C API user
attribute for user-defined message data. To retrieve the value of a
message property, specify the indicator for argn. For example, to
get the value of a property called rflag
, use
(get-tooltalk-message-attribute msg 'plist 'rflag)
To get the value of a message argument use one of the arg_val
(strings), arg_ival
(integers), or arg_bval
(strings with
embedded nulls), attributes. For example, to get the integer value of
the third argument:
(get-tooltalk-message-attribute msg 'arg_ival 2)
As you can see, argument numbers are zero-based. The type of each
arguments can be retrieved with the arg_type
attribute; however
ToolTalk doesn’t define any semantics for the string value of
arg_type
. Conventionally string
is used for strings and
int
for 32 bit integers. Note that Emacs Lisp stores the lengths
of strings explicitly (unlike C) so treating the value returned by
arg_bval
like a string is fine.
Initialize one ToolTalk message attribute.
Attribute names and values are the same as for
get-tooltalk-message-attribute
. A property list is provided for
user data (instead of the user
message attribute); see
get-tooltalk-message-attribute
.
Callbacks are handled slightly differently than in the C ToolTalk API.
The value of callback should be the name of a function of one
argument. It will be called each time the state of the message changes.
This is usually used to notice when the message’s state has changed to
TT_HANDLED
(or TT_FAILED
), so that reply argument values
can be used.
If one of the argument attributes is specified as arg_val
,
arg_ival
, or arg_bval
, then argn must be the
number of an already created argument. Arguments can be added to a
message with add-tooltalk-message-arg
.
Append one new argument to the message. mode must be one of
TT_IN
, TT_INOUT
, or TT_OUT
, type must be a
string, and value can be a string or an integer. ToolTalk doesn’t
define any semantics for type, so only the participants in the
protocol you’re using need to agree what types mean (if anything).
Conventionally string
is used for strings and int
for 32
bit integers. Arguments can initialized by providing a value or with
set-tooltalk-message-attribute
; the latter is neccessary if you
want to initialize the argument with a string that can contain embedded
nulls (use arg_bval
).
Create a new ToolTalk message. The message’s session attribute is
initialized to the default session. Other attributes can be intialized
with set-tooltalk-message-attribute
.
make-tooltalk-message
is the preferred way to create and
initialize a message.
Apply ‘tt_message_destroy’ to the message. It’s not necessary to destroy messages after they’ve been processed by a message or pattern callback, the Lisp/ToolTalk callback machinery does this for you.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
1.3.1 Example of Receiving Messages | ||
1.3.2 Elisp Interface for Receiving Messages |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here’s a simple example of a handler for a message that tells XEmacs to display a string in the mini-buffer area. The message operation is called ‘emacs-display-string’. Its first (0th) argument is the string to display.
(defun tooltalk-display-string-handler (msg) (message (get-tooltalk-message-attribute msg 'arg_val 0))) (defvar display-string-pattern '(category TT_HANDLE scope TT_SESSION op "emacs-display-string" callback tooltalk-display-string-handler)) (let ((p (make-tooltalk-pattern display-string-pattern))) (register-tooltalk-pattern p))
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Create a ToolTalk pattern and initialize its attributes. The value of attributes must be a list of alternating keyword/values, where keywords are symbols that name valid pattern attributes or lists of valid attributes. For example:
(make-tooltalk-pattern '(category TT_OBSERVE scope TT_SESSION op ("operation1" "operation2") args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
Attribute names are the same as those supported by
add-tooltalk-pattern-attribute
, plus 'args
.
Values must always be strings, integers, or symbols that represent ToolTalk constants or lists of same. When a list of values is provided all of the list elements are added to the attribute. In the example above, messages whose ‘op’ attribute is ‘"operation1"’ or ‘"operation2"’ would match the pattern.
The value of args should be a list of pattern arguments where each pattern argument has the following form:
‘(mode [value [type]])’ or just ‘value’
Where mode is one of TT_IN
, TT_OUT
, or
TT_INOUT
and type is a string. If type isn’t
specified then int
is used if value is a number; otherwise
string
is used. If type is string
then value
is converted to a string (if it isn’t a string already) with
prin1-to-string
. If only a value is specified then mode
defaults to TT_IN
. If mode is TT_OUT
then
value and type don’t need to be specified. You can find out
more about the semantics and uses of ToolTalk pattern arguments in
chapter 3 of the ToolTalk Programmer’s Guide.
XEmacs will begin receiving messages that match this pattern.
XEmacs will stop receiving messages that match this pattern.
Add one value to the indicated pattern attribute. The names of
attributes are the same as the ToolTalk accessors used to set them less
the ‘tooltalk_pattern_’ prefix and the ‘_add’ suffix. For
example, the name of the attribute for the
‘tt_pattern_disposition_add’ attribute is disposition
. The
category
attribute is handled specially, since a pattern can only
be a member of one category (TT_OBSERVE
or TT_HANDLE
).
Callbacks are handled slightly differently than in the C ToolTalk API. The value of callback should be the name of a function of one argument. It will be called each time the pattern matches an incoming message.
Add one fully-specified argument to a ToolTalk pattern. mode must
be one of TT_IN
, TT_INOUT
, or TT_OUT
. type
must be a string. value can be an integer, string or nil
.
If value is an integer then an integer argument
(‘tt_pattern_iarg_add’) is added; otherwise a string argument is
added. At present there’s no way to add a binary data argument.
Create a new ToolTalk pattern and initialize its session attribute to be the default session.
Apply ‘tt_pattern_destroy’ to the pattern. This effectively unregisters the pattern.
Print the message’s attributes and arguments to stream. This is often useful for debugging.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on December 6, 2024 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on December 6, 2024 using texi2html 5.0.