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