Mercurial > hg > xemacs-beta

comparison src/tooltalk.doc @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ec9a17fef872
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1
2 Emacs Tooltalk API Summary
3
4 The Emacs Lisp interface to Tooltalk is similar, atleast 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", it's 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 it's 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 it's 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 neccessary 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 intialized
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 neccessary
214 to destroy messages after they've been proccessed 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
278 the name of the attribute for tt_pattern_dispostion_add attribute
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