Mercurial > hg > xemacs-beta

comparison src/tooltalk.doc @ 272:c5d627a313b1 r21-0b34

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-0b34
author cvs
date Mon, 13 Aug 2007 10:28:48 +0200
parents 360340f9fd5f
children 8626e4521993
comparison
equal deleted inserted replaced
271:c7b7086b0a39 272:c5d627a313b1
5 to the standard C Tootalk API. Only the message and pattern parts 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 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: 7 if needed. The Lisp interface departs from the C API in a few ways:
8 8
9 - Tooltalk is initialized automatically at emacs startup-time. Messages 9 - Tooltalk is initialized automatically at emacs startup-time. Messages
10 can only be sent other Tooltalk applications connected to the same 10 can only be sent other Tooltalk applications connected to the same
11 X11 server that emacs is running on. 11 X11 server that emacs is running on.
12 12
13 - There are fewer entry points, polymorphic functions with keyword 13 - There are fewer entry points, polymorphic functions with keyword
14 arguments are used instead. 14 arguments are used instead.
15 15
16 - The callback interface is simpler and marginally less functional. 16 - The callback interface is simpler and marginally less functional.
17 A single callback may be associated with a message or a pattern, 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 18 the callback is specified with a Lisp symbol (the symbol should
19 have a function binding). 19 have a function binding).
20 20
21 - The session attribute for messages and patterns is always 21 - The session attribute for messages and patterns is always
22 initialized to the default session. 22 initialized to the default session.
23 23
24 - Anywhere a Tooltalk enum constant, e.g. TT_SESSION, is valid one 24 - Anywhere a Tooltalk enum constant, e.g. TT_SESSION, is valid one
25 can substitute the corresponding symbol, e.g. 'TT_SESSION. This 25 can substitute the corresponding symbol, e.g. 'TT_SESSION. This
26 simplifies building lists that represent messages and patterns. 26 simplifies building lists that represent messages and patterns.
28 28
29 * Example: Receiving Messages 29 * Example: Receiving Messages
30 30
31 Here's a simple example of a handler for a message that tells 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 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 33 operation is called "emacs-display-string", its first (0th) argument
34 is the string to display: 34 is the string to display:
35 35
36 (defun tooltalk-display-string-handler (msg) 36 (defun tooltalk-display-string-handler (msg)
37 (message (get-tooltalk-message-attribute msg 'arg_val 0))) 37 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
38 38
47 47
48 48
49 * Example: Sending Messages 49 * Example: Sending Messages
50 50
51 Here's a simple example that sends a query to another application 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 52 and then displays its reply. Both the query and the reply are
53 stored in the first argument of the message. 53 stored in the first argument of the message.
54 54
55 (defun tooltalk-random-query-handler (msg) 55 (defun tooltalk-random-query-handler (msg)
56 (let ((state (get-tooltalk-message-attribute msg 'state))) 56 (let ((state (get-tooltalk-message-attribute msg 'state)))
57 (cond 57 (cond
59 (message (get-tooltalk-message-attribute msg arg_val 0))) 59 (message (get-tooltalk-message-attribute msg arg_val 0)))
60 ((memq state '(TT_FAILED TT_REJECTED)) 60 ((memq state '(TT_FAILED TT_REJECTED))
61 (message "Random query turns up nothing"))))) 61 (message "Random query turns up nothing")))))
62 62
63 (defvar random-query-message 63 (defvar random-query-message
64 '( class TT_REQUEST 64 '( class TT_REQUEST
65 scope TT_SESSION 65 scope TT_SESSION
66 address TT_PROCEDURE 66 address TT_PROCEDURE
67 op "random-query" 67 op "random-query"
68 args '((TT_INOUT "?" "string")) 68 args '((TT_INOUT "?" "string"))
69 callback tooltalk-random-query-handler)) 69 callback tooltalk-random-query-handler))
70 70
77 ** Sending Messages: 77 ** Sending Messages:
78 78
79 (make-tooltalk-message attributes) 79 (make-tooltalk-message attributes)
80 80
81 Create a tooltalk message and initialize its attributes. 81 Create a tooltalk message and initialize its attributes.
82 The value of attributes must be a list of alternating keyword/values, 82 The value of attributes must be a list of alternating keyword/values,
83 where keywords are symbols that name valid message attributes. 83 where keywords are symbols that name valid message attributes.
84 For example: 84 For example:
85 85
86 (make-tooltalk-message 86 (make-tooltalk-message
87 '(class TT_NOTICE 87 '(class TT_NOTICE
88 scope TT_SESSION 88 scope TT_SESSION
89 address TT_PROCEDURE 89 address TT_PROCEDURE
90 op "do-something" 90 op "do-something"
91 args ("arg1" 12345 (TT_INOUT "arg3" "string")))) 91 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
92 92
93 Values must always be strings, integers, or symbols that 93 Values must always be strings, integers, or symbols that
94 represent Tooltalk constants. Attribute names are the same as 94 represent Tooltalk constants. Attribute names are the same as
95 those supported by set-tooltalk-message-attribute, plus 'args. 95 those supported by set-tooltalk-message-attribute, plus 'args.
96 96
97 The value of args should be a list of message arguments where 97 The value of args should be a list of message arguments where
98 each message argument has the following form: 98 each message argument has the following form:
99 99
100 (mode [value [type]]) or just value 100 (mode [value [type]]) or just value
101 101
102 Where mode is one of TT_IN, TT_OUT, TT_INOUT and type is a string. 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 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 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 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 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 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 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 109 uses of ToolTalk message arguments in chapter 4 of the Tooltalk
110 Programmers Guide. 110 Programmers Guide.
111 111
112 112
113 113
114 (send-tooltalk-message msg) 114 (send-tooltalk-message msg)
115 115
116 Send the message on it's way. Once the message has been sent it's 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. 117 almost always a good idea to get rid of it with destroy-tooltalk-message.
118 118
119 119
120 120
121 (return-tooltalk-message msg &optional mode) 121 (return-tooltalk-message msg &optional mode)
135 String attribute values are copied, enumerated type values (except disposition) 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 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, 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 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 139 string, e.g. 123 => \"123\" because there's no guarantee that opnums will fit
140 within the range of Emacs Lisp integers. 140 within the range of Emacs Lisp integers.
141 141
142 [TBD] Use the 'plist attribute instead of C API 'user attribute 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 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 144 specify the indicator for argn. For example to get the value of a property
145 called 'rflagg, use 145 called 'rflagg, use
146 (get-tooltalk-message-attribute msg 'plist 'rflag) 146 (get-tooltalk-message-attribute msg 'plist 'rflag)
147 147
148 148
149 To get the value of a message argument use one of the 'arg_val (strings), 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. 150 'arg_ival (integers), or 'arg_bval (strings with embedded nulls), attributes.
151 Because integer valued arguments can be larger than Emacs Lisp integers 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 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 153 convert it to an integer with string-to-int. For example to get the integer
154 value of the third argument: 154 value of the third argument:
155 155
156 (string-to-int (get-tooltalk-message-attribute msg 'arg_ival 2)) 156 (string-to-int (get-tooltalk-message-attribute msg 'arg_ival 2))
157 157
158 As you can see, argument numbers are zero based. The type of each arguments 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 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 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 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 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. 163 value returned by 'arg_bval like a string is fine.
164 164
165 165
166 166
167 167
168 (set-tooltalk-message-attribute value msg attribute &optional argn) 168 (set-tooltalk-message-attribute value msg attribute &optional argn)
169 169
170 Initialize one ToolTalk message attribute. 170 Initialize one ToolTalk message attribute.
171 171
172 Attribue names and values are the same as for get-tooltalk-message-attribute. 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 173 A property list is provided for user data (instead of the 'user message
174 attribute), see get-tooltalk-message-attribute. 174 attribute), see get-tooltalk-message-attribute.
175 175
176 Callbacks are handled slightly differently than in the C Tooltalk API. 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. 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 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 179 is usually used to notice when the messages state has
180 changed to TT_HANDLED (or TT_FAILED), so that reply argument values 180 changed to TT_HANDLED (or TT_FAILED), so that reply argument values
181 can be used. 181 can be used.
182 182
183 If one of the argument attributes is specified, 'arg_val, 'arg_ival, or 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. 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. 185 Arguments can be added to a message with add-tooltalk-message-arg.
186 186
187 187
188 188
209 209
210 210
211 (destroy-tooltalk-message msg) 211 (destroy-tooltalk-message msg)
212 212
213 Apply tt_message_destroy to the message. It's not necessary 213 Apply tt_message_destroy to the message. It's not necessary
214 to destroy messages after they've been proccessed by a message or 214 to destroy messages after they've been proccessed by a message or
215 pattern callback, the Lisp/Tooltalk callback machinery does this 215 pattern callback, the Lisp/Tooltalk callback machinery does this
216 for you. 216 for you.
217 217
218 218
219 219
221 221
222 222
223 (make-tooltalk-pattern attributes) 223 (make-tooltalk-pattern attributes)
224 224
225 Create a tooltalk pattern and initialize its attributes. 225 Create a tooltalk pattern and initialize its attributes.
226 The value of attributes must be a list of alternating keyword/values, 226 The value of attributes must be a list of alternating keyword/values,
227 where keywords are symbols that name valid pattern attributes 227 where keywords are symbols that name valid pattern attributes
228 or lists of valid attributes. For example: 228 or lists of valid attributes. For example:
229 229
230 (make-tooltalk-pattern 230 (make-tooltalk-pattern
231 '(category TT_OBSERVE 231 '(category TT_OBSERVE
232 scope TT_SESSION 232 scope TT_SESSION
233 op ("operation1" "operation2") 233 op ("operation1" "operation2")
234 args ("arg1" 12345 (TT_INOUT "arg3" "string")))) 234 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
235 235
236 Attribute names are the same as those supported by 236 Attribute names are the same as those supported by
237 add-tooltalk-pattern-attribute, plus 'args. 237 add-tooltalk-pattern-attribute, plus 'args.
238 238
239 Values must always be strings, integers, or symbols that 239 Values must always be strings, integers, or symbols that
240 represent Tooltalk constants or lists of same. When a list 240 represent Tooltalk constants or lists of same. When a list
241 of values is provided all of the list elements are added to 241 of values is provided all of the list elements are added to
242 the attribute. In the example above, messages whose op 242 the attribute. In the example above, messages whose op
243 attribute is "operation1" or "operation2" would match the pattern. 243 attribute is "operation1" or "operation2" would match the pattern.
244 244
245 The value of args should be a list of pattern arguments where 245 The value of args should be a list of pattern arguments where
246 each pattern argument has the following form: 246 each pattern argument has the following form:
247 247
248 (mode [value [type]]) or just value 248 (mode [value [type]]) or just value
249 249
250 Where mode is one of TT_IN, TT_OUT, TT_INOUT and type is a string. 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 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 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 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 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 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 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 257 uses of ToolTalk pattern arguments in chapter 3 of the Tooltalk
258 Programmers Guide. 258 Programmers Guide.
259 259
260 260
261 261
271 271
272 272
273 (add-tooltalk-pattern-attribute value pat indicator) 273 (add-tooltalk-pattern-attribute value pat indicator)
274 274
275 Add one value to the indicated pattern attribute. The names of attributes 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 276 are the same as the Tooltalk accessors used to set them less the
277 "tooltalk_pattern_" prefix and the "_add" suffix). For example 277 "tooltalk_pattern_" prefix and the "_add" suffix). For example
278 the name of the attribute for tt_pattern_dispostion_add attribute 278 the name of the attribute for tt_pattern_dispostion_add attribute
279 is 'disposition. The 'category attribute is handled specially, 279 is 'disposition. The 'category attribute is handled specially,
280 since a pattern can only be a member of one category (TT_OBSERVE 280 since a pattern can only be a member of one category (TT_OBSERVE
281 or TT_HANDLE. 281 or TT_HANDLE.
282 282
283 Callbacks are handled slightly differently than in the C Tooltalk API. 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. 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. 285 It will be called each time the pattern matches an incoming message.
286 286
287 287
288 288
289 (add-tooltalk-pattern-arg pat mode type value) 289 (add-tooltalk-pattern-arg pat mode type value)
290 290
291 Add one, fully specified, argument to a tooltalk pattern. Mode must 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. 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 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 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. 295 is added. At present there's no way to add a binary data argument.
296 296
297 297
298 (create-tooltalk-pattern) 298 (create-tooltalk-pattern)
321 - At the moment there is almost no support for detecting and 321 - At the moment there is almost no support for detecting and
322 handling ToolTalk errors. This should be added. 322 handling ToolTalk errors. This should be added.
323 323
324 - Message and patterns should support a plist attribute. This 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 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 326 it useful to apply the message and pattern callbacks to
327 both the message and the matching pattern. 327 both the message and the matching pattern.
328 328
329 329
330 330