Mercurial > hg > xemacs-beta
annotate src/tooltalk.doc @ 5887:6eca500211f4
Prototype for X509_check_host() has changed, detect this in configure.ac
ChangeLog addition:
2015-04-09 Aidan Kehoe <kehoea@parhasard.net>
* configure.ac:
If X509_check_host() is available, check the number of arguments
it takes. Don't use it if it takes any number of arguments other
than five. Also don't use it if <openssl/x509v3.h> does not
declare it, since if that is so there is no portable way to tell
how many arguments it should take, and so we would end up smashing
the stack.
* configure: Regenerate.
src/ChangeLog addition:
2015-04-09 Aidan Kehoe <kehoea@parhasard.net>
* tls.c:
#include <openssl/x509v3.h> for its prototype for
X509_check_host().
* tls.c (tls_open):
Pass the new fifth argument to X509_check_host().
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 09 Apr 2015 14:27:02 +0100 |
| 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 |