2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/tooltalk.info
8 @node ToolTalk Support, LDAP Support, X-Windows, top
9 @chapter ToolTalk Support
13 * SXEmacs ToolTalk API Summary::
15 * Receiving Messages::
19 @node SXEmacs ToolTalk API Summary
20 @section SXEmacs ToolTalk API Summary
22 The SXEmacs Lisp interface to ToolTalk is similar, at least in spirit,
23 to the standard C ToolTalk API. Only the message and pattern parts
24 of the API are supported at present; more of the API could be added
25 if needed. The Lisp interface departs from the C API in a few ways:
29 ToolTalk is initialized automatically at SXEmacs startup-time. Messages
30 can only be sent other ToolTalk applications connected to the same X11
31 server that SXEmacs is running on.
34 There are fewer entry points; polymorphic functions with keyword
35 arguments are used instead.
38 The callback interface is simpler and marginally less functional.
39 A single callback may be associated with a message or a pattern;
40 the callback is specified with a Lisp symbol (the symbol should
41 have a function binding).
44 The session attribute for messages and patterns is always
45 initialized to the default session.
48 Anywhere a ToolTalk enum constant, e.g. @samp{TT_SESSION}, is valid, one
49 can substitute the corresponding symbol, e.g. @code{'TT_SESSION}. This
50 simplifies building lists that represent messages and patterns.
54 @node Sending Messages
55 @section Sending Messages
56 @cindex sending ToolTalk messages
57 @cindex ToolTalk message
60 * Example of Sending Messages::
61 * Elisp Interface for Sending Messages::
65 @node Example of Sending Messages
66 @subsection Example of Sending Messages
68 Here's a simple example that sends a query to another application
69 and then displays its reply. Both the query and the reply are
70 stored in the first argument of the message.
73 (defun tooltalk-random-query-handler (msg)
74 (let ((state (get-tooltalk-message-attribute msg 'state)))
76 ((eq state 'TT_HANDLED)
77 (message (get-tooltalk-message-attribute msg arg_val 0)))
78 ((memq state '(TT_FAILED TT_REJECTED))
79 (message "Random query turns up nothing")))))
81 (defvar random-query-message
86 args '((TT_INOUT "?" "string"))
87 callback tooltalk-random-query-handler))
89 (let ((m (make-tooltalk-message random-query-message)))
90 (send-tooltalk-message m))
93 @node Elisp Interface for Sending Messages
94 @subsection Elisp Interface for Sending Messages
96 @defun make-tooltalk-message attributes
97 Create a ToolTalk message and initialize its attributes.
98 The value of @var{attributes} must be a list of alternating keyword/values,
99 where keywords are symbols that name valid message attributes.
103 (make-tooltalk-message
108 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
111 Values must always be strings, integers, or symbols that represent
112 ToolTalk constants. Attribute names are the same as those supported by
113 @code{set-tooltalk-message-attribute}, plus @code{args}.
115 The value of @code{args} should be a list of message arguments where
116 each message argument has the following form:
119 @samp{(mode [value [type]])} or just @samp{value}
122 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
123 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
124 specified then @code{int} is used if @var{value} is a number; otherwise
125 @code{string} is used. If @var{type} is @code{string} then @var{value}
126 is converted to a string (if it isn't a string already) with
127 @code{prin1-to-string}. If only a value is specified then @var{mode}
128 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
129 @var{value} and @var{type} don't need to be specified. You can find out
130 more about the semantics and uses of ToolTalk message arguments in
131 chapter 4 of the @cite{ToolTalk Programmer's Guide}.
135 @defun send-tooltalk-message msg
136 Send the message on its way. Once the message has been sent it's almost
137 always a good idea to get rid of it with
138 @code{destroy-tooltalk-message}.
142 @defun return-tooltalk-message msg &optional mode
143 Send a reply to this message. The second argument can be @code{reply},
144 @code{reject} or @code{fail}; the default is @code{reply}. Before
145 sending a reply, all message arguments whose mode is @code{TT_INOUT} or
146 @code{TT_OUT} should have been filled in---see
147 @code{set-tooltalk-message-attribute}.
151 @defun get-tooltalk-message-attribute msg attribute &optional argn
152 Returns the indicated ToolTalk message attribute. Attributes are
153 identified by symbols with the same name (underscores and all) as the
154 suffix of the ToolTalk @samp{tt_message_<attribute>} function that
155 extracts the value. String attribute values are copied and enumerated
156 type values (except disposition) are converted to symbols;
157 e.g. @samp{TT_HANDLER} is @code{'TT_HANDLER}, @samp{uid} and @samp{gid}
158 are represented by fixnums (small integers), @samp{opnum} is converted
159 to a string, and @samp{disposition} is converted to a fixnum. We
160 convert @samp{opnum} (a C int) to a string (e.g. @code{123} @result{}
161 @code{"123"}) because there's no guarantee that opnums will fit within
162 the range of SXEmacs Lisp integers.
165 [TBD] Use the @code{plist} attribute instead of C API @code{user}
166 attribute for user-defined message data. To retrieve the value of a
167 message property, specify the indicator for @var{argn}. For example, to
168 get the value of a property called @code{rflag}, use
171 (get-tooltalk-message-attribute msg 'plist 'rflag)
174 To get the value of a message argument use one of the @code{arg_val}
175 (strings), @code{arg_ival} (integers), or @code{arg_bval} (strings with
176 embedded nulls), attributes. For example, to get the integer value of
180 (get-tooltalk-message-attribute msg 'arg_ival 2)
183 As you can see, argument numbers are zero-based. The type of each
184 arguments can be retrieved with the @code{arg_type} attribute; however
185 ToolTalk doesn't define any semantics for the string value of
186 @code{arg_type}. Conventionally @code{string} is used for strings and
187 @code{int} for 32 bit integers.
189 Note: SXEmacs Lisp stores the lengths of strings explicitly (unlike C)
190 so treating the value returned by @code{arg_bval} like a string is fine.
194 @defun set-tooltalk-message-attribute value msg attribute &optional argn
195 Initialize one ToolTalk message attribute.
197 Attribute names and values are the same as for
198 @code{get-tooltalk-message-attribute}. A property list is provided for
199 user data (instead of the @code{user} message attribute); see
200 @code{get-tooltalk-message-attribute}.
203 Callbacks are handled slightly differently than in the C ToolTalk API.
204 The value of @var{callback} should be the name of a function of one
205 argument. It will be called each time the state of the message changes.
206 This is usually used to notice when the message's state has changed to
207 @code{TT_HANDLED} (or @code{TT_FAILED}), so that reply argument values
211 If one of the argument attributes is specified as @code{arg_val},
212 @code{arg_ival}, or @code{arg_bval}, then @var{argn} must be the
213 number of an already created argument. Arguments can be added to a
214 message with @code{add-tooltalk-message-arg}.
218 @defun add-tooltalk-message-arg msg mode type &optional value
219 Append one new argument to the message. @var{mode} must be one of
220 @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}, @var{type} must be a
221 string, and @var{value} can be a string or an integer. ToolTalk doesn't
222 define any semantics for @var{type}, so only the participants in the
223 protocol you're using need to agree what types mean (if anything).
224 Conventionally @code{string} is used for strings and @code{int} for 32
227 Arguments can initialized by providing a value or with
228 @code{set-tooltalk-message-attribute}; the latter is necessary if you
229 want to initialize the argument with a string that can contain embedded
230 nulls (use @code{arg_bval}).
234 @defun create-tooltalk-message &optional no-callback
235 Create a new ToolTalk message. The message's session attribute is
236 initialized to the default session. Other attributes can be initialized
237 with @code{set-tooltalk-message-attribute}.
238 @code{make-tooltalk-message} is the preferred way to create and
239 initialize a message.
241 Optional arg @var{no-callback} says don't add a C-level callback at all.
242 Normally don't do that; just don't specify the Lisp callback when
243 calling @code{make-tooltalk-message}.
247 @defun destroy-tooltalk-message msg
248 Apply @samp{tt_message_destroy} to the message. It's not necessary to
249 destroy messages after they've been processed by a message or pattern
250 callback, the Lisp/ToolTalk callback machinery does this for you.
254 @node Receiving Messages
255 @section Receiving Messages
256 @cindex ToolTalk pattern
257 @cindex receiving ToolTalk messages
260 * Example of Receiving Messages::
261 * Elisp Interface for Receiving Messages::
265 @node Example of Receiving Messages
266 @subsection Example of Receiving Messages
268 Here's a simple example of a handler for a message that tells XEmacs to
269 display a string in the mini-buffer area. The message operation is
270 called @samp{emacs-display-string}. Its first (0th) argument is the
274 (defun tooltalk-display-string-handler (msg)
275 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
277 (defvar display-string-pattern
280 op "emacs-display-string"
281 callback tooltalk-display-string-handler))
283 (let ((p (make-tooltalk-pattern display-string-pattern)))
284 (register-tooltalk-pattern p))
288 @node Elisp Interface for Receiving Messages
289 @subsection Elisp Interface for Receiving Messages
291 @defun make-tooltalk-pattern attributes
292 Create a ToolTalk pattern and initialize its attributes.
293 The value of attributes must be a list of alternating keyword/values,
294 where keywords are symbols that name valid pattern attributes
295 or lists of valid attributes. For example:
298 (make-tooltalk-pattern
299 '(category TT_OBSERVE
301 op ("operation1" "operation2")
302 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
305 Attribute names are the same as those supported by
306 @code{add-tooltalk-pattern-attribute}, plus @code{'args}.
308 Values must always be strings, integers, or symbols that represent
309 ToolTalk constants or lists of same. When a list of values is provided
310 all of the list elements are added to the attribute. In the example
311 above, messages whose @samp{op} attribute is @samp{"operation1"} or
312 @samp{"operation2"} would match the pattern.
314 The value of @var{args} should be a list of pattern arguments where each
315 pattern argument has the following form:
318 @samp{(mode [value [type]])} or just @samp{value}
321 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
322 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
323 specified then @code{int} is used if @var{value} is a number; otherwise
324 @code{string} is used. If @var{type} is @code{string} then @var{value}
325 is converted to a string (if it isn't a string already) with
326 @code{prin1-to-string}. If only a value is specified then @var{mode}
327 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
328 @var{value} and @var{type} don't need to be specified. You can find out
329 more about the semantics and uses of ToolTalk pattern arguments in
330 chapter 3 of the @cite{ToolTalk Programmer's Guide}.
334 @defun register-tooltalk-pattern pattern
335 SXEmacs will begin receiving messages that match this pattern.
338 @defun unregister-tooltalk-pattern pattern
339 SXEmacs will stop receiving messages that match this pattern.
342 @defun add-tooltalk-pattern-attribute value pattern indicator
343 Add one value to the indicated pattern attribute. The names of
344 attributes are the same as the ToolTalk accessors used to set them less
345 the @samp{tooltalk_pattern_} prefix and the @samp{_add} suffix. For
346 example, the name of the attribute for the
347 @samp{tt_pattern_disposition_add} attribute is @code{disposition}. The
348 @code{category} attribute is handled specially, since a pattern can only
349 be a member of one category (@code{TT_OBSERVE} or @code{TT_HANDLE}).
352 Callbacks are handled slightly differently than in the C ToolTalk API.
353 The value of @var{callback} should be the name of a function of one
354 argument. It will be called each time the pattern matches an incoming
358 @defun add-tooltalk-pattern-arg pattern mode vtype &optional value
359 Add one fully-specified argument to a ToolTalk pattern. @var{mode} must
360 be one of @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}. @var{vtype}
361 must be a string. @var{value} can be an integer, string or @code{nil}.
362 If @var{value} is an integer then an integer argument
363 (@samp{tt_pattern_iarg_add}) is added; otherwise a string argument is
364 added. At present there's no way to add a binary data argument.
368 @defun create-tooltalk-pattern
369 Create a new ToolTalk pattern and initialize its session attribute to
370 be the default session.
373 @defun destroy-tooltalk-pattern pattern
374 Apply @samp{tt_pattern_destroy} to the pattern. This effectively
375 unregisters the pattern.
378 @defun describe-tooltalk-message msg &optional stream
379 Print the message's attributes and arguments to @var{stream}. This is
380 often useful for debugging.