Protocol-A.texi 280 KB
 David Byers committed Jan 13, 1996 1 \input texinfo @c -*-texinfo-*-  David Byers committed Jan 07, 1999 2 3 4 @c @c FIXME: Explain how the garb works with nice and keep-commented @c  Per Cederqvist committed Nov 20, 1999 5 @c $Id: Protocol-A.texi,v 1.96 1999/11/20 20:06:30 ceder Exp$  David Byers committed Jan 13, 1996 6 7 8 9 10 11 12 @c %**start of header @setfilename protocol-a.info @settitle LysKOM Protocol A @setchapternewpage odd @c %**end of header @iftex @parindent 0pt  David Byers committed Jul 27, 1996 13 @font@tensltt=cmsltt10  David Byers committed Jun 14, 1996 14 15 16 17 18 @begin tex \global\def\rett#1{{\let\t\sltt\tt #1}} \global\def\sltt#1{{\fam\ttfam\tensltt\let\t\rett #1}} \global\let\t\sltt @end tex  David Byers committed Jan 13, 1996 19 20 21 @end iftex @ifinfo  Per Cederqvist committed Jul 23, 1999 22 23 This is revision 10.2 of the LysKOM Protocol A specification. It specifies version 10 of the protocol.  David Byers committed Jan 13, 1996 24   David Byers committed Dec 30, 1998 25 Copyright @copyright{} 1995-1999 Lysator ACS.  David Byers committed Jan 13, 1996 26 27 28 29 30 31  Permission is granted to make and distribute verbatim copies of this specification provided the copyright notice and this permission notice are preserved on all copies. @end ifinfo  Per Cederqvist committed Aug 02, 1998 32 33 34 35 36 @dircategory LysKOM @direntry * Protocol A: (protocol-a). The LysKOM Protocol A specification. @end direntry  David Byers committed Jan 13, 1996 37 38 39 40 @titlepage @sp 10 @title{LysKOM Protocol A} @sp 2  Per Cederqvist committed Apr 04, 1999 41 @subtitle{Protocol version 10}  David Byers committed Jan 13, 1996 42 43 44 45 46 @sp 2 @author by the LysKOM Developers @page @vskip 0pt plus 1filll  David Byers committed Dec 30, 1998 47 Copyright @copyright{} 1995-1999 Lysator ACS  David Byers committed Jan 13, 1996 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63  Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies. Modified versions of this document may be redistributed with the added condition that all modifications not cleared with the LysKOM development group are clearly marked and that the entire modified work be redistributed under the same conditions as the original. Permission is granted to copy and distribute translations of this manual into another language under the same conditions as for modified versions. @end titlepage @ifinfo  Per Cederqvist committed May 23, 1999 64 @node Top  Per Cederqvist committed Apr 05, 1999 65 @top LysKOM Protocol A  Per Cederqvist committed Apr 04, 1999 66 67  This document specifies version 10 of LysKOM Protocol A.  Per Cederqvist committed Jul 23, 1999 68 This is revision 10.2 of the specification.  David Byers committed Jan 13, 1996 69 70  @menu  Per Cederqvist committed Apr 04, 1999 71 72 73 74 75 76 77 78 79 80 81 82 * Overview:: * Introduction:: * Data Types:: * Protocol Requests:: * Asynchronous Messages:: * Error Codes:: * LysKOM Content Types:: * The User Area:: * Writing Clients:: * Importing and Exporting E-Mail:: * Type Index:: * Request Index::  David Byers committed Jan 13, 1996 83 84 85 @end menu @end ifinfo  Per Cederqvist committed May 23, 1999 86 @node Overview  David Byers committed Jan 13, 1996 87 88 89 @chapter Overview LysKOM is a conferencing system@footnote{Or in modern terms, enabling  David Byers committed Sep 13, 1997 90 91 92 93 94 95 technology for Computer-Supported Cooperative Work (CSCW).}. Similar systems were QZ-KOM and PortaCOM@footnote{Also known as PottaKOM'' and BortaKOM.''}. The LysKOM system is copyrighted by Lysator Academic Computing Society and distributed under conditions of the GNU Public License. LysKOM and its documentation is provided as is'' without warranty of any kind.  David Byers committed Jan 13, 1996 96   Per Cederqvist committed Jul 10, 1999 97 This document specifies version 10 of protocol A used between a LysKOM  David Byers committed Sep 13, 1997 98 99 client and a LysKOM server. Anything described here as unspecified'' is liable to change in future protocol versions.  David Byers committed Jan 13, 1996 100 101  This specification is the work of several people. The main contributors have  David Byers committed Sep 13, 1997 102 been  David Byers committed May 23, 1999 103 104 Per Cederqvist @email{ceder@@lysator.liu.se}, David Byers @email{byers@@lysator.liu.se},  David Byers committed Jan 13, 1996 105 106 107 108 109 110 @ifinfo Pär @end ifinfo @iftex P@"ar @end iftex  David Byers committed May 23, 1999 111 112 113 114 Emanuelsson @email{pell@@lysator.liu.se}, Thomas Bellman @email{bellman@@lysator.liu.se}, Lars Aronsson @email{aronsson@@lysator.liu.se}, Linus Tolke @email{linus@@lysator.liu.se} and  David Byers committed Jan 13, 1996 115 116 117 118 119 120 @ifinfo Kent Engström @end ifinfo @iftex Kent Eng@-str@"om@penalty-10000 @end iftex  David Byers committed May 23, 1999 121 @email{kent@@lysator.liu.se}.  David Byers committed Jan 13, 1996 122   David Byers committed May 23, 1999 123 124 The LysKOM developers can be reached by email to @email{lyskom@@lysator.liu.se}.  David Byers committed Jan 13, 1996 125   Per Cederqvist committed Apr 04, 1999 126 127 128 129 @menu * Document Revision History:: * Protocol Version History:: * Notation::  David Byers committed Jan 13, 1996 130 131 @end menu  Per Cederqvist committed May 23, 1999 132 @node Document Revision History  David Byers committed Jan 13, 1996 133 134 135 @section Document Revision History @table @asis  David Byers committed Sep 13, 1997 136   Per Cederqvist committed Jul 23, 1999 137 138 139 140 @item 10.2: 1999-07-23 Some typos and other minor errors were fixed. Distributed with lyskomd 2.0.2.  Per Cederqvist committed Jul 11, 1999 141 @item 10.1: 1999-07-12  David Byers committed Jul 02, 1999 142 Call @code{sub-comment} was incorrectly marked obsolete. This has been  Per Cederqvist committed Jul 11, 1999 143 144 145 146 147 corrected. Regexps are case sensitive. The Info-Type enumeration was introduced in the description of the protocol. (Previous versions of the protocol had broken definitions of add-recipient, async-new-recipient and async-sub-recipient.) Distributed with lyskomd 2.0.1.  David Byers committed Jul 02, 1999 148   Per Cederqvist committed Jun 24, 1999 149 @item 10.0: 1999-06-27  Per Cederqvist committed Apr 04, 1999 150 151 The specification was translated to English and converted to Texinfo by David Byers. Protocol version 10. Distributed with lyskomd 2.0.0.  Per Cederqvist committed Jul 10, 1999 152 153 154 Note: this revision incorrectly marked the @code{sub-comment} call as obsolete, and stated that regexp lookup was case insensitive. Both statements were wrong, and has since been fixed.  Per Cederqvist committed Apr 04, 1999 155 156  @item 9.0: 1996-08-04  Per Cederqvist committed May 23, 1999 157 Protocol version 9. Distributed with lyskomd 1.9.0.  David Byers committed Jun 14, 1996 158   David Byers committed Jan 13, 1996 159 @item 8.0: 1995-11-10  Per Cederqvist committed Apr 04, 1999 160 Protocol version 8. Distributed with lyskomd 1.8.0.  David Byers committed Jan 13, 1996 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184  @item 7.1: 1995-01-08. Protocol and document revision history were added by Per Cederqvist. Outline mode was used to make the document more manageable. This version was distributed with lyskomd 1.7.1. @item 7.0: 1994-12-31. The first specification with a version number. All calls that had been added since 1991-06-25 were documented. Pell and Per Cederqvist did the deed. This version was distributed with lyskomd 1.7.0. @item 1993-05-19. Linus Tolke wrote comments for some calls that were without comments. @item 1992-07-06. Linus Tolke converted the document to ISO 8859-1. @item 1991-08-12. Per Cederqvist started using version control for documentation. @item 1991-06-25. Lars Aronsson documented the protocol that was in use at the time. @end table  Per Cederqvist committed May 23, 1999 185 @node Protocol Version History  Per Cederqvist committed Apr 04, 1999 186 187 188 @section Protocol Version History @subsection Protocol version 10 (first implemented in lyskomd 2.0.0)  David Byers committed Jan 13, 1996 189   David Byers committed Sep 13, 1997 190 @table @asis  Per Cederqvist committed May 23, 1999 191 192 193 194 195 196  @item Error codes The error codes are now documented. Several error codes were changed to more sane values while documenting the new behaviour.  David Byers committed Sep 13, 1997 197 @item New Server Calls  Per Cederqvist committed May 23, 1999 198 199 200  These new calls have status Recommended.  David Byers committed Sep 13, 1997 201 202 203 204 205 206 207 208 209 210 211 212 213 @itemize @bullet @item 85=get-collate-table @item 86=create-text @item 87=create-anonymous-text @item 88=create-conf @item 89=create-person @item 90=get-text-stat @item 91=get-conf-stat @item 92=modify-text-info @item 93=modify-conf-info @item 94=get-info @item 95=modify-system-info @item 96=query-predefined-aux-items  David Byers committed Jun 14, 1998 214 215 216 217 @item 98=query-read-texts @item 99=get-membership @item 100=add-member @item 101=get-members  Per Cederqvist committed Apr 18, 1999 218 219 220 @item 102=set-membership-type @item 103=local-to-global @item 104=map-created-texts  Per Cederqvist committed May 23, 1999 221 222 223 224 225 226 227 @item 106=set-pers-flags @end itemize These new calls have status Experimental. @itemize @bullet @item 97=set-expire  David Byers committed Jan 07, 1999 228 @item 105=set-keep-commented  David Byers committed Sep 13, 1997 229 230 @end itemize  Per Cederqvist committed May 23, 1999 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 @item Name changes @multitable {59=create-anonymous-text} {59=create-anonymous-text-old} @item Old name @tab New name @item 5=create-person @tab 5=create-person-old @item 9=query-read-texts @tab 9=query-read-texts-old @item 10=create-conf @tab 10=create-conf-old @item 13=get-conf-stat-old @tab 13=get-conf-stat-older @item 14=add-member @tab 14=add-member-old @item 26=get-text-stat @tab 26=get-text-stat-old @item 28=create-text @tab 28=create-text-old @item 36=get-info @tab 36=get-info-old @item 46=get-membership @tab 46=get-membership-old @item 48=get-members @tab 48=get-members-old @item 50=get-conf-stat @tab 50=get-conf-stat-old @item 59=create-anonymous-text @tab 59=create-anonymous-text-old @end multitable @item Status change The following calls have change status from Experimental to Recommended.  David Byers committed Sep 13, 1997 253 @itemize @bullet  Per Cederqvist committed May 23, 1999 254 255 256 257 258 @item 58=get-last-text @item 77=set-last-read @item 78=get-uconf-stat @end itemize  Kent Engström committed Jul 07, 1999 259 The following calls have changed status from Recommended or  Per Cederqvist committed May 23, 1999 260 261 262 263 264 265 266 267 268 Experimental to Obsolete. @itemize @bullet @item 5=create-person-old @item 9=query-read-texts-old @item 10=create-conf-old @item 14=add-member-old @item 26=get-text-stat-old @item 28=create-text-old  David Byers committed Sep 13, 1997 269 @item 36=get-info-old  David Byers committed Jun 14, 1998 270 @item 46=get-membership-old  Per Cederqvist committed May 23, 1999 271 @item 47=get-created-texts  David Byers committed Jun 14, 1998 272 @item 48=get-members-old  Per Cederqvist committed May 23, 1999 273 274 @item 50=get-conf-stat-old @item 59=create-anonymous-text-old  David Byers committed Sep 13, 1997 275 276 @end itemize  Per Cederqvist committed May 23, 1999 277 @item New and Modified Structures  David Byers committed Sep 13, 1997 278 @itemize @bullet  Per Cederqvist committed Aug 29, 1998 279 @item Aux-Item  Per Cederqvist committed Aug 29, 1998 280 @item Aux-Item-Input  David Byers committed Sep 13, 1997 281 282 @item Conference @item Info  David Byers committed Jun 14, 1998 283 284 285 @item Member @item Membership @item Membership-Type  Per Cederqvist committed Aug 29, 1998 286 287 @item Misc-Info @item Text-Stat  David Byers committed Sep 13, 1997 288 289 @end itemize  Per Cederqvist committed May 23, 1999 290 291 292 293 294 295 @item Renamed Asynchronous Messages A @samp{async-} prefix has been added to the name of all asynchronous messages. In addition, 0=new-text has been renamed to 0=async-new-text-old, and it is now considered obsolete. Clients should use 80=accept-async to listen to 15=async-new-text instead.  David Byers committed Sep 13, 1997 296 297 @item New Asynchronous Messages @itemize @bullet  Per Cederqvist committed May 23, 1999 298 299 300 301 302 @item 14=async-deleted-text @item 15=async-new-text @item 16=async-new-recipient @item 17=async-sub-recipient @item 18=async-new-membership  David Byers committed Sep 13, 1997 303 @end itemize  David Byers committed Dec 29, 1998 304 305 306  @item Notes @itemize @bullet  Kent Engström committed Jul 07, 1999 307 @item Since protocol version 9 setting a priority of zero for a  David Byers committed Dec 29, 1998 308 309 310 conference was supposed to indicate passive membership in a conference. It was largely up to the client to implement this. True passive memberships have been introduced in this protocol version through the  Kent Engström committed Jul 07, 1999 311 Membership-type extension to the Membership type. In order to maintain  David Byers committed Dec 29, 1998 312 313 314 315 316 compatibility with clients that interpret priority 0 as passive membership, the old calls @pxref{add-member-old} and @pxref{get-membership-old} perform magic, translating between priorities and membership types. The magic is documented with each call. @end itemize  David Byers committed Sep 13, 1997 317 318 @end table  David Byers committed Dec 29, 1998 319   Per Cederqvist committed Apr 04, 1999 320 @subsection Protocol version 9 (first implemented in lyskomd 1.9.0)  David Byers committed Jun 14, 1996 321 322  @table @asis  Per Cederqvist committed Apr 04, 1999 323 324 325 326 327 328 @item New functionality @itemize @bullet @item The server shall now reply with error @code{not-implemented} when a client attempts to use an unimplemented call. This feature requires that the client uses newline as call terminator. @end itemize  Per Cederqvist committed Jul 07, 1998 329 @item Added Commands  David Byers committed Jun 14, 1996 330 @itemize @bullet  David Byers committed Sep 13, 1997 331 332 333 334 335 336 @item 79=set-info: Can change server information. @item 80=accept-async: Can select asynchronous messages to receive. @item 81=query-async: Can query which messages are being send. @item 82=user-active @item 83=who-is-on-dynamic @item 84=get-static-session-info  David Byers committed Jun 14, 1996 337 @end itemize  Per Cederqvist committed Apr 04, 1999 338 339 340 341 342 343 344 @item Changed names @itemize @bullet @item @code{change-conference} was previously called @code{pepsi}. The name was changed, but not the functionality. @end itemize @item Status change @itemize @bullet  David Byers committed May 23, 1999 345 346 @item 63=@code{who-is-on-ident} is now considered obsolete. @item 64=@code{get-session-info-ident} is now considered obsolete.  Per Cederqvist committed Apr 04, 1999 347 @end itemize  David Byers committed Jun 14, 1996 348 349 @end table  Per Cederqvist committed Apr 04, 1999 350 @subsection Protocol version 8 (first implemented in lyskomd 1.8.0)  David Byers committed Jan 13, 1996 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385  @table @asis @item Added Functionality @itemize @bullet @item 30=add-recipient: Can change recpt to cc_recpt and vice versa. @item 21=set-conf-type: Accepts Conf-Type and Extended-Conf-Type. @item 10=create-conf: Accepts Conf-Type and Extended-Conf-Type. @end itemize @item New Commands @itemize @bullet @item 77=set-last-read @item 78=get-uconf-stat @end itemize @end table @subsection Protocol version 7 (first implemented in lyskomd 1.7.0) @table @asis @item Added Functionality @itemize @bullet @item 53=send-message: Recipient can be a conference or a person. @end itemize @item New Commands @itemize @bullet @item 74=re-z-lookup @item  Per Cederqvist committed Apr 04, 1999 386 75=get-version-info  David Byers committed Jan 13, 1996 387 @item  Per Cederqvist committed Apr 04, 1999 388 76=lookup-z-name  David Byers committed Jan 13, 1996 389 390 391 392 393 @end itemize @item Other @itemize @bullet @item  Per Cederqvist committed Jul 07, 1998 394 The asynchronous message 1=i-am-off has been removed  David Byers committed Jan 13, 1996 395 396 397 398 399 400 401 402 403 @end itemize @end table @subsection Protocol Version 6 (first implemented in lyskomd 1.4.0) @table @asis @item New Calls @itemize @bullet @item  Per Cederqvist committed Apr 04, 1999 404 67=lookup-person  David Byers committed Jan 13, 1996 405 @item  Per Cederqvist committed Apr 04, 1999 406 68=lookup-conf  David Byers committed Jan 13, 1996 407 @item  Per Cederqvist committed Apr 04, 1999 408 69=set-client-version  David Byers committed Jan 13, 1996 409 @item  Per Cederqvist committed Apr 04, 1999 410 70=get-client-name  David Byers committed Jan 13, 1996 411 @item  Per Cederqvist committed Apr 04, 1999 412 71=get-client-version  David Byers committed Jan 13, 1996 413 @item  Per Cederqvist committed Apr 04, 1999 414 72=mark-text  David Byers committed Jan 13, 1996 415 @item  Per Cederqvist committed Apr 04, 1999 416 73=unmark-text  David Byers committed Jan 13, 1996 417 418 419 420 421 422 423 424 425 426 @end itemize @end table @subsection Protocol Version 5 (first implemented in lyskomd 1.3.0) @table @asis @item New Calls @itemize @bullet @item  Per Cederqvist committed Apr 04, 1999 427 65=re-lookup-person  David Byers committed Jan 13, 1996 428 @item  Per Cederqvist committed Apr 04, 1999 429 66=re-lookup-conf  David Byers committed Jan 13, 1996 430 431 432 433 434 435 436 437 438 439 440 @end itemize @end table @subsection Protocol Version 4 (first implemented in lyskomd 1.1.1) @table @asis @item New Calls @itemize @bullet @item 62=login @item  Per Cederqvist committed Apr 04, 1999 441 63=who-is-on-ident  David Byers committed Jan 13, 1996 442 @item  Per Cederqvist committed Apr 04, 1999 443 64=get-session-info-ident  David Byers committed Jan 13, 1996 444 445 446 447 448 449 450 451 452 @end itemize @end table @subsection Protocol Version 3 (first implemented in lyskomd 1.1.0) @table @asis @item New Calls @itemize @bullet @item  Per Cederqvist committed Apr 04, 1999 453 61=find-previous-text-no  David Byers committed Jan 13, 1996 454 @item  Per Cederqvist committed Apr 04, 1999 455 60=find-next-text-no  David Byers committed Jan 13, 1996 456 @item  Per Cederqvist committed Apr 04, 1999 457 59=create-anonymous-text  David Byers committed Jan 13, 1996 458 @item  Per Cederqvist committed Apr 04, 1999 459 58=get-last-text  David Byers committed Jan 13, 1996 460 461 462 463 464 465 466 467 468 @end itemize @end table @subsection Protocol Version 2 (first implemented in lyskomd 0.30.0) @table @asis @item New Calls @itemize @bullet @item  Per Cederqvist committed Apr 04, 1999 469 57=set-user-area  David Byers committed Jan 13, 1996 470 471 472 473 474 475 476 477 478 479 480 @end itemize @end table @subsection Protocol Version 1 (first implemented in lyskomd 0.29.2) @table @asis @item New Calls All calls from 0--56. @end table  Per Cederqvist committed May 23, 1999 481 @node Notation  David Byers committed Jan 13, 1996 482 483 @section Notation  David Byers committed Sep 13, 1997 484 This specification uses a BNF-like grammar to describe the protocol and  Per Cederqvist committed Apr 04, 1999 485 its data elements.  David Byers committed Jan 13, 1996 486   David Byers committed Sep 13, 1997 487 Data fields have been given names that start with a lower-case letter.  Per Cederqvist committed Aug 29, 1998 488 489 490 491 492 493 494 495 496 497 498  Fundamental data types have names in all-caps (such as @code{INT32} and @code{ARRAY}). Derived data types have names that start with an upper-case letter. (If the type contains more than one word, all words start with an upper-case letter, like this: @code{Text-Stat}.) The operator @code{::=} defines the name to its left. Comments start with @code{!} (exclamation mark) and alternatives are separated by a @code{|} (vertical bar.) A @code{;} (semicolon)  David Byers committed Sep 13, 1997 499 500 501 terminates statements in the grammar. In some specifications there are literal strings. There is to be no whitespace before or after literal strings unless there is whitespace in the literal itself.  David Byers committed Jan 13, 1996 502 503   Per Cederqvist committed May 23, 1999 504 @node Introduction  David Byers committed Jan 13, 1996 505 506 507 508 509 510 @chapter Introduction This chapter introduces the concepts used in LysKOM, such as articles, conferences and sessions. @menu  Per Cederqvist committed Apr 04, 1999 511 512 513 514 515 516 517 * Articles:: * Conferences:: * The Misc-Info List:: * The Aux-Item List:: * Security:: * Membership and Reading:: * Client-Server Dialog::  David Byers committed Jan 13, 1996 518 519 520 @end menu  Per Cederqvist committed May 23, 1999 521 @node Articles  David Byers committed Jan 13, 1996 522 523 524 525 @section Articles An article is represented as a value of the type @code{Text-Stat} and a string containing the article contents. An article will usually have one  David Byers committed Sep 13, 1997 526 527 528 529 or more recipients and may be a comment or footnote to other articles. Each article is kept in the database until it is older than the @code{nice} value of each of its recipients and it is not marked by any user.  David Byers committed Jan 13, 1996 530   David Byers committed Sep 13, 1997 531 532 533 534 535 Currently there is a structure called a @code{Misc-Info-List} associated with the @code{Text-Stat}. This list contains information about recipients, senders, comments and footnotes. In the future the information contained in the @code{Misc-Info-List} will be integrated into the @code{Text-Stat}.  David Byers committed Jan 13, 1996 536 537 538  Every article has at least one number, the global article number. Global numbers are assigned in ascending order to new articles, and are never  David Byers committed Sep 13, 1997 539 reused. If an article has recipients it will also have a local number  Per Cederqvist committed Jul 07, 1998 540 for each recipient. Local numbers are used in some data structures to  Per Cederqvist committed Aug 08, 1998 541 provide more compact storage and to provide an ordering of articles for  David Byers committed Sep 13, 1997 542 543 544 a particular recipient. Local numbers are assigned in ascending order and are never reused for a particular recipient, though different recipients will have articles with the same local numbers.  David Byers committed Jan 13, 1996 545   David Byers committed Sep 13, 1997 546 Occasionally it is necessary to map between local and global numbers.  Per Cederqvist committed Aug 03, 1998 547 The server call @code{local-to-global} does this.  David Byers committed Jan 13, 1996 548 549 550   Per Cederqvist committed May 23, 1999 551 @node Conferences  David Byers committed Jan 13, 1996 552 553 @section Conferences  David Byers committed Sep 13, 1997 554 555 556 557 Conferences hold articles. They are represented in the protocol as a data type called @code{Conference}. Each conference has a @emph{creator}, the person who created the conference, and a @emph{supervisor}, a conference whose members can modify the conference.  David Byers committed Dec 26, 1998 558 If the supervisor is a person, the members of that person's mailbox  David Byers committed Sep 13, 1997 559 560 561 562 563 are supervisors, which in most cases is only that person. We have also introduced a type called @code{UConference} (pronounced micro-conf-stat) which holds a subset of the information contained in the full @code{Conference} type. Use the @code{UConference} type whenever possible since it places a much smaller load on the LysKOM server.  David Byers committed Jan 13, 1996 564 565  Each conference has a type, which is essentially a collection of boolean  Per Cederqvist committed Jul 07, 1998 566 flags. Currently the flags @code{rd-prot}, @code{letterbox},  Kent Engström committed Jul 07, 1999 567 568 @code{secret}, @code{original}, @code{allow-anonymous} and @code{forbid-secret} are defined.  David Byers committed Jan 13, 1996 569 570 571 572 573 574 575  @table @code @item rd-prot The conference is protected from reading by non-members. Persons become members by having one of the existing members or supervisors add him or her to the conference. This restriction is enforced by the server. @item original  David Byers committed Sep 13, 1997 576 577 578 579 Conferences of this type are intended for original articles only. Comments are to be redirected to the super-conference instead. This restriction is currently not enforced by the server; clients must implement this functionality.  David Byers committed Jan 13, 1996 580 @item letterbox  David Byers committed Sep 13, 1997 581 Conferences of this type are connected to persons. Letters to a person  David Byers committed Dec 26, 1998 582 are sent to the mailbox and the name of the mailbox is synchronized  David Byers committed Sep 13, 1997 583 584 with the person name. It is currently not possible to explicitly set or clear this flag on a conference.  David Byers committed Jan 13, 1996 585 586 @item secret Conferences of this type are secret. The server will not divulge any  Kent Engström committed Jul 07, 1999 587 information about the existence of the conference to persons who are not  David Byers committed Dec 26, 1998 588 members or supervisors of the conference. If a mailbox is made secret,  David Byers committed Jan 13, 1996 589 590 that person cannot log in using the person name, but must specify a person number instead.  David Byers committed Sep 13, 1997 591 592 593 @item allow-anonymous Conferences of this type accept anonymous articles. Other conferences will reject anonymous articles.  David Byers committed Dec 26, 1998 594 595 596 @item forbid-secret Conferences of this type do not allow secret members. If a conference is changed to this type, preexisting secret members remain secret.  David Byers committed Jan 13, 1996 597 598 599 600 @end table  Per Cederqvist committed Apr 04, 1999 601 602 603 604 @menu * Persons and Sessions:: @end menu  Per Cederqvist committed May 23, 1999 605 @node Persons and Sessions  David Byers committed Jan 13, 1996 606 607 608 @subsection Persons and Sessions Persons are represented in the protocol by values of the type  David Byers committed Sep 13, 1997 609 610 611 612 @code{Person}. Associated with persons are statistics, a set of personal flags and a set of privileges (@pxref{Security}.) Persons are also associated with a conference that has the same number as the person and the @code{letterbox} bit set.  David Byers committed Jan 13, 1996 613 614  Connections to the server are represented as values of the type  David Byers committed Sep 13, 1997 615 616 617 618 619 620 @code{Static-Session-Info}, @code{Session-Info-Ident} or @code{Session-Info}. Sessions have session number that are unique for each session in the lifetime of the server execution. A single user can have several sessions running at once. The session is not released until the network connection is closed; a user can log in and out repeatedly in a single session.  David Byers committed Jan 13, 1996 621 622   Per Cederqvist committed May 23, 1999 623 @node The Misc-Info List  David Byers committed Jan 13, 1996 624 625 @section The Misc-Info List  David Byers committed Sep 13, 1997 626 627 The @code{Misc-Info} list contains tagged data. The fields are sent in groups pertaining to a particular type of information: information about  Per Cederqvist committed Oct 06, 1998 628 629 recipient; carbon copy recipient; blank carbon copy recipient; comment to; footnote to; comment in  David Byers committed Sep 13, 1997 630 631 632 and footnote in. The information groups may be sent in any order and there may be any number of groups. Within each group the elements are always sent in the order listed below.  David Byers committed Jan 13, 1996 633   David Byers committed Jun 14, 1996 634 @subsection Recipient  David Byers committed Jan 13, 1996 635 636 637  @table @code @item recpt  David Byers committed Sep 13, 1997 638 639 Starts a recipient group. It contains the conference number of a recipient of the article.  David Byers committed Jan 13, 1996 640 @item loc-no  David Byers committed Sep 13, 1997 641 642 643 Always present within a recipient group. It contains the local text number of the article in the conference specified by the preceding @code{recpt} field.  David Byers committed Jan 13, 1996 644 @item rec-time  David Byers committed Sep 13, 1997 645 646 647 If the recipient is a person, this element is added by the server when the recipient marks the article as read. It contains the time when the text was read.  David Byers committed Jan 13, 1996 648 @item sent-by  David Byers committed Sep 13, 1997 649 650 651 Present when the recipient was added by a person other than the author (after the article was created.) It contains the person number of the person who added the recipient.  David Byers committed Jan 13, 1996 652 @item sent-at  David Byers committed Sep 13, 1997 653 654 Present when the recipient was added after the article was created. It contains the time when the recipient was added.  David Byers committed Jan 13, 1996 655 656 657 @end table  David Byers committed Jun 14, 1996 658 @subsection Carbon Copy (CC) Recipient  David Byers committed Jan 13, 1996 659   David Byers committed Sep 13, 1997 660 661 662 663 The carbon-copy recipient group is identical to the recipient group above. The difference is how new comments to an article with a recipient or carbon-copy recipient are treated. A comment to an article is sent to all recipients, but not to carbon-copy recipients of the original  Per Cederqvist committed Jul 07, 1998 664 article. This difference is enforced by the clients.  David Byers committed Jan 13, 1996 665 666 667  @table @code @item cc-recpt  David Byers committed Sep 13, 1997 668 669 Starts a carbon-copy recipient group. It contains the conference number of a carbon-copy recipient of the article.  David Byers committed Jan 13, 1996 670 @item loc-no  David Byers committed Sep 13, 1997 671 672 673 Always present in a CC recipient group. It contains the local text number of the article in the conference specified by the most recent @code{cc-recpt} field.  David Byers committed Jan 13, 1996 674 @item rec-time  David Byers committed Sep 13, 1997 675 Present after the CC recipient has read the article. It contains the  Per Cederqvist committed Oct 06, 1998 676 677 time when the article was read. Since only persons can read articles this will only be seen if the CC recipient is a person.  David Byers committed Jan 13, 1996 678 679 680 @item sent-by Present when a CC recipient was added by a person other than the author after the article had been created. It contains the person number of the  Per Cederqvist committed Oct 06, 1998 681 person who added the CC recipient.  David Byers committed Jan 13, 1996 682 683 684 685 686 687 @item sent-at Present when a CC recipient was added after the article had been created. It is the time when the CC recipient was added. @end table  Per Cederqvist committed Oct 06, 1998 688 689 690 691 692 @subsection Blank Carbon Copy (BCC) Recipient The blank carbon-copy recipient group is identical to the carbon-copy recipient group above. The difference is the visibility of the information. A carbon-copy recipient group is visible to anyone that is  Kent Engström committed Jul 07, 1999 693 allowed to fetch both the text status of the involved text and the  Per Cederqvist committed Oct 06, 1998 694 conference status of the involved conference. (That is, as long as the  Kent Engström committed Jul 07, 1999 695 conference isn't secret everybody is allowed to see the carbon-copy  Per Cederqvist committed Oct 06, 1998 696 697 698 699 700 701 recipient group.) A BCC recipient group is only visible to members and supervisors of the recipient. This is enforced by the server. This type of group was introduced in protocol version 10. When  Kent Engström committed Jul 07, 1999 702 703 704 old-style calls such as get-text-stat-old (@pxref{get-text-stat-old}) are used this will be converted to a CC recipient group by the server for the benefit of clients that don't understand this group.  Per Cederqvist committed Oct 06, 1998 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727  @table @code @item bcc-recpt Starts a blank carbon-copy recipient group. It contains the conference number of a blank carbon-copy recipient of the article. @item loc-no Always present in a BCC recipient group. It contains the local text number of the article in the conference specified by the most recent @code{bcc-recpt} field. @item rec-time Present after the BCC recipient has read the article. It contains the time when the article was read. Since only persons can read articles this will only be seen if the BCC recipient is a person. @item sent-by Present when a BCC recipient was added by a person other than the author after the article had been created. It contains the person number of the person who added the BCC recipient. @item sent-at Present when a BCC recipient was added after the article had been created. It is the time when the BCC recipient was added. @end table  David Byers committed Jun 14, 1996 728 @subsection Comment To  David Byers committed Jan 13, 1996 729 730 731 732 733 734 735 736 737 738  @table @code @item comm-to Always present when the article is a comment to another article. @item sent-by Present when the article was added as a comment by a person other than the author, after the article had been created. It contains the person number of the person who added the article as a comment. @item sent-at Present when the article was added as a comment after the article had  Kent Engström committed Jul 07, 1999 739 been created. It contains the time when it was added as a comment.  David Byers committed Jan 13, 1996 740 741 742 @end table  David Byers committed Jun 14, 1996 743 @subsection Footnote To  David Byers committed Jan 13, 1996 744 745  @table @code  David Byers committed Sep 13, 1997 746 @item footn-to  David Byers committed Jan 13, 1996 747 748 749 Always present when the article is a footnote to another article. @item sent-at Present when the article was added as a footnote after the article had  Kent Engström committed Jul 07, 1999 750 been created. It contains the time when it was added as a footnote.  David Byers committed Jan 13, 1996 751 752 753 @end table  David Byers committed Jun 14, 1996 754 @subsection Comment in  David Byers committed Jan 13, 1996 755 756 757 758 759 760 761 762  @table @code @item comm-in Present when there are comments to this article. It contains the article number which is a comment to this article. @end table  David Byers committed Jun 14, 1996 763 @subsection Footnote in  David Byers committed Jan 13, 1996 764 765  @table @code  David Byers committed Sep 13, 1997 766 @item footn-in  David Byers committed Jan 13, 1996 767 768 769 770 771 Present when there are footnotes to this article. It contains the article number which is a footnote to this article. @end table  Per Cederqvist committed May 23, 1999 772 @node The Aux-Item List  Per Cederqvist committed Apr 04, 1999 773 @section The Aux-Item List  David Byers committed Sep 13, 1997 774 775 776 777 778  The aux-item list is used as a generic extension mechanism in the LysKOM server and in protocol A. @menu  Per Cederqvist committed Apr 04, 1999 779 780 781 782 783 * About Aux-Items:: * Predefined Aux-Item Types:: * Client-Specific Aux-Item Types:: * Experimental Aux-Item Types:: * Defining New Aux-Item Types::  David Byers committed Sep 13, 1997 784 785 @end menu  Per Cederqvist committed May 23, 1999 786 @node About Aux-Items  Per Cederqvist committed Apr 04, 1999 787 @subsection About Aux-Items  David Byers committed Sep 13, 1997 788 789 790 791  Aux-items were introduced in protocol version 10 as a mechanism for extending the conference, text and server information structures without changing the protocol. Persons were excluded since nobody could figure  David Byers committed Dec 26, 1998 792 out a case where setting an aux-item on the mailbox wasn't as good as  David Byers committed Sep 13, 1997 793 794 795 796 797 798 799 800 801 setting it on the person (another reason was that I was fed up writing aux-item code by the time they were working on texts and conferences.) The exact structure of an aux item is specified elsewhere (@pxref{LysKOM Data Types}). The important fields here are the aux-no, tag and data fields. The aux-no field is used to identify an item. The aux-no together with a text or conference number uniquely identifies a particular aux item.  Per Cederqvist committed Aug 08, 1998 802 Items are numbered from one and up within each item list. Once assigned,  David Byers committed Sep 13, 1997 803 804 805 806 the aux-no for an item is never changed. New items are guaranteed to be assigned numbers that have never been used before within a particular list.  Per Cederqvist committed Aug 08, 1998 807 The tag field identifies the type of aux item. It is used by the server  David Byers committed Sep 13, 1997 808 809 810 811 812 813 814 815 816 817 and by clients to figure out how to interpret the data field, and by the server to decide if the item needs special treatment. The data field is a simple string. The meaning of the string is determined by the tag field, but since it is a string, clients that have no understanding of the contents can successfully parse the item anyway (in contrast to items in the misc-info list.)  Per Cederqvist committed May 23, 1999 818 @node Predefined Aux-Item Types  Per Cederqvist committed Apr 04, 1999 819 @subsection Predefined Aux-Item Types  David Byers committed Sep 13, 1997 820   David Byers committed May 12, 1999 821 822 823 Predefined Aux-Item types are part of Protocol A, and clients should support all of them. As with other parts of the protocol, changes to these definitions will be made backwards-compatible, if possible.  David Byers committed Sep 13, 1997 824   David Byers committed May 12, 1999 825 826 827 Creation and deletion of items with a predefined type can cause arbitrarily complex and wonderous behavior in the server. Furthermore, the server may place constraints on the items with regard to content,  Kent Engström committed Jul 07, 1999 828 flags, who can create them, to what objects they can be attached and  David Byers committed May 12, 1999 829 830 so forth. The server may also silently enforce specific values for any field of an item, regardless of what the client requests.  David Byers committed Sep 13, 1997 831   Per Cederqvist committed Aug 08, 1998 832 All items with tags in the range 1-9999 and 30000 and up are considered  David Byers committed Sep 13, 1997 833 834 predefined. If a client attempts to create an item with a tag in this range, but the server has no idea what that tag means, the server will  David Byers committed May 12, 1999 835 return an error (illegal-aux-item.)  David Byers committed Sep 13, 1997 836   Kent Engström committed Oct 20, 1999 837 838 839 Some of the aux-items below (mostly the ones that begin with "mx-") are used by mail importers. For information about supplementary aux-items introduced by @code{komimportmail}, see @ref{komimportmail Aux-Item Types}.  David Byers committed Sep 13, 1997 840 841 842  @table @samp @item content-type [1] (text)  David Byers committed Oct 09, 1999 843 Specifies the content type of a text. Data is a valid MIME type or one  David Byers committed Sep 13, 1997 844 845 846 847 848 849 850 851 852 853 854 of the special LysKOM types (@pxref{LysKOM Content Types}.) This item may only be set by the author of a text. The inherit, secret and hide-owner bits are cleared. Only one content-type item can be created per creator. @item fast-reply [2] (text) Data is a string that constitutes a brief comment to the text. This comment should be displayed immediately after the text body.  David Byers committed Dec 26, 1998 855 856 An item of this type will never be inherited, can always be deleted, is never anonymous and is never secret.  David Byers committed Sep 13, 1997 857 858 859  @item cross-reference [3] (text, conference)  David Byers committed Dec 26, 1998 860 Data is a cross-reference to something else. The contents consist of a  Per Cederqvist committed Aug 18, 1999 861 862 letter, a number, and optionally a space and a descriptive text. The letter must be one  David Byers committed Dec 26, 1998 863 864 865 866 867 of T, C or P. T specifies that the cross-reference points to a text; C that it points to a conference; and P that it points to a person. The number is the id of the target of the cross reference. The descriptive text is simly that, a text that describes the cross-reference. For example, "T15 Check this out!" is a cross reference to text 15 with a  Per Cederqvist committed Aug 18, 1999 868 869 description that reads "Check this out!", and "T17" is a cross reference without a description.  David Byers committed Sep 13, 1997 870   David Byers committed Dec 26, 1998 871 872 The inherit bit is automatically cleared and the item can always be deleted.  David Byers committed Sep 13, 1997 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905  @item no-comments [4] (text) When this item is set, the author requests that nobody comments the text. This is advisory only; it is still possible to write comments, but clients should advise the user that this is contrary to the author's wishes. Data should be empty. This item may only be set by the author. The secret, hide-creator and inherit bits are automatically cleared. @item personal-comment [5] (text) When this item is set, the author requests only personal comments. This is advisory only; it is still possible to create regular comments, but clients should advise the user that the author prefers a personal comment. Data should be empty. This item may only be set by the author. The secret, hide-creator and inherit bits are automatically cleared. @item request-confirmation [6] (text) The author requests that everyone who reads the text confirms having done so by creating read-confirmation items on the text. Clients should ask users if they wish to confirm having read the text when it is displayed. Data should be empty. The hide-creator, secret and inherit bits are automatically cleared. @item read-confirm [7] (text) This item can be taken as confirmation that the item creator has read  Per Cederqvist committed Aug 08, 1998 906 907 908 the text to which the item is attached. Clients should never ever create this item without an explicit confirmation from the user that the text has indeed been read.  David Byers committed Sep 13, 1997 909 910  The hide-creator, secret and inherit bits are automatically cleared.  David Byers committed Dec 26, 1998 911 Once created an item of this type cannot be deleted.  David Byers committed Sep 13, 1997 912 913 914  @item redirect [8] (conference)  David Byers committed Dec 29, 1998 915   David Byers committed Dec 26, 1998 916 917 918 919 920 921 922 923 924 925 926 This item indicates that texts should not be sent to the conference, but be directed to some other target instead. Clients should notify users that attempt to send texts to the conference of the redirect and offer to send the text to the target of the redirect instead. A typical use of this item would be a user that does not read LysKOM very often and would like to advise other users to send e-mail instead. Data is PROTOCOL:ADDRESS where PROTOCOL is either "E-mail" or "LysKOM", and ADDRESS is either an e-mail address or a LysKOM conference. Hopefully we'll be able to replace this with a forwarding mechanism later.  David Byers committed Sep 13, 1997 927 928  This item can only be set by the conference supervisor or in the case of  David Byers committed Dec 26, 1998 929 a mailbox, the person attached to the mailbox. The hide-creator and  David Byers committed Sep 13, 1997 930 931 932 secret bits are cleared automatically. Only one redirect can be specified.  David Byers committed Dec 29, 1998 933   David Byers committed Sep 13, 1997 934 935 936 937 938 @item x-face [9] (conference) Data is the face of the person in compface format. Cool, innit? This item can only be set by the conference supervisor or in the case of  David Byers committed Dec 26, 1998 939 a mailbox, the person attached to the mailbox. The hide-creator and  David Byers committed Sep 13, 1997 940 941 942 secret bits are cleared automatically.  Per Cederqvist committed Aug 08, 1998 943 @item alternate-name [10] (text, conference)  David Byers committed Sep 13, 1997 944 945  Data is a string that the client may use as an alternate to the name of  David Byers committed Dec 26, 1998 946 947 948 a conference or the subject of a text. Note that the server does not match against this name when performing name lookups. Clients should only display alternate names created by the user currently logged on.  David Byers committed Sep 13, 1997 949 950 951 952 953 954 955  The inherit flag is automatically cleared. @item pgp-signature [11] (text) Data is a PGP signature of the text. The signature should be the  David Byers committed Dec 26, 1998 956 equivalent of what "pgp -sba" in PGP 2.6.2 generates.  David Byers committed Sep 13, 1997 957 958 959 960 961 962 963 964  The secret, hide-creator and inherit bits are automatically cleared. Signatures cannot be deleted once they have been created. @item pgp-public-key [12] (letterbox) Data is the public key of the person. It is desirable that the public  David Byers committed May 23, 1999 965 966 967 key contains a userid of the format "LysKOM +", where @var{n} is the number of the person in the LysKOM server specified in @var{server}. This rule is currently not enforced.  David Byers committed Sep 13, 1997 968 969 970 971  This item can only be set by the person himself. The hide-creator, secret and inherit bits are automatically cleared.  David Byers committed Dec 26, 1998 972   Per Cederqvist committed Aug 16, 1998 973 974 @item e-mail-address [13] (conference, letterbox, server)  David Byers committed Dec 26, 1998 975 976 Data is an RFC 822-style email address. When set on a mailbox, it should be the email address of the person. If the person has multiple  Per Cederqvist committed Aug 16, 1998 977 978 979 email addresses he may set serveral e-mail-address aux-items. The meaning of this aux-item when set on a conference that isn't a  David Byers committed Dec 26, 1998 980 981 982 mailbox is vague. For a conference that is used as to import a mailing list this should be the email address of the list. For other conferences we haven't really defined a sensible use.  Per Cederqvist committed Aug 16, 1998 983 984  When this aux-item is set on the server it shold contain the email  David Byers committed Jan 18, 1999 985 address of the administrator (or administrators.)  Per Cederqvist committed Aug 16, 1998 986   David Byers committed Dec 26, 1998 987 988 989 This aux-item can only be set by the supervisor of a conference or the server administrator. The creator cannot be hidden.  Per Cederqvist committed Aug 16, 1998 990 991 992 993  @item faq-text [14] (conference, server) Data is a decimal text number, which is a FAQ for the conference (or  David Byers committed May 12, 1999 994 995 server). Creating an item of this type automatically causes creation of a faq-for-conf item.  David Byers committed Dec 26, 1998 996 997 998 999  This item can only be set by the supervisor or server administrator. The hide-creator, secret, and inherit bits are automatically cleared.  Per Cederqvist committed Aug 16, 1998 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011  @item creating-software [15] (text) Data is the name and version number of the client that created the text. This aux-item can only be set by the author of the text. Once set, it cannot be removed or changed. A typical value would be @samp{elisp-client 0.47.3}. Setting the creating-software aux-item is optional. The data should be the client name, a space, and the client version used in the @code{set-client-version} call. The server may enforce this restriction.  David Byers committed Sep 13, 1997 1012   David Byers committed Jan 14, 1999 1013 @item mx-author [16] (text)  Jonas S Karlsson committed Oct 11, 1998 1014   David Byers committed Jan 14, 1999 1015 Data is a string containing the name of the author of an imported  Kent Engström committed Oct 20, 1999 1016 1017 1018 1019 1020 1021 e-mail, extracted from the @code{From} header. This aux-item may be missing, if the mail address in the @code{From} header consists of just the @code{addr-spec} (see the next aux-item). Clients should display this instead of the actual author of the text (which will be an importer ID) even if an mx-from aux-item is not present.  Jonas S Karlsson committed Oct 11, 1998 1022   Kent Engström committed Jul 25, 1999 1023 1024 Sample contents: @code{Joe Q. Public} which may come from a @code{From} header containing @code{"Joe Q. Public" }.  Jonas S Karlsson committed Oct 11, 1998 1025   David Byers committed Jan 14, 1999 1026 @item mx-from [17] (text)  Jonas S Karlsson committed Oct 11, 1998 1027   Kent Engström committed Jul 25, 1999 1028 1029 Data is the proper e-mail address (called @code{addr-spec} in the mail standards) extracted from the @code{From} header of an imported  Kent Engström committed Oct 20, 1999 1030 1031 1032 1033 1034 1035 e-mail. Clients should display this address together with the mx-author, preferably inside angles. If mx-author is not present, this address should be shown anyway. It can also be used by clients to construct an address for personal (e-mail) replies to an imported message.  Jonas S Karlsson committed Oct 11, 1998 1036   Kent Engström committed Jul 25, 1999 1037 1038 1039 Sample contents: @code{john.q.public@@example.com} which may come from a @code{From} header containing @code{john.q.public@@example.com} or something like @code{"Joe Q. Public" }.  Jonas S Karlsson committed Oct 11, 1998 1040   David Byers committed Jan 14, 1999 1041 @item mx-reply-to [18] (text)  Jonas S Karlsson committed Oct 11, 1998 1042   Kent Engström committed Jul 25, 1999 1043 1044 1045 1046 Data is the proper e-mail address (called @code{addr-spec} in the mail standards) extracted from the @code{Reply-To} header of an imported e-mail. Clients should use this for constructing replies to imported messages.  Jonas S Karlsson committed Oct 11, 1998 1047   David Byers committed Jan 14, 1999 1048 @item mx-to [19] (text)  Jonas S Karlsson committed Oct 11, 1998 1049   Kent Engström committed Oct 20, 1999 1050 1051 1052 1053 Data is a single e-mail address from an email @code{To} header. Multiple @code{mx-to} items may be present when multiple recipients are specified in the header. Clients should display these items along with the normal LysKOM recipient headers.  Jonas S Karlsson committed Oct 11, 1998 1054   Kent Engström committed Jul 25, 1999 1055 1056 1057 Sample contents: @code{john.q.public@@example.com} and @code{"Joe Q. Public" } are both valid.  David Byers committed Jan 14, 1999 1058 @item mx-cc [20] (text)  David Byers committed Sep 13, 1997 1059   David Byers committed Jan 14, 1999 1060 1061 Same as @code{mx-to}, but applies to the @code{CC} header rather than the @code{To} header.  Jonas S Karlsson committed Oct 11, 1998 1062   David Byers committed Jan 14, 1999 1063 @item mx-date [21] (text)  1064   Kent Engström committed Oct 20, 1999 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 Data is the date and time from the @code{Date} header of an imported email. Its format is "YYYY-MM-DD hh:mm:ss TZ". YYYY is the year the message was sent, MM is the month, DD is the day, hh is the hour, mm is the minute and ss is the second. This date and time are given in the timezone where the message was sent. TZ is the timezone the date is valid for. It must be of the form "+hhmm" or "-hhmm", where hh is the number of hours offset from UTC and mm is the number of minutes offset. Symbolic timezones are not permitted. The timezone specification is recommended but optional, since it is not always available. Clients should display this information as the date and time a text was written, since the imported text will have been created at a later time. The date and time when the mesage was imported would then be displayed elsewhere or not at all.  1079   David Byers committed Jan 14, 1999 1080 1081 @item mx-message-id [22] (text)  Kent Engström committed Oct 20, 1999 1082 1083 1084 Data is the @code{Message-ID} header of an imported e-mail, with whitespace and comments removed. The Message-ID should contain the surrounding angles.  David Byers committed Jan 14, 1999 1085 1086 1087  @item mx-in-reply-to [23] (text)  Kent Engström committed Oct 20, 1999 1088 1089 1090 Data is a string containing one item of the same form as the mx-message-id item described above. This is the Message-ID of another mail the current text is a comment to.  David Byers committed Jan 14, 1999 1091   Kent Engström committed Oct 20, 1999 1092 1093 1094 1095 1096 1097 1098 Hopefully, this information comes from the @code{In-Reply-To} header of the imported e-mail, but it could also have been picked from the end of the @code{References} header line. If the text really comments more than one other text directly, it is allowed to attach more than one @code{mx-in-reply-to} items to it.  David Byers committed Jan 14, 1999 1099 1100 1101  @item mx-misc [24] (text)  Kent Engström committed Oct 20, 1999 1102 1103 1104 1105 1106 Data is a string that contains all of the headers of an imported email, including @code{Subject}, and including those that are redundantly stored in other aux-items. The headers are concatenated with "\n". In other words, this item contains all headers of an imported e-mail as they appear in the message.  David Byers committed Jan 14, 1999 1107   Kent Engström committed Oct 20, 1999 1108 Clients are encouraged to provide a command to display this information.  Jonas S Karlsson committed Oct 11, 1998 1109   Kent Engström committed Oct 20, 1999 1110 @item mx-allow-filter [25] (conference)  Jonas S Karlsson committed Oct 11, 1998 1111   Kent Engström committed Oct 20, 1999 1112 1113 1114 This aux-item has been declared obsolete. It was intended to supply the importer with information on how to filter incoming messages based on regular expressions matching header lines.  Jonas S Karlsson committed Oct 11, 1998 1115   David Byers committed Jan 14, 1999 1116 @item mx-reject-forward [26] (conference)  Jonas S Karlsson committed Oct 11, 1998 1117   Kent Engström committed Oct 20, 1999 1118 1119 1120 This aux-item has been declared obsolete. It was intended to supplement mx-allow-filter by telling where rejected mails should be sent.  Jonas S Karlsson committed Oct 11, 1998 1121   David Byers committed Dec 26, 1998 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 @item notify-comments [27] (letterbox) Data is a decimal text number that the user is interested in. Clients should monitor this text for unread comments and present these to the user in some convenient manner. This is typically used by users that want to read comments to some text of theirs as soon as they arrive, rather than in the normal reading order. This item can only be set by the owner of the letterbox. No flags are forced or cleared.  David Byers committed Sep 13, 1997 1132   David Byers committed May 12, 1999 1133 1134 1135 1136 1137 1138 1139 1140 @item faq-for-conf [28] (text) Data is a decimal number specifying the conference a certain text is a FAQ for. The special number zero denotes that the text is a FAQ for the entire system. Items of this kind can only be created by the LysKOM server itself. Texts with this item are protected from garbage collection.  Per Cederqvist committed Aug 18, 1999 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 @item recommended-conf [29] (server) Data is a decimal number specifying a conference that new members should automatically be added to, optionally followed by a space and a recommended priority, optionally followed by a space and a membership type. In the future, additional data may be defined; clients should be prepared to accept and ignore a space and any trailing data that may follow the membership type. A few examples might clarify what the data may look like: @table @code @item 1 Conference number 1. @item 2 32 Conference number 2, with priority 32. @item 3 250 11100000 Conference number 3, with priority 250. The membership should be secret, passive and have the invitation bit set. @item 4 253 01000000 garbage Conference number 4, with priority 253. The membership should be passive. The client should ignore the trailing garbage. Note that  Kent Engström committed Oct 20, 1999 1162 clients are not allowed to create aux-items of this format, but the  Per Cederqvist committed Aug 18, 1999 1163 1164 1165 1166 1167 1168 should be prepared to hande them correctly. @end table This is a recommendation only; it is up to the client that creates a new person to also add him to the conferences that are specified via @code{recommended-conf}.  David Byers committed Sep 13, 1997 1169   David Byers committed Dec 26, 1998 1170 1171 @end table  Per Cederqvist committed May 23, 1999 1172 @node Client-Specific Aux-Item Types  Per Cederqvist committed Apr 04, 1999 1173 @subsection Client-Specific Aux-Item Types  David Byers committed Sep 13, 1997 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187  Client-specific items do not cause the server to perform any magic. All the flags (except the delete flag) are left untouched, the data is not validated in any way, and anyone can create any item. If you need more server support than this, your item should be on the predefined list. All tags in the range 10000-19999 are reserved for clients. Blocks of 100 numbers at a time can be assigned to specific clients. A client should never create items with tags in a range assigned to another client or in an unassigned range. Assigned ranges will never change. Currently, the following ranges are assigned to clients: @itemize @bullet @item 10000-10099: The Elisp Client  David Byers committed Oct 09, 1999 1188 @item 10100-10199: komimportmail  David Byers committed Sep 13, 1997 1189 1190 1191 1192 1193 @end itemize If you want a range of numbers, send e-mail to the LysKOM development group.  Kent Engström committed Oct 20, 1999 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210