|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
428
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/tooltalk.info
|
|
|
6 @node ToolTalk Support, LDAP Support, X-Windows, top
|
|
|
7 @chapter ToolTalk Support
|
|
|
8 @cindex ToolTalk
|
|
|
9
|
|
|
10 @menu
|
|
|
11 * XEmacs ToolTalk API Summary::
|
|
|
12 * Sending Messages::
|
|
|
13 * Receiving Messages::
|
|
|
14 @end menu
|
|
|
15
|
|
|
16 @node XEmacs ToolTalk API Summary
|
|
|
17 @section XEmacs ToolTalk API Summary
|
|
|
18
|
|
|
19 The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
|
|
|
20 to the standard C ToolTalk API. Only the message and pattern parts
|
|
|
21 of the API are supported at present; more of the API could be added
|
|
|
22 if needed. The Lisp interface departs from the C API in a few ways:
|
|
|
23
|
|
|
24 @itemize @bullet
|
|
|
25 @item
|
|
|
26 ToolTalk is initialized automatically at XEmacs startup-time. Messages
|
|
|
27 can only be sent other ToolTalk applications connected to the same X11
|
|
|
28 server that XEmacs is running on.
|
|
|
29
|
|
|
30 @item
|
|
|
31 There are fewer entry points; polymorphic functions with keyword
|
|
|
32 arguments are used instead.
|
|
|
33
|
|
|
34 @item
|
|
|
35 The callback interface is simpler and marginally less functional.
|
|
|
36 A single callback may be associated with a message or a pattern;
|
|
|
37 the callback is specified with a Lisp symbol (the symbol should
|
|
|
38 have a function binding).
|
|
|
39
|
|
|
40 @item
|
|
444
|
41 The session attribute for messages and patterns is always
|
|
428
|
42 initialized to the default session.
|
|
|
43
|
|
|
44 @item
|
|
|
45 Anywhere a ToolTalk enum constant, e.g. @samp{TT_SESSION}, is valid, one
|
|
|
46 can substitute the corresponding symbol, e.g. @code{'TT_SESSION}. This
|
|
|
47 simplifies building lists that represent messages and patterns.
|
|
|
48 @end itemize
|
|
|
49
|
|
|
50 @node Sending Messages
|
|
|
51 @section Sending Messages
|
|
|
52 @cindex sending ToolTalk messages
|
|
|
53 @cindex ToolTalk message
|
|
|
54
|
|
|
55 @menu
|
|
|
56 * Example of Sending Messages::
|
|
|
57 * Elisp Interface for Sending Messages::
|
|
|
58 @end menu
|
|
|
59
|
|
|
60 @node Example of Sending Messages
|
|
|
61 @subsection Example of Sending Messages
|
|
|
62
|
|
|
63 Here's a simple example that sends a query to another application
|
|
|
64 and then displays its reply. Both the query and the reply are
|
|
|
65 stored in the first argument of the message.
|
|
|
66
|
|
|
67 @example
|
|
|
68 (defun tooltalk-random-query-handler (msg)
|
|
|
69 (let ((state (get-tooltalk-message-attribute msg 'state)))
|
|
|
70 (cond
|
|
|
71 ((eq state 'TT_HANDLED)
|
|
|
72 (message (get-tooltalk-message-attribute msg arg_val 0)))
|
|
|
73 ((memq state '(TT_FAILED TT_REJECTED))
|
|
|
74 (message "Random query turns up nothing")))))
|
|
|
75
|
|
|
76 (defvar random-query-message
|
|
444
|
77 '( class TT_REQUEST
|
|
|
78 scope TT_SESSION
|
|
428
|
79 address TT_PROCEDURE
|
|
|
80 op "random-query"
|
|
|
81 args '((TT_INOUT "?" "string"))
|
|
|
82 callback tooltalk-random-query-handler))
|
|
|
83
|
|
|
84 (let ((m (make-tooltalk-message random-query-message)))
|
|
|
85 (send-tooltalk-message m))
|
|
|
86 @end example
|
|
|
87
|
|
|
88 @node Elisp Interface for Sending Messages
|
|
|
89 @subsection Elisp Interface for Sending Messages
|
|
|
90
|
|
|
91 @defun make-tooltalk-message attributes
|
|
|
92 Create a ToolTalk message and initialize its attributes.
|
|
444
|
93 The value of @var{attributes} must be a list of alternating keyword/values,
|
|
|
94 where keywords are symbols that name valid message attributes.
|
|
428
|
95 For example:
|
|
|
96
|
|
|
97 @example
|
|
444
|
98 (make-tooltalk-message
|
|
428
|
99 '(class TT_NOTICE
|
|
|
100 scope TT_SESSION
|
|
|
101 address TT_PROCEDURE
|
|
|
102 op "do-something"
|
|
|
103 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
|
|
|
104 @end example
|
|
|
105
|
|
|
106 Values must always be strings, integers, or symbols that represent
|
|
|
107 ToolTalk constants. Attribute names are the same as those supported by
|
|
|
108 @code{set-tooltalk-message-attribute}, plus @code{args}.
|
|
|
109
|
|
|
110 The value of @code{args} should be a list of message arguments where
|
|
|
111 each message argument has the following form:
|
|
|
112
|
|
|
113 @quotation
|
|
|
114 @samp{(mode [value [type]])} or just @samp{value}
|
|
|
115 @end quotation
|
|
|
116
|
|
|
117 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
|
|
|
118 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
|
|
|
119 specified then @code{int} is used if @var{value} is a number; otherwise
|
|
|
120 @code{string} is used. If @var{type} is @code{string} then @var{value}
|
|
|
121 is converted to a string (if it isn't a string already) with
|
|
|
122 @code{prin1-to-string}. If only a value is specified then @var{mode}
|
|
|
123 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
|
|
|
124 @var{value} and @var{type} don't need to be specified. You can find out
|
|
|
125 more about the semantics and uses of ToolTalk message arguments in
|
|
|
126 chapter 4 of the @cite{ToolTalk Programmer's Guide}.
|
|
|
127 @refill
|
|
|
128 @end defun
|
|
|
129
|
|
|
130 @defun send-tooltalk-message msg
|
|
|
131 Send the message on its way. Once the message has been sent it's almost
|
|
|
132 always a good idea to get rid of it with
|
|
|
133 @code{destroy-tooltalk-message}.
|
|
|
134 @refill
|
|
|
135 @end defun
|
|
|
136
|
|
|
137 @defun return-tooltalk-message msg &optional mode
|
|
|
138 Send a reply to this message. The second argument can be @code{reply},
|
|
|
139 @code{reject} or @code{fail}; the default is @code{reply}. Before
|
|
|
140 sending a reply, all message arguments whose mode is @code{TT_INOUT} or
|
|
440
|
141 @code{TT_OUT} should have been filled in---see
|
|
428
|
142 @code{set-tooltalk-message-attribute}.
|
|
|
143 @refill
|
|
|
144 @end defun
|
|
|
145
|
|
|
146 @defun get-tooltalk-message-attribute msg attribute &optional argn
|
|
|
147 Returns the indicated ToolTalk message attribute. Attributes are
|
|
|
148 identified by symbols with the same name (underscores and all) as the
|
|
|
149 suffix of the ToolTalk @samp{tt_message_<attribute>} function that
|
|
|
150 extracts the value. String attribute values are copied and enumerated
|
|
|
151 type values (except disposition) are converted to symbols;
|
|
|
152 e.g. @samp{TT_HANDLER} is @code{'TT_HANDLER}, @samp{uid} and @samp{gid}
|
|
|
153 are represented by fixnums (small integers), @samp{opnum} is converted
|
|
|
154 to a string, and @samp{disposition} is converted to a fixnum. We
|
|
|
155 convert @samp{opnum} (a C int) to a string (e.g. @code{123} @result{}
|
|
|
156 @code{"123"}) because there's no guarantee that opnums will fit within
|
|
|
157 the range of XEmacs Lisp integers.
|
|
|
158 @refill
|
|
|
159
|
|
|
160 [TBD] Use the @code{plist} attribute instead of C API @code{user}
|
|
|
161 attribute for user-defined message data. To retrieve the value of a
|
|
|
162 message property, specify the indicator for @var{argn}. For example, to
|
|
|
163 get the value of a property called @code{rflag}, use
|
|
|
164
|
|
|
165 @example
|
|
|
166 (get-tooltalk-message-attribute msg 'plist 'rflag)
|
|
|
167 @end example
|
|
|
168
|
|
|
169 To get the value of a message argument use one of the @code{arg_val}
|
|
|
170 (strings), @code{arg_ival} (integers), or @code{arg_bval} (strings with
|
|
|
171 embedded nulls), attributes. For example, to get the integer value of
|
|
|
172 the third argument:
|
|
|
173
|
|
|
174 @example
|
|
|
175 (get-tooltalk-message-attribute msg 'arg_ival 2)
|
|
|
176 @end example
|
|
|
177
|
|
|
178 As you can see, argument numbers are zero-based. The type of each
|
|
|
179 arguments can be retrieved with the @code{arg_type} attribute; however
|
|
|
180 ToolTalk doesn't define any semantics for the string value of
|
|
|
181 @code{arg_type}. Conventionally @code{string} is used for strings and
|
|
|
182 @code{int} for 32 bit integers. Note that XEmacs Lisp stores the lengths
|
|
|
183 of strings explicitly (unlike C) so treating the value returned by
|
|
|
184 @code{arg_bval} like a string is fine.
|
|
|
185 @refill
|
|
|
186 @end defun
|
|
|
187
|
|
|
188 @defun set-tooltalk-message-attribute value msg attribute &optional argn
|
|
|
189 Initialize one ToolTalk message attribute.
|
|
|
190
|
|
|
191 Attribute names and values are the same as for
|
|
|
192 @code{get-tooltalk-message-attribute}. A property list is provided for
|
|
|
193 user data (instead of the @code{user} message attribute); see
|
|
|
194 @code{get-tooltalk-message-attribute}.
|
|
|
195 @refill
|
|
|
196
|
|
|
197 Callbacks are handled slightly differently than in the C ToolTalk API.
|
|
|
198 The value of @var{callback} should be the name of a function of one
|
|
|
199 argument. It will be called each time the state of the message changes.
|
|
|
200 This is usually used to notice when the message's state has changed to
|
|
|
201 @code{TT_HANDLED} (or @code{TT_FAILED}), so that reply argument values
|
|
|
202 can be used.
|
|
|
203 @refill
|
|
|
204
|
|
|
205 If one of the argument attributes is specified as @code{arg_val},
|
|
|
206 @code{arg_ival}, or @code{arg_bval}, then @var{argn} must be the
|
|
|
207 number of an already created argument. Arguments can be added to a
|
|
|
208 message with @code{add-tooltalk-message-arg}.
|
|
|
209 @refill
|
|
|
210 @end defun
|
|
|
211
|
|
|
212 @defun add-tooltalk-message-arg msg mode type &optional value
|
|
|
213 Append one new argument to the message. @var{mode} must be one of
|
|
|
214 @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}, @var{type} must be a
|
|
|
215 string, and @var{value} can be a string or an integer. ToolTalk doesn't
|
|
|
216 define any semantics for @var{type}, so only the participants in the
|
|
|
217 protocol you're using need to agree what types mean (if anything).
|
|
|
218 Conventionally @code{string} is used for strings and @code{int} for 32
|
|
|
219 bit integers. Arguments can initialized by providing a value or with
|
|
|
220 @code{set-tooltalk-message-attribute}; the latter is necessary if you
|
|
|
221 want to initialize the argument with a string that can contain embedded
|
|
|
222 nulls (use @code{arg_bval}).
|
|
|
223 @refill
|
|
|
224 @end defun
|
|
|
225
|
|
444
|
226 @defun create-tooltalk-message &optional no-callback
|
|
428
|
227 Create a new ToolTalk message. The message's session attribute is
|
|
|
228 initialized to the default session. Other attributes can be initialized
|
|
|
229 with @code{set-tooltalk-message-attribute}.
|
|
|
230 @code{make-tooltalk-message} is the preferred way to create and
|
|
|
231 initialize a message.
|
|
444
|
232
|
|
|
233 Optional arg @var{no-callback} says don't add a C-level callback at all.
|
|
|
234 Normally don't do that; just don't specify the Lisp callback when
|
|
|
235 calling @code{make-tooltalk-message}.
|
|
428
|
236 @refill
|
|
|
237 @end defun
|
|
|
238
|
|
|
239 @defun destroy-tooltalk-message msg
|
|
|
240 Apply @samp{tt_message_destroy} to the message. It's not necessary to
|
|
|
241 destroy messages after they've been processed by a message or pattern
|
|
|
242 callback, the Lisp/ToolTalk callback machinery does this for you.
|
|
|
243 @end defun
|
|
|
244
|
|
|
245 @node Receiving Messages
|
|
|
246 @section Receiving Messages
|
|
|
247 @cindex ToolTalk pattern
|
|
|
248 @cindex receiving ToolTalk messages
|
|
|
249
|
|
|
250 @menu
|
|
|
251 * Example of Receiving Messages::
|
|
|
252 * Elisp Interface for Receiving Messages::
|
|
|
253 @end menu
|
|
|
254
|
|
|
255 @node Example of Receiving Messages
|
|
|
256 @subsection Example of Receiving Messages
|
|
|
257
|
|
|
258 Here's a simple example of a handler for a message that tells XEmacs to
|
|
|
259 display a string in the mini-buffer area. The message operation is
|
|
|
260 called @samp{emacs-display-string}. Its first (0th) argument is the
|
|
|
261 string to display.
|
|
|
262
|
|
|
263 @example
|
|
|
264 (defun tooltalk-display-string-handler (msg)
|
|
|
265 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
|
|
|
266
|
|
|
267 (defvar display-string-pattern
|
|
|
268 '(category TT_HANDLE
|
|
|
269 scope TT_SESSION
|
|
|
270 op "emacs-display-string"
|
|
|
271 callback tooltalk-display-string-handler))
|
|
|
272
|
|
|
273 (let ((p (make-tooltalk-pattern display-string-pattern)))
|
|
|
274 (register-tooltalk-pattern p))
|
|
|
275 @end example
|
|
|
276
|
|
|
277 @node Elisp Interface for Receiving Messages
|
|
|
278 @subsection Elisp Interface for Receiving Messages
|
|
|
279
|
|
|
280 @defun make-tooltalk-pattern attributes
|
|
|
281 Create a ToolTalk pattern and initialize its attributes.
|
|
444
|
282 The value of attributes must be a list of alternating keyword/values,
|
|
428
|
283 where keywords are symbols that name valid pattern attributes
|
|
|
284 or lists of valid attributes. For example:
|
|
|
285
|
|
|
286 @example
|
|
444
|
287 (make-tooltalk-pattern
|
|
428
|
288 '(category TT_OBSERVE
|
|
|
289 scope TT_SESSION
|
|
|
290 op ("operation1" "operation2")
|
|
|
291 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
|
|
|
292 @end example
|
|
|
293
|
|
444
|
294 Attribute names are the same as those supported by
|
|
428
|
295 @code{add-tooltalk-pattern-attribute}, plus @code{'args}.
|
|
|
296
|
|
|
297 Values must always be strings, integers, or symbols that represent
|
|
|
298 ToolTalk constants or lists of same. When a list of values is provided
|
|
|
299 all of the list elements are added to the attribute. In the example
|
|
|
300 above, messages whose @samp{op} attribute is @samp{"operation1"} or
|
|
|
301 @samp{"operation2"} would match the pattern.
|
|
|
302
|
|
|
303 The value of @var{args} should be a list of pattern arguments where each
|
|
|
304 pattern argument has the following form:
|
|
|
305
|
|
|
306 @quotation
|
|
|
307 @samp{(mode [value [type]])} or just @samp{value}
|
|
|
308 @end quotation
|
|
|
309
|
|
|
310 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
|
|
|
311 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
|
|
|
312 specified then @code{int} is used if @var{value} is a number; otherwise
|
|
|
313 @code{string} is used. If @var{type} is @code{string} then @var{value}
|
|
|
314 is converted to a string (if it isn't a string already) with
|
|
|
315 @code{prin1-to-string}. If only a value is specified then @var{mode}
|
|
|
316 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
|
|
|
317 @var{value} and @var{type} don't need to be specified. You can find out
|
|
|
318 more about the semantics and uses of ToolTalk pattern arguments in
|
|
|
319 chapter 3 of the @cite{ToolTalk Programmer's Guide}.
|
|
|
320 @refill
|
|
|
321 @end defun
|
|
|
322
|
|
444
|
323 @defun register-tooltalk-pattern pattern
|
|
428
|
324 XEmacs will begin receiving messages that match this pattern.
|
|
|
325 @end defun
|
|
|
326
|
|
444
|
327 @defun unregister-tooltalk-pattern pattern
|
|
428
|
328 XEmacs will stop receiving messages that match this pattern.
|
|
|
329 @end defun
|
|
|
330
|
|
444
|
331 @defun add-tooltalk-pattern-attribute value pattern indicator
|
|
428
|
332 Add one value to the indicated pattern attribute. The names of
|
|
|
333 attributes are the same as the ToolTalk accessors used to set them less
|
|
|
334 the @samp{tooltalk_pattern_} prefix and the @samp{_add} suffix. For
|
|
|
335 example, the name of the attribute for the
|
|
|
336 @samp{tt_pattern_disposition_add} attribute is @code{disposition}. The
|
|
|
337 @code{category} attribute is handled specially, since a pattern can only
|
|
|
338 be a member of one category (@code{TT_OBSERVE} or @code{TT_HANDLE}).
|
|
|
339 @refill
|
|
|
340
|
|
|
341 Callbacks are handled slightly differently than in the C ToolTalk API.
|
|
|
342 The value of @var{callback} should be the name of a function of one
|
|
|
343 argument. It will be called each time the pattern matches an incoming
|
|
|
344 message.
|
|
|
345 @end defun
|
|
|
346
|
|
444
|
347 @defun add-tooltalk-pattern-arg pattern mode vtype &optional value
|
|
428
|
348 Add one fully-specified argument to a ToolTalk pattern. @var{mode} must
|
|
444
|
349 be one of @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}. @var{vtype}
|
|
428
|
350 must be a string. @var{value} can be an integer, string or @code{nil}.
|
|
|
351 If @var{value} is an integer then an integer argument
|
|
|
352 (@samp{tt_pattern_iarg_add}) is added; otherwise a string argument is
|
|
|
353 added. At present there's no way to add a binary data argument.
|
|
|
354 @refill
|
|
|
355 @end defun
|
|
|
356
|
|
|
357 @defun create-tooltalk-pattern
|
|
|
358 Create a new ToolTalk pattern and initialize its session attribute to
|
|
|
359 be the default session.
|
|
|
360 @end defun
|
|
|
361
|
|
444
|
362 @defun destroy-tooltalk-pattern pattern
|
|
428
|
363 Apply @samp{tt_pattern_destroy} to the pattern. This effectively
|
|
|
364 unregisters the pattern.
|
|
|
365 @end defun
|
|
|
366
|
|
|
367 @defun describe-tooltalk-message msg &optional stream
|
|
|
368 Print the message's attributes and arguments to @var{stream}. This is
|
|
|
369 often useful for debugging.
|
|
|
370 @end defun
|
