Mercurial > hg > xemacs-beta
annotate man/lispref/tooltalk.texi @ 5888:a85efdabe237
Call #'read-passwd when requesting a password from the user, tls.c
src/ChangeLog addition:
2015-04-09 Aidan Kehoe <kehoea@parhasard.net>
* tls.c (nss_pk11_password):
* tls.c (gnutls_pk11_password):
* tls.c (openssl_password):
* tls.c (syms_of_tls):
Our read-a-password function is #'read-passwd, not
#'read-password, correct that in this file.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 09 Apr 2015 14:54:37 +0100 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
6 @node ToolTalk Support, LDAP Support, X-Windows, Top |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
16 @node XEmacs ToolTalk API Summary, Sending Messages, ToolTalk Support, ToolTalk Support |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
50 @node Sending Messages, Receiving Messages, XEmacs ToolTalk API Summary, ToolTalk Support |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
60 @node Example of Sending Messages, Elisp Interface for Sending Messages, Sending Messages, Sending Messages |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
88 @node Elisp Interface for Sending Messages, , Example of Sending Messages, Sending Messages |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
245 @node Receiving Messages, , Sending Messages, ToolTalk Support |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
255 @node Example of Receiving Messages, Elisp Interface for Receiving Messages, Receiving Messages, Receiving Messages |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
277 @node Elisp Interface for Receiving Messages, , Example of Receiving Messages, Receiving Messages |
| 428 | 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 |