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