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