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