Protocol-A.texi 282 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 David Byers committed May 23, 1999 5 @c $Id: Protocol-A.texi,v 1.66 1999/05/23 13:04:57 byers 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 Apr 04, 1999 22 23 This is specification 10.0 of LysKOM Protocol A. 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 David Byers committed May 18, 1999 64 @node Top, Overview, (dir), (dir) 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 Apr 05, 1999 68 This is revision 10.0 of the specification. David Byers committed Jan 13, 1996 69 Per Cederqvist committed Aug 02, 1998 70 71 72 73 FIXME: This document is not yet published. The document you are looking at has the version numbers all wrong. This will be fixed before publication. David Byers committed Jan 13, 1996 74 @menu Per Cederqvist committed Apr 04, 1999 75 76 77 78 79 80 81 82 83 84 85 86 * 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 87 88 89 @end menu @end ifinfo David Byers committed May 18, 1999 90 @node Overview, Introduction, Top, Top David Byers committed Jan 13, 1996 91 92 93 @chapter Overview LysKOM is a conferencing system@footnote{Or in modern terms, enabling David Byers committed Sep 13, 1997 94 95 96 97 98 99 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 100 David Byers committed Sep 13, 1997 101 102 103 This document specifies version 10.0 of protocol A used between a LysKOM client and a LysKOM server. Anything described here as unspecified'' is liable to change in future protocol versions. David Byers committed Jan 13, 1996 104 105 This specification is the work of several people. The main contributors have David Byers committed Sep 13, 1997 106 been David Byers committed May 23, 1999 107 108 Per Cederqvist @email{ceder@@lysator.liu.se}, David Byers @email{byers@@lysator.liu.se}, David Byers committed Jan 13, 1996 109 110 111 112 113 114 @ifinfo Pär @end ifinfo @iftex P@"ar @end iftex David Byers committed May 23, 1999 115 116 117 118 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 119 120 121 122 123 124 @ifinfo Kent Engström @end ifinfo @iftex Kent Eng@-str@"om@penalty-10000 @end iftex David Byers committed May 23, 1999 125 @email{kent@@lysator.liu.se}. David Byers committed Jan 13, 1996 126 David Byers committed May 23, 1999 127 128 The LysKOM developers can be reached by email to @email{lyskom@@lysator.liu.se}. David Byers committed Jan 13, 1996 129 Per Cederqvist committed Apr 04, 1999 130 131 132 133 @menu * Document Revision History:: * Protocol Version History:: * Notation:: David Byers committed Jan 13, 1996 134 135 @end menu David Byers committed May 18, 1999 136 @node Document Revision History, Protocol Version History, Overview, Overview David Byers committed Jan 13, 1996 137 138 139 @section Document Revision History @table @asis David Byers committed Sep 13, 1997 140 Per Cederqvist committed Apr 04, 1999 141 142 143 144 145 146 @item 10.0: @i{In progress} The specification was translated to English and converted to Texinfo by David Byers. Protocol version 10. Distributed with lyskomd 2.0.0. @item 9.0: 1996-08-04 This version was distributed with lyskomd 1.9.0. David Byers committed Jun 14, 1996 147 David Byers committed Jan 13, 1996 148 @item 8.0: 1995-11-10 Per Cederqvist committed Apr 04, 1999 149 Protocol version 8. Distributed with lyskomd 1.8.0. David Byers committed Jan 13, 1996 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 @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 David Byers committed May 18, 1999 174 @node Protocol Version History, Notation, Document Revision History, Overview Per Cederqvist committed Apr 04, 1999 175 176 177 @section Protocol Version History @subsection Protocol version 10 (first implemented in lyskomd 2.0.0) David Byers committed Jan 13, 1996 178 David Byers committed Sep 13, 1997 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 @table @asis @item New Server Calls @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 @item 97=set-expire David Byers committed Jun 14, 1998 195 196 197 198 @item 98=query-read-texts @item 99=get-membership @item 100=add-member @item 101=get-members Per Cederqvist committed Apr 18, 1999 199 200 201 @item 102=set-membership-type @item 103=local-to-global @item 104=map-created-texts David Byers committed Jan 07, 1999 202 @item 105=set-keep-commented David Byers committed Sep 13, 1997 203 204 205 206 207 @end itemize @item Removed Server Calls @itemize @bullet @item 5=create-person David Byers committed Jun 14, 1998 208 @item 9=query-read-texts David Byers committed Sep 13, 1997 209 @item 10=create-conf David Byers committed Jun 14, 1998 210 @item 14=add-member David Byers committed Sep 13, 1997 211 212 213 @item 26=get-text-stat @item 28=create-text @item 36=get-info-old David Byers committed Jun 14, 1998 214 215 @item 46=get-membership-old @item 48=get-members-old David Byers committed Sep 13, 1997 216 217 218 219 220 221 @item 50=get-conf-stat @item 59=create-anonymous-text @end itemize @item New and New Modified Structures @itemize @bullet Per Cederqvist committed Aug 29, 1998 222 @item Aux-Item Per Cederqvist committed Aug 29, 1998 223 @item Aux-Item-Input David Byers committed Sep 13, 1997 224 225 @item Conference @item Info David Byers committed Jun 14, 1998 226 227 228 @item Member @item Membership @item Membership-Type Per Cederqvist committed Aug 29, 1998 229 230 @item Misc-Info @item Text-Stat David Byers committed Sep 13, 1997 231 232 233 234 235 236 237 @end itemize @item New Asynchronous Messages @itemize @bullet @item async-deleted-text message @item New async-new-text message @end itemize David Byers committed Dec 29, 1998 238 239 240 241 242 243 244 245 246 247 248 249 250 @item Notes @itemize @bullet @item Since protocol version 9 setting a priority of zero in a 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 Membership-type extension to Membership type. In order to maintain 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 251 252 @end table David Byers committed Dec 29, 1998 253 Per Cederqvist committed Apr 04, 1999 254 @subsection Protocol version 9 (first implemented in lyskomd 1.9.0) David Byers committed Jun 14, 1996 255 256 @table @asis Per Cederqvist committed Apr 04, 1999 257 258 259 260 261 262 @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 263 @item Added Commands David Byers committed Jun 14, 1996 264 @itemize @bullet David Byers committed Sep 13, 1997 265 266 267 268 269 270 @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 271 @end itemize Per Cederqvist committed Apr 04, 1999 272 273 274 275 276 277 278 @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 279 280 281 @item 63=@code{who-is-on-ident} is now considered obsolete. @item 64=@code{get-session-info-ident} is now considered obsolete. @item 59=@code{create-anonymous-text-old} is now considered obsolete. Per Cederqvist committed Apr 04, 1999 282 @end itemize David Byers committed Jun 14, 1996 283 284 @end table Per Cederqvist committed Apr 04, 1999 285 @subsection Protocol version 8 (first implemented in lyskomd 1.8.0) David Byers committed Jan 13, 1996 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 @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 321 75=get-version-info David Byers committed Jan 13, 1996 322 @item Per Cederqvist committed Apr 04, 1999 323 76=lookup-z-name David Byers committed Jan 13, 1996 324 325 326 327 328 @end itemize @item Other @itemize @bullet @item Per Cederqvist committed Jul 07, 1998 329 The asynchronous message 1=i-am-off has been removed David Byers committed Jan 13, 1996 330 331 332 333 334 335 336 337 338 @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 339 67=lookup-person David Byers committed Jan 13, 1996 340 @item Per Cederqvist committed Apr 04, 1999 341 68=lookup-conf David Byers committed Jan 13, 1996 342 @item Per Cederqvist committed Apr 04, 1999 343 69=set-client-version David Byers committed Jan 13, 1996 344 @item Per Cederqvist committed Apr 04, 1999 345 70=get-client-name David Byers committed Jan 13, 1996 346 @item Per Cederqvist committed Apr 04, 1999 347 71=get-client-version David Byers committed Jan 13, 1996 348 @item Per Cederqvist committed Apr 04, 1999 349 72=mark-text David Byers committed Jan 13, 1996 350 @item Per Cederqvist committed Apr 04, 1999 351 73=unmark-text David Byers committed Jan 13, 1996 352 353 354 355 356 357 358 359 360 361 @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 362 65=re-lookup-person David Byers committed Jan 13, 1996 363 @item Per Cederqvist committed Apr 04, 1999 364 66=re-lookup-conf David Byers committed Jan 13, 1996 365 366 367 368 369 370 371 372 373 374 375 @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 376 63=who-is-on-ident David Byers committed Jan 13, 1996 377 @item Per Cederqvist committed Apr 04, 1999 378 64=get-session-info-ident David Byers committed Jan 13, 1996 379 380 381 382 383 384 385 386 387 @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 388 61=find-previous-text-no David Byers committed Jan 13, 1996 389 @item Per Cederqvist committed Apr 04, 1999 390 60=find-next-text-no David Byers committed Jan 13, 1996 391 @item Per Cederqvist committed Apr 04, 1999 392 59=create-anonymous-text David Byers committed Jan 13, 1996 393 @item Per Cederqvist committed Apr 04, 1999 394 58=get-last-text David Byers committed Jan 13, 1996 395 396 397 398 399 400 401 402 403 @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 404 57=set-user-area David Byers committed Jan 13, 1996 405 406 407 408 409 410 411 412 413 414 415 @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 David Byers committed May 18, 1999 416 @node Notation, , Protocol Version History, Overview David Byers committed Jan 13, 1996 417 418 @section Notation David Byers committed Sep 13, 1997 419 This specification uses a BNF-like grammar to describe the protocol and Per Cederqvist committed Apr 04, 1999 420 its data elements. David Byers committed Jan 13, 1996 421 David Byers committed Sep 13, 1997 422 Data fields have been given names that start with a lower-case letter. Per Cederqvist committed Aug 29, 1998 423 424 425 426 427 428 429 430 431 432 433 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 434 435 436 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 437 438 David Byers committed May 18, 1999 439 @node Introduction, Data Types, Overview, Top David Byers committed Jan 13, 1996 440 441 442 443 444 445 @chapter Introduction This chapter introduces the concepts used in LysKOM, such as articles, conferences and sessions. @menu Per Cederqvist committed Apr 04, 1999 446 447 448 449 450 451 452 * Articles:: * Conferences:: * The Misc-Info List:: * The Aux-Item List:: * Security:: * Membership and Reading:: * Client-Server Dialog:: David Byers committed Jan 13, 1996 453 454 455 @end menu David Byers committed May 18, 1999 456 @node Articles, Conferences, Introduction, Introduction David Byers committed Jan 13, 1996 457 458 459 460 @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 461 462 463 464 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 465 David Byers committed Sep 13, 1997 466 467 468 469 470 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 471 472 473 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 474 reused. If an article has recipients it will also have a local number Per Cederqvist committed Jul 07, 1998 475 for each recipient. Local numbers are used in some data structures to Per Cederqvist committed Aug 08, 1998 476 provide more compact storage and to provide an ordering of articles for David Byers committed Sep 13, 1997 477 478 479 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 480 David Byers committed Sep 13, 1997 481 Occasionally it is necessary to map between local and global numbers. Per Cederqvist committed Aug 03, 1998 482 The server call @code{local-to-global} does this. David Byers committed Jan 13, 1996 483 484 485 David Byers committed May 18, 1999 486 @node Conferences, The Misc-Info List, Articles, Introduction David Byers committed Jan 13, 1996 487 488 @section Conferences David Byers committed Sep 13, 1997 489 490 491 492 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 493 If the supervisor is a person, the members of that person's mailbox David Byers committed Sep 13, 1997 494 495 496 497 498 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 499 500 Each conference has a type, which is essentially a collection of boolean Per Cederqvist committed Jul 07, 1998 501 flags. Currently the flags @code{rd-prot}, @code{letterbox}, David Byers committed Sep 13, 1997 502 @code{secret}, @code{original} and @code{allow-anonymous} are defined. David Byers committed Jan 13, 1996 503 504 505 506 507 508 509 @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 510 511 512 513 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 514 @item letterbox David Byers committed Sep 13, 1997 515 Conferences of this type are connected to persons. Letters to a person David Byers committed Dec 26, 1998 516 are sent to the mailbox and the name of the mailbox is synchronized David Byers committed Sep 13, 1997 517 518 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 519 520 521 @item secret Conferences of this type are secret. The server will not divulge any information of the existence of the conference to persons who are not David Byers committed Dec 26, 1998 522 members or supervisors of the conference. If a mailbox is made secret, David Byers committed Jan 13, 1996 523 524 that person cannot log in using the person name, but must specify a person number instead. David Byers committed Sep 13, 1997 525 526 527 @item allow-anonymous Conferences of this type accept anonymous articles. Other conferences will reject anonymous articles. David Byers committed Dec 26, 1998 528 529 530 @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 531 532 533 534 @end table Per Cederqvist committed Apr 04, 1999 535 536 537 538 @menu * Persons and Sessions:: @end menu David Byers committed May 18, 1999 539 @node Persons and Sessions, , Conferences, Conferences David Byers committed Jan 13, 1996 540 541 542 @subsection Persons and Sessions Persons are represented in the protocol by values of the type David Byers committed Sep 13, 1997 543 544 545 546 @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 547 548 Connections to the server are represented as values of the type David Byers committed Sep 13, 1997 549 550 551 552 553 554 @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 555 556 David Byers committed May 18, 1999 557 @node The Misc-Info List, The Aux-Item List, Conferences, Introduction David Byers committed Jan 13, 1996 558 559 @section The Misc-Info List David Byers committed Sep 13, 1997 560 561 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 562 563 recipient; carbon copy recipient; blank carbon copy recipient; comment to; footnote to; comment in David Byers committed Sep 13, 1997 564 565 566 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 567 David Byers committed Jun 14, 1996 568 @subsection Recipient David Byers committed Jan 13, 1996 569 570 571 @table @code @item recpt David Byers committed Sep 13, 1997 572 573 Starts a recipient group. It contains the conference number of a recipient of the article. David Byers committed Jan 13, 1996 574 @item loc-no David Byers committed Sep 13, 1997 575 576 577 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 578 @item rec-time David Byers committed Sep 13, 1997 579 580 581 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 582 @item sent-by David Byers committed Sep 13, 1997 583 584 585 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 586 @item sent-at David Byers committed Sep 13, 1997 587 588 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 589 590 591 @end table David Byers committed Jun 14, 1996 592 @subsection Carbon Copy (CC) Recipient David Byers committed Jan 13, 1996 593 David Byers committed Sep 13, 1997 594 595 596 597 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 598 article. This difference is enforced by the clients. David Byers committed Jan 13, 1996 599 600 601 @table @code @item cc-recpt David Byers committed Sep 13, 1997 602 603 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 604 @item loc-no David Byers committed Sep 13, 1997 605 606 607 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 608 @item rec-time David Byers committed Sep 13, 1997 609 Present after the CC recipient has read the article. It contains the Per Cederqvist committed Oct 06, 1998 610 611 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 612 613 614 @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 615 person who added the CC recipient. David Byers committed Jan 13, 1996 616 617 618 619 620 621 @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 622 623 624 625 626 627 628 629 630 631 632 633 634 635 @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 allowed to fetch both the text status of the involed text and the conference status of the involved conference. (That is, as long as the conference isn't secret everybody is allowed to se the carbon-copy 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 David Byers committed Jan 14, 1999 636 old-style calls such as @xref{get-text-stat-old} are used this Per Cederqvist committed Oct 06, 1998 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 will be converted to a CC recipient group by the server for the benefit of clients that don't understand this group. @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 662 @subsection Comment To David Byers committed Jan 13, 1996 663 664 665 666 667 668 669 670 671 672 673 674 675 676 @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 been created. It contains the time when is was added as a comment. @end table David Byers committed Jun 14, 1996 677 @subsection Footnote To David Byers committed Jan 13, 1996 678 679 @table @code David Byers committed Sep 13, 1997 680 @item footn-to David Byers committed Jan 13, 1996 681 682 683 684 685 686 687 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 been created. It contains the time when is was added as a footnote. @end table David Byers committed Jun 14, 1996 688 @subsection Comment in David Byers committed Jan 13, 1996 689 690 691 692 693 694 695 696 @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 697 @subsection Footnote in David Byers committed Jan 13, 1996 698 699 @table @code David Byers committed Sep 13, 1997 700 @item footn-in David Byers committed Jan 13, 1996 701 702 703 704 705 Present when there are footnotes to this article. It contains the article number which is a footnote to this article. @end table David Byers committed May 18, 1999 706 @node The Aux-Item List, Security, The Misc-Info List, Introduction Per Cederqvist committed Apr 04, 1999 707 @section The Aux-Item List David Byers committed Sep 13, 1997 708 709 710 711 712 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 713 714 715 716 717 * 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 718 719 @end menu David Byers committed May 18, 1999 720 @node About Aux-Items, Predefined Aux-Item Types, The Aux-Item List, The Aux-Item List Per Cederqvist committed Apr 04, 1999 721 @subsection About Aux-Items David Byers committed Sep 13, 1997 722 723 724 725 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 726 out a case where setting an aux-item on the mailbox wasn't as good as David Byers committed Sep 13, 1997 727 728 729 730 731 732 733 734 735 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 736 Items are numbered from one and up within each item list. Once assigned, David Byers committed Sep 13, 1997 737 738 739 740 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 741 The tag field identifies the type of aux item. It is used by the server David Byers committed Sep 13, 1997 742 743 744 745 746 747 748 749 750 751 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.) David Byers committed May 18, 1999 752 @node Predefined Aux-Item Types, Client-Specific Aux-Item Types, About Aux-Items, The Aux-Item List Per Cederqvist committed Apr 04, 1999 753 @subsection Predefined Aux-Item Types David Byers committed Sep 13, 1997 754 David Byers committed May 12, 1999 755 756 757 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 758 David Byers committed May 12, 1999 759 760 761 762 763 764 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, flags, who can create them, to what objects they can be attached to and 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 765 Per Cederqvist committed Aug 08, 1998 766 All items with tags in the range 1-9999 and 30000 and up are considered David Byers committed Sep 13, 1997 767 768 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 769 return an error (illegal-aux-item.) David Byers committed Sep 13, 1997 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 @table @samp @item content-type [1] (text) Specifies the content type of a text. Data is a valid MIME type of one 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 787 788 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 789 790 791 @item cross-reference [3] (text, conference) David Byers committed Dec 26, 1998 792 793 794 795 796 797 798 799 Data is a cross-reference to something else. The contents consist of a letter, a number, a space and a descriptive text. The letter must be one 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 description that reads "Check this out!". David Byers committed Sep 13, 1997 800 David Byers committed Dec 26, 1998 801 802 The inherit bit is automatically cleared and the item can always be deleted. David Byers committed Sep 13, 1997 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 @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 836 837 838 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 839 840 The hide-creator, secret and inherit bits are automatically cleared. David Byers committed Dec 26, 1998 841 Once created an item of this type cannot be deleted. David Byers committed Sep 13, 1997 842 843 844 @item redirect [8] (conference) David Byers committed Dec 29, 1998 845 David Byers committed Dec 26, 1998 846 847 848 849 850 851 852 853 854 855 856 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 857 858 This item can only be set by the conference supervisor or in the case of David Byers committed Dec 26, 1998 859 a mailbox, the person attached to the mailbox. The hide-creator and David Byers committed Sep 13, 1997 860 861 862 secret bits are cleared automatically. Only one redirect can be specified. David Byers committed Dec 29, 1998 863 David Byers committed Sep 13, 1997 864 865 866 867 868 @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 869 a mailbox, the person attached to the mailbox. The hide-creator and David Byers committed Sep 13, 1997 870 871 872 secret bits are cleared automatically. Per Cederqvist committed Aug 08, 1998 873 @item alternate-name [10] (text, conference) David Byers committed Sep 13, 1997 874 875 Data is a string that the client may use as an alternate to the name of David Byers committed Dec 26, 1998 876 877 878 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 879 880 881 882 883 884 885 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 886 equivalent of what "pgp -sba" in PGP 2.6.2 generates. David Byers committed Sep 13, 1997 887 888 889 890 891 892 893 894 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 895 896 897 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 898 899 900 901 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 902 Per Cederqvist committed Aug 16, 1998 903 904 @item e-mail-address [13] (conference, letterbox, server) David Byers committed Dec 26, 1998 905 906 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 907 908 909 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 910 911 912 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 913 914 When this aux-item is set on the server it shold contain the email David Byers committed Jan 18, 1999 915 address of the administrator (or administrators.) Per Cederqvist committed Aug 16, 1998 916 David Byers committed Dec 26, 1998 917 918 919 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 920 921 922 923 @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 924 925 server). Creating an item of this type automatically causes creation of a faq-for-conf item. David Byers committed Dec 26, 1998 926 927 928 929 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 930 931 932 933 934 935 936 937 938 939 940 941 @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 942 David Byers committed Jan 14, 1999 943 @item mx-author [16] (text) Jonas S Karlsson committed Oct 11, 1998 944 David Byers committed Jan 14, 1999 945 946 947 Data is a string containing the name of the author of an imported e-mail. Clients should display this instead of the actual author of the text, which will be an importer ID. Jonas S Karlsson committed Oct 11, 1998 948 949 David Byers committed Jan 14, 1999 950 @item mx-from [17] (text) Jonas S Karlsson committed Oct 11, 1998 951 David Byers committed Jan 14, 1999 952 953 954 Data is the e-mail address extracted from the @code{From} header of an imported e-mail. This field can be used by clients to construct an address for personal (e-mail) replies to an imported message. Jonas S Karlsson committed Oct 11, 1998 955 956 David Byers committed Jan 14, 1999 957 @item mx-reply-to [18] (text) Jonas S Karlsson committed Oct 11, 1998 958 David Byers committed Jan 14, 1999 959 960 961 Data is the e-mail address 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 962 963 David Byers committed Jan 14, 1999 964 @item mx-to [19] (text) Jonas S Karlsson committed Oct 11, 1998 965 David Byers committed Jan 14, 1999 966 967 968 969 Data is a single e-mail address, and must be valid as the contents of an e-mail @code{To} header. Multiple @code{mx-o} items may be present. For imported messages, these items contain the @code{To} header of the messages. Jonas S Karlsson committed Oct 11, 1998 970 David Byers committed Jan 14, 1999 971 972 973 On messages created by a LysKOM person, the @code{mx-to} items are used by the exporter to determine that the message is to be exported and where to send it. Jonas S Karlsson committed Oct 11, 1998 974 David Byers committed Jan 14, 1999 975 @item mx-cc [20] (text) David Byers committed Sep 13, 1997 976 David Byers committed Jan 14, 1999 977 978 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 979 980 David Byers committed Jan 14, 1999 981 @item mx-date [21] (text) 982 David Byers committed Jan 14, 1999 983 984 985 986 987 988 989 990 991 Data is the send data of an imported e-mail. 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. 992 David Byers committed Jan 14, 1999 993 994 Clients should display this date as the date a text was written since the imported text will have been created at a later date. 995 996 David Byers committed Jan 14, 1999 997 998 999 @item mx-message-id [22] (text) Data is the @code{Message-ID} header of an imported e-mail. This is used David Byers committed May 12, 1999 1000 by e-mail importers. LysKOM exporters should set the message ID to David Byers committed May 23, 1999 1001 1002 @code{