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