|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/tooltalk.info
|
|
298
|
6 @node ToolTalk Support, LDAP Support, X-Windows, top
|
|
0
|
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
|
|
|
41 The session attribute for messages and patterns is always
|
|
|
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
|
|
|
77 '( class TT_REQUEST
|
|
|
78 scope TT_SESSION
|
|
|
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.
|
|
|
93 The value of @var{attributes} must be a list of alternating keyword/values,
|
|
|
94 where keywords are symbols that name valid message attributes.
|
|
|
95 For example:
|
|
|
96
|
|
|
97 @example
|
|
|
98 (make-tooltalk-message
|
|
|
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
|
|
|
141 @code{TT_OUT} should have been filled in -- see
|
|
|
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
|
|
108
|
220 @code{set-tooltalk-message-attribute}; the latter is necessary if you
|
|
0
|
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
|
|
|
226 @defun create-tooltalk-message
|
|
|
227 Create a new ToolTalk message. The message's session attribute is
|
|
373
|
228 initialized to the default session. Other attributes can be initialized
|
|
0
|
229 with @code{set-tooltalk-message-attribute}.
|
|
|
230 @code{make-tooltalk-message} is the preferred way to create and
|
|
|
231 initialize a message.
|
|
|
232 @refill
|
|
|
233 @end defun
|
|
|
234
|
|
|
235 @defun destroy-tooltalk-message msg
|
|
|
236 Apply @samp{tt_message_destroy} to the message. It's not necessary to
|
|
|
237 destroy messages after they've been processed by a message or pattern
|
|
|
238 callback, the Lisp/ToolTalk callback machinery does this for you.
|
|
|
239 @end defun
|
|
|
240
|
|
|
241 @node Receiving Messages
|
|
|
242 @section Receiving Messages
|
|
|
243 @cindex ToolTalk pattern
|
|
|
244 @cindex receiving ToolTalk messages
|
|
|
245
|
|
|
246 @menu
|
|
|
247 * Example of Receiving Messages::
|
|
|
248 * Elisp Interface for Receiving Messages::
|
|
|
249 @end menu
|
|
|
250
|
|
|
251 @node Example of Receiving Messages
|
|
|
252 @subsection Example of Receiving Messages
|
|
|
253
|
|
|
254 Here's a simple example of a handler for a message that tells XEmacs to
|
|
|
255 display a string in the mini-buffer area. The message operation is
|
|
|
256 called @samp{emacs-display-string}. Its first (0th) argument is the
|
|
|
257 string to display.
|
|
|
258
|
|
|
259 @example
|
|
|
260 (defun tooltalk-display-string-handler (msg)
|
|
|
261 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
|
|
|
262
|
|
|
263 (defvar display-string-pattern
|
|
|
264 '(category TT_HANDLE
|
|
|
265 scope TT_SESSION
|
|
|
266 op "emacs-display-string"
|
|
|
267 callback tooltalk-display-string-handler))
|
|
|
268
|
|
|
269 (let ((p (make-tooltalk-pattern display-string-pattern)))
|
|
|
270 (register-tooltalk-pattern p))
|
|
|
271 @end example
|
|
|
272
|
|
|
273 @node Elisp Interface for Receiving Messages
|
|
|
274 @subsection Elisp Interface for Receiving Messages
|
|
|
275
|
|
|
276 @defun make-tooltalk-pattern attributes
|
|
|
277 Create a ToolTalk pattern and initialize its attributes.
|
|
|
278 The value of attributes must be a list of alternating keyword/values,
|
|
|
279 where keywords are symbols that name valid pattern attributes
|
|
|
280 or lists of valid attributes. For example:
|
|
|
281
|
|
|
282 @example
|
|
|
283 (make-tooltalk-pattern
|
|
|
284 '(category TT_OBSERVE
|
|
|
285 scope TT_SESSION
|
|
|
286 op ("operation1" "operation2")
|
|
|
287 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
|
|
|
288 @end example
|
|
|
289
|
|
|
290 Attribute names are the same as those supported by
|
|
|
291 @code{add-tooltalk-pattern-attribute}, plus @code{'args}.
|
|
|
292
|
|
|
293 Values must always be strings, integers, or symbols that represent
|
|
|
294 ToolTalk constants or lists of same. When a list of values is provided
|
|
|
295 all of the list elements are added to the attribute. In the example
|
|
|
296 above, messages whose @samp{op} attribute is @samp{"operation1"} or
|
|
|
297 @samp{"operation2"} would match the pattern.
|
|
|
298
|
|
|
299 The value of @var{args} should be a list of pattern arguments where each
|
|
|
300 pattern argument has the following form:
|
|
|
301
|
|
|
302 @quotation
|
|
|
303 @samp{(mode [value [type]])} or just @samp{value}
|
|
|
304 @end quotation
|
|
|
305
|
|
|
306 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
|
|
|
307 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
|
|
|
308 specified then @code{int} is used if @var{value} is a number; otherwise
|
|
|
309 @code{string} is used. If @var{type} is @code{string} then @var{value}
|
|
|
310 is converted to a string (if it isn't a string already) with
|
|
|
311 @code{prin1-to-string}. If only a value is specified then @var{mode}
|
|
|
312 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
|
|
|
313 @var{value} and @var{type} don't need to be specified. You can find out
|
|
|
314 more about the semantics and uses of ToolTalk pattern arguments in
|
|
|
315 chapter 3 of the @cite{ToolTalk Programmer's Guide}.
|
|
|
316 @refill
|
|
|
317 @end defun
|
|
|
318
|
|
|
319 @defun register-tooltalk-pattern pat
|
|
|
320 XEmacs will begin receiving messages that match this pattern.
|
|
|
321 @end defun
|
|
|
322
|
|
|
323 @defun unregister-tooltalk-pattern pat
|
|
|
324 XEmacs will stop receiving messages that match this pattern.
|
|
|
325 @end defun
|
|
|
326
|
|
|
327 @defun add-tooltalk-pattern-attribute value pat indicator
|
|
|
328 Add one value to the indicated pattern attribute. The names of
|
|
|
329 attributes are the same as the ToolTalk accessors used to set them less
|
|
|
330 the @samp{tooltalk_pattern_} prefix and the @samp{_add} suffix. For
|
|
|
331 example, the name of the attribute for the
|
|
|
332 @samp{tt_pattern_disposition_add} attribute is @code{disposition}. The
|
|
|
333 @code{category} attribute is handled specially, since a pattern can only
|
|
|
334 be a member of one category (@code{TT_OBSERVE} or @code{TT_HANDLE}).
|
|
|
335 @refill
|
|
|
336
|
|
|
337 Callbacks are handled slightly differently than in the C ToolTalk API.
|
|
|
338 The value of @var{callback} should be the name of a function of one
|
|
|
339 argument. It will be called each time the pattern matches an incoming
|
|
|
340 message.
|
|
|
341 @end defun
|
|
|
342
|
|
|
343 @defun add-tooltalk-pattern-arg pat mode type value
|
|
|
344 Add one fully-specified argument to a ToolTalk pattern. @var{mode} must
|
|
|
345 be one of @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}. @var{type}
|
|
|
346 must be a string. @var{value} can be an integer, string or @code{nil}.
|
|
|
347 If @var{value} is an integer then an integer argument
|
|
|
348 (@samp{tt_pattern_iarg_add}) is added; otherwise a string argument is
|
|
|
349 added. At present there's no way to add a binary data argument.
|
|
|
350 @refill
|
|
|
351 @end defun
|
|
|
352
|
|
|
353 @defun create-tooltalk-pattern
|
|
|
354 Create a new ToolTalk pattern and initialize its session attribute to
|
|
|
355 be the default session.
|
|
|
356 @end defun
|
|
|
357
|
|
|
358 @defun destroy-tooltalk-pattern pat
|
|
|
359 Apply @samp{tt_pattern_destroy} to the pattern. This effectively
|
|
|
360 unregisters the pattern.
|
|
|
361 @end defun
|
|
|
362
|
|
|
363 @defun describe-tooltalk-message msg &optional stream
|
|
|
364 Print the message's attributes and arguments to @var{stream}. This is
|
|
|
365 often useful for debugging.
|
|
|
366 @end defun
|
