LysKOM-Projektet -------------------------------- Specifikation 7.0 av protokoll A mellan klient och server -------------------------------- av Lars Aronsson 25 juni 1991 Uppdaterad av Pell samt Per Cederqvist 24 dec 1994 Finjusterad av Per Cederqvist 31 dec 1994 LysKOM LysKOM är ett datakonferenssystem. Andra liknande system är QZ-KOM och PortaCOM. LysKOM är Copyright (C) 1990, 1991, 1992, 1993, 1994 datorföreningen Lysator vid Universitetet och Tekniska Högskolan i Linköping. Var och en tillåts fritt kopiera, ändra och distribuera LysKOM-dokument och program enligt villkoren i GNU General Public License. Varken Lysator eller dess medlemmar tar något som helst ansvar för dokumentens eller programmens riktighet eller följderna av deras användande. Den här texten Den här texten specificerar version A av det protokoll som används mellan en klient (användarens program) och en server (databasen). Den här texten är tänkt att innehålla allt du behöver veta för att skriva en klient utan att veta något om servern, eller tvärtom. Denna ädla föresats är inte helt uppfylld, men kanske i framtiden. Mitt syfte är att den här texten skall vara så fullständig och korrekt som möjligt. Om du hittar några fel, eller kommer på något som saknas, så hör gärna av dig till mig. Följande är de saker som jag vet saknas i den här texten: Vad som lagras i en användares "user-area", och hur. Filer Den här filen är en mer systematisk sammanställning av nedan uppräknade filer. Det är möjligt att filerna har ändrat namn, antal och utseende när du läser detta. Så här hette de den 24 december 1994: doc/security-levels.txt src/include/kom-types.h src/include/kom-errno.h src/server/com.h -- automatgenereras src/server/fncdef.txt src/include/services.h Underliggande protokoll LysKOM Protokoll A kan köras ovanpå vilken tillförlitlig dubbelriktad 8-bitars bytekanal som helst. I nödfall kan det också köras på en 7-bitars bytekanal. Idag körs det ovanpå Telnet/TCP/IP. På Lysator används telnetport 4894 på IP-host kom.lysator.liu.se. Data i protokoll A sker i ASCII klartext. I hollerithsträngar (se nedan) får godtyckliga 8-bitars bytes förekomma, men tanken är att man skall kunna köra protokollet "rått" från en textterminal. Abstrakt syntaxnotation I den här specifikationen har en BNF-liknande grammatik använts för att beskriva protokollets dataelement. Det är mycket vetenskapligt, för så gör de som specar OSI-protokoll. Den här grammatiken borde likna ASN.1 mer än den gör, men jag har inte ASN.1-specen här. Datafält har givits namn med liten begynnelsebokstav, datatyper med stor. Operatorn "::=" definierar (som i BNF) och ":" ger typ (som i Pascal). Kommentarer inleds med "!" och avslutas med radslut (som i BLISS). Semikolon används som i C. De grundläggande typerna och deras notation beskrivs härnäst. Grundläggande datatyper Dataelementen som skickas från klient till server åtskiljs av (ett eller fler) mellanslag (ASCII 0x20), tab-tecken (0x9), line-feed (0xA), return (0xD), eller NULL (0x0). Undvik att skicka NULL. I meddelanden från server till klient åtskiljs dataelementen av exakt ett mellanslag och varje meddelande avslutas alltid med line-feed. INT32, INT16 samt INT8 är icke-negativa heltal som skall rymmas på 32, 16 och 8 bitar, respektive. De skickas som text på decimal form. INTEGER används när inga särskilda begränsningar finns och kan anses synonym med INT32. HOLLERITH är textsträngar. Först skickas strängens längd som en INTEGER, sedan bokstaven "H" och därefter (utan åtskiljande mellanslag!) texten. Texten får innehålla vilka byte-värden som helst från 0 till 255. BITSTRING skickas som text representerande ett heltal på binär form. Antal bitar i strängen framgår alltid av sammanhanget. Även inledande nollor måste skickas. Siffran "1" representerar sant värde och "0" falskt. Bitarna skickas i den ordning de står listade i den abstrakta syntaxen. shape-of-world : BITSTRING ( is-flat; is-round; is-3d; is-2d; ! t.ex. "0110" ) ARRAY är en lista med ett visst antal element. Elementens typ noteras omedelbart efter ordet ARRAY. Först skickas en INTEGER som ger antalet element, sedan skickas tecknet "{", därefter alla elementen i följd och slutligen tecknet "}". Tecknen "{" och "}" fyller egentligen ingen funktion, men underlättar när man kör protokollet "rått". Exempel: hackers : ARRAY HOLLERITH; ! t.ex. 4 { 8Haronsson 7Hbellman 4Hinge 5Hceder } Om arrayen är tom skickas den som "0 *". I vissa anrop (t ex 46=get-membership) kan man säga åt servern att bara skicka tillbaks arrayens storlek, men inte innehållet. Om arrayen innehåller 38 element kommer den i så fall att skickas som "38 *" oavsett vad den innehåller. SELECTION är en INTEGER med efterföljande svans. Vilken typ svansen har beror på värdet av heltalet. För vissa värden kan svansen vara tom. Värdet anges i den abstrakta syntaxen med "nummer=namn". Exempel: phrase : SELECTION ( 1=hello name:HOLLERITH; ! t.ex. "1 4HJohn" 2=howdy ; ! t.ex. "2" ) RPC är en mycket speciell notation som används för protokoll med remote procedure calls, dvs frågor och svar. Notationen för RPC ser ut som SELECTION, men varje alternativ har två svansar: frågan och svaret. Selectornumret skickas bara tillsammans med frågan. Exempel: phrases : RPC ( 1=cost inventory:INTEGER; price:INTEGER; 2=time timezone:INTEGER; hours:INTEGER; 3=name ; name:HOLLERITH; ) ! t.ex. "1 23"->"498" "3"->"4HLars" "2 1"->"1430" Datastrukturen struct/record markeras i den abstrakta syntaxen bara med omgivande "(" och ")". Detta innebär inte att några extra tecken skickas i protokollet. Dialog En session börjar alltid med en uppkoppling, där klienten väljer protokoll genom att skicka en uppkopplingsbegäran : ( "A"; loginnamn : HOLLERITH; ) vilken besvaras från servern av en uppkopplingsbekräftelse : "LysKOM\n" Därefter finns bara RPC-protokollet commands. Klienten får skicka flera frågor innan den fått svar på den första. För att hålla reda på till vilket anrop ett visst svar hör, väljer klienten ett referensnummer att medfölja och samma nummer återfinns i svaret. Det är klientens sak att fritt välja och hålla reda på referensnumren. fråga : ( ref-no : INTEGER; commands-call; ) som, om allt går som det skall, besvaras från servern med ok-return : ( "="; ref-no : INTEGER; commands-return; ) eller, om något misslyckades, med error-return : ( "%"; ref-no : INTEGER; error-no : Error-No; error-status : INTEGER; ) Det skall inte vara något tomrum mellan "=" respektive "%" och ref-no. Observera att även för de funktioner där f-return är innehållslöst svarar servern med "=" eller "%" och ref-number. Säkerhetsnivåer och privilegiebittar Säkerhet och privilegier byggs i LysKOM med två komponenter: Varje person har sig ett antal bittar tilldelad (man kan säga att personen tillhör ett antal grupper) och varje session har dessutom en säkerhetsnivå (ett tal). Varje rättighet kräver en viss bitt och en viss minsta nivå. De nu aktuella nivåerna och kombinationerna av bitt-nivå-rättighet beskrivs i filen doc/security-levels.txt. Här ges en vackrare tabell: Bitt Nivå Rättighet ------------------------------------------------------ wheel Normalt ej tilldelad 0 Alltid logga in, även vid "crowded" 6 Sätta alla Priv_bits för alla personer 7 Sätta password för alla personer 8 Vara organisatör (supervisor) för allt 10 Kan läsa alla texter ------------------------------------------------------ admin Normalt ej tilldelad 1 Stänga av servern 1 Sätta motd_of_kom 1 Läsa last_login 2 Läsa status för hemliga möten och personer 2 Läsa de skyddade delarna av statusen 2 Läsa hela text_statusen, även vid hemliga mottagare 3 Byta namn på alla 4 Addera/subtrahera medlemmar 4 Addera/subtrahera mottagare till texter 5 Sätta supermöte 5 Radera texter 6 Sätta administratör ------------------------------------------------------ statistic Normalt ej tilldelad 2 Läsa statistikdelarna av Person-structen, även om de är skyddade. ------------------------------------------------------ create_conf Normalt tilldelad 0 Skapa möten ------------------------------------------------------ create_pers Normalt tilldelad 0 Skapa personer ------------------------------------------------------ Enligt Thomas Bellmans erfarenheter använder en administratör i praktiskt arbete bara nivåerna 0 och 255. I stället för säkerhetsnivåer borde de enskilda privilegiebittarna slås på och av individuellt. Detta kanske löses elegantare i kommande versioner av protokollet. Felkoder De felkoder som förekommer som svar på RPC-anrop är nedanstående. Här är de förklarade i nummerordning. Det finns en kort lista i alfabetisk ordning strax efteråt. Några felkoder har använts i tidigare versioner av protokoll A, men används ej längre. Dessa felkoder kommer inte att återanvändas, eftersom gamla klienter då skulle kunna ge ett felaktigt felmeddelande. Dessa felkoder är märkta "*" i tabellen nedan. Error-No : SELECTION ( 0=no-error; ! No error has occured ! Felkod 1 används ej. 2=not-impl; ! Not implemented yet 3=obsolete; ! No longer implemented 4=pwd; ! Wrong or illegal password 5=long-str; ! String too long 6=login; ! Not logged in. 7=login-disallowed; ! System is in 'singel-user mode' 8=conf-zero; ! Attempt to use conference number 0. 9=undef-conf; ! Undefined or secret conference 10=undef-pers; ! Undefined or secret person 11=access; ! No 'read/write permission' 12=perm; ! No permission 13=not-member; ! Not member in conf 14=no-such-text; ! No such global text-no, or no access 15=text-zero; ! Can't use text no 0 16=no-such-local-text;! No such local text-no 17=local-text-zero; ! Can't use local text no 0 18=bad-name; ! Too short or too long ! or contains illegal chars 19=index-out-of-range; 20=conf-exists; ! Already exists *21=pers-exists; ! Already exists 22=secret-public; ! Cannot be secret and !rd-prot 23=letter-box; ! Cannot change letter-box flag 24=ldb-err; ! Database is corrupted. 25=ill-misc; ! Illegal misc field. ! err-stat holds field no 26=illegal-info-type; ! Info-type parameter was illegal. ! This means that there is a ! bug in the client. 27=already-recipient; ! Already recipient to this text. 28=already-comment; ! Already comment to this text. 29=already-footnote; ! Already footnote to this text. 30=not-recipient; ! Not recipient 31=not-comment; ! Not comment to this text. 32=not-footnote; ! Not footnote to this text. 33=recipient-limit; ! Too many recipients 34=comm-limit; ! Too many comments 35=foot-limit; ! Too many footnotes 36=mark-limit; ! Too many marks. 37=not-author; ! Only the author may add footnotes or ! delete texts. 38=no-connect; ! Can't connect to specified server 39=out-of-memory; ! Couldn't get memory for result *40=server-is-crazy; ! Client can't understand server *41=client-is-crazy; ! Client thinks that server says it ! can't understand client. 42=undef-session; ! This session doesn't exist 43=regex-error; ! Regexp compilation failed 44=not-marked; ! Attempt to unmark an unmarked text 45=tempfail; ! Temporary failure. Try again later ) Nummer Felmeddelande Nummer Felmeddelande ------------------------------------------------------ 11 access 28 already-comment 29 already-footnote 27 already-recipient 18 bad-name 41* client-is-crazy 34 comm-limit 20 conf-exists 8 conf-zero 35 foot-limit 25 ill-misc 26 illegal-info-type 19 index-out-of-range 24 ldb-err 23 letter-box 17 local-text-zero 6 login 7 login-disallowed 5 long-str 36 mark-limit 38 no-connect 0 no-error 16 no-such-local-text 14 no-such-text 37 not-author 31 not-comment 32 not-footnote 2 not-impl 44 not-marked 13 not-member 30 not-recipient 3 obsolete 39 out-of-memory 12 perm 21* pers-exists 4 pwd 33 recipient-limit 43 regex-error 22 secret-public 40* server-is-crazy 45 tempfail 15 text-zero 9 undef-conf 10 undef-pers 42 undef-session ------------------------------------------------------ Asynkrona anrop När som helst kan servern skicka ut ett asynkront anrop. En klient behöver inte bry sig om dem. Det går bra att läsa undan dem när ett svar skall läsas. Asynkrona meddelanden börjar alltid med ":" och ett heltal som talar om hur många parametrar som kommer. Därefter kommer en selector och parametrarna. Precis som för ok- och error-return är där inget tomrum mellan ":" och första heltalet. I förklaringen nedan listas de asynkrona anropen i nummerordning, men en alfabetiskt sorterad lista följer strax därpå. asynk-meddelande ::= ( ":"; antal-params:INTEGER; meddelande : SELECTION ( 0=new-text ( text-no : Text-No; text-stat : Text-stat ) ! En ny text har skapats. ; 1=i-am-off ( person : Pers-No; ) ! Används ej längre. Ersatt av anrop 13, som ! anger sessionsnummer i stället för personnummer. ; 2=i-am-on-obsolete ( person : Pers-No; conference : Conf-No; what-am-i-doing : HOLLERITH; ) ! Används ej längre. Ersatt av anrop 6. ; 3=conf-deleted ! Ännu ej implementerat. ; 4=conf-created ! Ännu ej implementerat. ; 5=new-name ( conf-no : Conf-No; old-name : HOLLERITH; new-name : HOLLERITH; ) ! Konferens (eller Person) har bytt namn. ; 6=i-am-on ( info : Who-Info; ) ! Innehåller ett Who-Info när någon byter konferens eller ! "what-am-i-doing". ; 7=sync-db ! Databasen synkas. ; 8=leave-conf ( conf-no : Conf-No; ) ! Skickas när någon utesluter aktuell Person från ! mötet conf-no och personen var närvarnade i mötet. ; 9=login ( pers-no : Pers-No; session-no : Session-No; ) ! Innehåller info när någon loggar in. ; 10=broadcast ( sender : Pers-No; message : HOLLERITH; ) ! Används ej längre. Ersatt av anrop 12, med recipient=0. ; 11=rejected-connection ! Asynkrona anropet nummer 11 betyder att någon har ! misslyckats logga in, eftersom servern inte har fler ! lediga förbindelser. Den ansvarskännande användaren ! kan nu välja att logga ut för att bereda plats. ; 12=send-message ( recipient : Conf-No; sender : Pers-No; message : HOLLERITH; ) ! Om argumentet recipient är noll (0) i asynkrona anropet ! nummer 12, så är meddelandet riktat till alla inloggade. ! Det är ännu inte möjligt att rikta ett meddelande till ! en viss session. Om recipient är ett möte så har ! meddelandet skickats till alla medlemmar i mötet. ; 13=logout ( pers-no : Pers-No; session-no : Session-No; ) ! Personens pers-no session session-no har loggat ut. ; ) ) En asterisk (*) efter numret i tabellen nedan anger att det asynkrona anropet ersatts av något annat. Se ovan under respektive anrop för närmare beskrivning. Nr Asynkront anrop Nr Asynkront anrop ------------------------------------------------------ 10* broadcast 9 login 4 conf-created 13 logout 3 conf-deleted 5 new-name 1* i-am-off 0 new-text 6 i-am-on 11 rejected-connection 2* i-am-on-obsolete 12 send-message 8 leave-conf 7 sync-db ------------------------------------------------------ RPC-anrop Klienten skickar RPC-anrop med parametrar till servern. Servern svarar endera med ett felmeddelande (se ovan i avsnitten Dialog och Felkoder) eller med ett returvärde. Nedan ges BNF-grammatiken för de datatyper som används i parametrar och returvärden. RPC-anropen listas i alfabetisk ordning, men en numeriskt sorterad lista följer strax efteråt. För varje anrop anges om det är OBSOLETE, RECOMMENDED eller EXPERIMENTAL. Anrop i klassen O ska inte användas, och anrop i klassen E bör bara användas efter samråd med LysKOM-kommittén. Följande information saknas i listan nedan: - vilka felkoder som kan returneras - om man måste vara inloggad för att få utföra anropet - vilka privilegiebittar man behöver för att få utföra anropet - vid vilken protokollnivå som anropet infördes commands : RPC ( ! Anropsnummer och -namn ! Datayp för anropsparameter ! Datatyp för returvärde 32=add-comment ( comment : Text-No; ! RECOMMENDED comment-to : Text-No; ) ; ! Används för att lägga till en kommentarslänk i efterskott. ! Lägger även till informationen om vem som lade till ! kommentarslänken och när. 37=add-footnote ( footnote : Text-No; ! RECOMMENDED footnote-to : Text-No; ) ; ! Används för att lägga till en fotnotslänk i efterskott. ! Bara författaren till de två inläggen får göra detta. 14=add-member ( conf-no : Conf-No; ! RECOMMENDED pers-no : Pers-No; priority : INT8; where : INT16; ) ; ! Addera angiven person som medlem i angivet möte. ! Priority är prioriteten på läslistan (0-255). ! Where är placering på listan, 0 (noll) eller större ! RPC-anropet nummer 14 kan även användas senare för att ändra ! prioritet och plats på listan. 30=add-recipient ( text-no : Text-No; ! RECOMMENDED conf-no : Conf-No; type : Misc-Info; ) ; ! Type får endast vara recpt eller cc-recpt. 45=broadcast ( message : HOLLERITH; ) ! OBSOLETE ; ! Ett privilegierat anrop. Används ej längre. Ersätts av anrop 53. 3=change-name ( conf-no : Conf-No; ! RECOMMENDED new-name : HOLLERITH; ) ; ! Byter namn på angivet möte eller person. 4=change-what-i-am-doing ( what-am-i-doing : HOLLERITH; ) ! RECOMMENDED ; ! Den medskickade texten kommer att visas i vilka-listan, ! se även anropet nummer 51. 59=create-anonymous-text ( text : HOLLERITH; ! EXPERIMENTAL misc-info : ARRAY Misc-Info ) result : Text-No; ! create-anonymous-text-result returnerar text nummer noll vid fel. ! OBS! Endas Misc-Infos 0,1,2,4 kan anges. ! Detta anrop normalt menat för import av artiklar från ! andra källor (FTP, WWW, etc) och anses som experimentell. 10=create-conf ( name : HOLLERITH; ! RECOMMENDED type : Conf-Type; ) result : Conf-No; ! En ny konferens med angivet namn och typ skapas. ! Den skapade konferensens nummer returneras. 5=create-person ( name : HOLLERITH; ! RECOMMENDED passwd : HOLLERITH; ) result: Pers-No; ! En ny person skapas med angivet namn och lösenord. ! Den skapade personens personnummer returneras. Den ! nuvarande personen blir den skapade personens ! administratör. På de flesta LysKOM-servrar behöver man inte ! vara inloggad för att kunna skapa en person. 28=create-text ( text : HOLLERITH; ! RECOMMENDED misc-info : ARRAY Misc-Info ) result : Text-No; ! create-text-return returnerar text nummer noll vid fel. ! OBS! Endast Misc-Infos 0,1,2,4 kan anges. 11=delete-conf ( conf : Conf-No; ) ! RECOMMENDED ; ! Utplåna ett möte eller en person. 29=delete-text ( text: Text-No; ) ! RECOMMENDED ; 55=disconnect ( session-no : Session-No; ) ! RECOMMENDED ; ! Koppla ner angiven session. Man kan koppla ner sin egen ! session (även om man inte är inloggad) och alla andra ! sessioner där man är administratör för den inloggade personen. 42=enable ( ena-level : INT8; ) ! RECOMMENDED ; ! Sätter administratörsnivå. Noll (0) betyder återgå till ! oprivilegierad nivå. Administratörsnivån avgör hur av sina ! extra privilegier man vill utnyttja; alla kan sätta sin ! administratörsnivå till 255, men den som inte har någon ! privilegiebit satt har inngen glädje av att ändra sin ! administratörsnivå. 60=find-next-text-no ( start : Text-No; ) ! EXPERIMENTAL result : Text-No; ! Leta upp nästa textnummer, utgående från start, som man ! får läsa, oberoende av aktuell konferens. 61=find-previous-text-no ( start : Text-No; ) ! EXPERIMENTAL result : Text-No; ! Leta upp föregående textnummer, utgående från start, som man ! får läsa, oberoende av aktuell konferens. 70=get-client-name ( session : Session-No; ) ! RECOMMENDED result : HOLLERITH; ! Returnerar en sträng som beskriver klienten som används ! i session. Klientnamn sätts med anrop 69. 71=get-client-version ( session : Session-No; ) ! RECOMMENDED result : HOLLERITH; ! Returnerar versionen av klienten som används i session, ! i strängform. Klientversion sätts med anrop 69. 50=get-conf-stat ( conf-no : Conf-No; ) ! RECOMMENDED result : Conference; ! Returnera mötesstatus för angivet möte 13=get-conf-stat-old ( conf-no : Conf-No; ! OBSOLETE mask : INTEGER; ) result : Conference ! Används ej längre. Ersatt av anrop 50. 47=get-created-texts ( person : Pers-No; ! RECOMMENDED first : Local-Text-No; no-of-texts : INTEGER; ) result : Text-List; ! OBS! first har som domän personens egna skrivna texter. ! Om man vill veta vilka 30 senaste texter person 21 skrivit ! i godtyckligt möte, och personen skrivit totalt 150 texter, ! anropar man alltså get-created-texts(21, 121, 30). 36=get-info ! RECOMMENDED ; result : Info; ! Returnerar information om servern. 58=get-last-text ( before: Time; ) ! EXPERIMENTAL ; result : Text-No; ! Returnerar numret för texten som skapats närmast före ! tiden before. Texten är inte nödvändigtvis läsbar. Det är ! inte ens säkert att den existerar längre. 34=get-map ( conf-no : Conf-No; ! RECOMMENDED first-local-no : Local-Text-No; no-of-texts : INTEGER; ) result : Text-List; ! Översätter från lokala textnummer i angiven konferens till ! globala, som returneras. 23=get-marks ! RECOMMENDED ; Mark-List; 48=get-members ( conf : Conf-No; ! RECOMMENDED first : INT16; no-of-members : INT16; ) result : Member-List; ! Första medlemmen är nummer 0 46=get-membership ( person : Pers-No; ! RECOMMENDED first : INT16; no-of-confs : INT16; mask : BITSTRING (want-read-texts); ) result : Membership-List; ! Första konferensen är nummer 0. Om mask.want-read-texts är ! falsk (0) kommer innehållet i arrayen read-texts i de ! medlemskap som begärs inte att överföras (se definitionen av ! ARRAY ovan). 49=get-person-stat ( person : Pers-No; ) ! RECOMMENDED result : Person; ! Personstatusen för den angivna personen returneras. 6=get-person-stat-old ( person : Pers-No; ! OBSOLETE mask : INTEGER; ) result : Person; ! Används ej längre. Ersatt av anrop 49. 54=get-session-info ( session-no : Session-No; ) ! OBSOLETE result : Session-Info; ! Används ej längre. Ersatt av anrop 64. 64=get-session-info-ident ( session-no : Session-No; ) ! RECOMMENDED result : Session-Info-Ident; 25=get-text ( text : Text-No; ! RECOMMENDED start-char : INTEGER; end-char : INTEGER; ) result : HOLLERITH; ! Första tecknet i texten är 0. Använd LONG_MAX som end-char ! för att få hela texten, eller bättre: titta i textstatusen ! (anrop 26). 26=get-text-stat ( text : Text-No; ) ! RECOMMENDED result : Text-Stat; 35=get-time ! RECOMMENDED result : Time; ; ! Lokal tid enligt servern. 52=get-unread-confs ( pers-no : Pers-No; ) ! RECOMMENDED result : ARRAY Conf-No; ! Returnerar en lista på möten i vilka personen kan ha olästa. ! Det finns inga garantier för att det finns olästa i alla dessa ! möten men listan är i alla fall kortare än medlemsskapet. 75=get-version-info ! RECOMMENDED result : Version-Info; ! Hämta information om vilken protokollversion, ! serverprogramvara och version av serverprogramvaran som ! körs. 62=login ( person : Pers-No; ! RECOMMENDED passwd : HOLLERITH; visibility: BITSTRING ( is-invisible; ); ) ; ! is-invisible anges som 1 om sessionen inte ska synas. ! Används för externa leverantörer av texter till LysKOM, ! t.ex. mail. 0=login-old ( person : Pers-No; ! OBSOLETE passwd : HOLLERITH; ) ; ! Inte helt dött, men anrop 62 rekommenderas. 1=logout ! RECOMMENDED ; ! Anropet nummer 1 misslyckas aldrig. Detta loggar ut ! användaren, men sessionen är fortfarande uppkopplad. Anrop ! 62 kan sedan användas för att logga in igen. 68=lookup-conf ( name : HOLLERITH; ) ! OBSOLETE result : Conf-No-List; ! Expandera ett förkortat namn och returnera en lista ! med nummer på de möten som det kan vara. Det finns ännu ej ! någon ersättare för detta anrop; se anrop 12. 12=lookup-name ( name : HOLLERITH; ) ! OBSOLETE result : Conf-List-Old; ! Ersatt av anrop nummer 76. 67=lookup-person ( name : HOLLERITH; ) ! OBSOLETE result : Pers-List; ! Expandera ett förkortat namn och returnera en lista ! med nummer på de personer som det kan vara. Det finns ännu ! ej någon ersättare för detta anrop; se anrop 12. 76=lookup-z-name ( name : HOLLERITH; ! RECOMMENDED want_persons : BOOL; want_confs : BOOL; ) result : Conf_Z_Info-List; ! Expandera ett förkortat namn och returnera en lista med ! nummer, namn och typ på de möten/personer som det kan vara. ! Om want_persons är 0 kommer inga personer att personer att ! finnas i svaret; om want_confs är 0 finns inga möten i ! svaret. Detta anrop kan göras innan man är inloggad. 27=mark-as-read ( conference : Conf-No; ! RECOMMENDED texts : ARRAY Local-Text-No; ) ; 72=mark-text ( text : Text-No; ! RECOMMENDED mark-type : INT8; ) ; ! Sätter en markör på angiven text. Servern lagrar endast ! markörvärdet och tolkar det inte. 24=mark-text-old ( text : Text-No; ! OBSOLETE mark-type : INT8; ) ; ! Används ej längre. Använd anrop 72 och 73. 2=pepsi ( conference : Conf-No; ) ! RECOMMENDED ; ! Anropet nummer 2 används för att gå till det angivna mötet. ! Det engelska namnet är change conference. ! Namnet "Pepsi" hör till avdelningen mer krystade vitsar. 9=query-read-texts ( pers-no : Pers-No; ! RECOMMENDED conf-no : Conf-No; ) result : Membership; ! Man kan fråga efter olästa utan att logga in. 66=re-lookup-conf ( regexp : HOLLERITH; ) ! OBSOLETE result : Conf-No-List; ! Matcha en regexp enligt ed(1) och returnera en lista ! med nummer på de möten som det kan vara. Ersatt av anrop 74. 65=re-lookup-person ( regexp : HOLLERITH; ) ! OBSOLETE result : Pers-List; ! Matcha en regexp enligt ed(1) och returnera en lista ! med nummer på de personer som det kan vara. Ersatt av anrop ! 74. 74=re-z-lookup ( regexp : HOLLERITH; ! RECOMMENDED want_persons : BOOL; want_confs : BOOL; ) result : Conf-Z-Info-List; ! Matcha en regexp enligt ed(1) och returnera en lista ! med nummer, namn och typ på de möten och/eller personer som ! det kan vara. Om want_persons är 0 kommer inga personer att ! personer att finnas i svaret; om want_confs är 0 finns inga ! möten i svaret. Detta anrop kan göras innan man är inloggad. 53=send-message ( recipient : Conf-No; ! RECOMMENDED message : HOLLERITH; ) ; ! Om mottagaren är nummer noll, skickas meddelandet till ! samtliga inloggade personer. Detta ersätter anrop 45. ! Om mottagaren är ett mötesnummer, skickas meddelandet ! till alla medlemmar i mötet som är inloggade. Det går ! för tillfället inte att sända till enskilda sessioner. 69=set-client-version ( client-name : HOLLERITH; ! RECOMMENDED client-version : HOLLERITH; ) ; 21=set-conf-type ( conf-no : Conf-No; ! RECOMMENDED type : Conf-Type ) ; ! Mötet conf-no sätts till typen type. Man kan för närvarande ! ej ändra letterbox-bitten. 17=set-etc-motd ( conf-no : Conf-No; ! RECOMMENDED text-no : Text-No; ) ; ! Sätt lappen text-no på dörren till conf-no. ! Set-presentation och set-etc-motd trollar dessutom ! med fältet no-of-marks i textstatusen för den gamla ! och den nya presentationstexten. 22=set-garb-nice ( conf-no : Conf-No; ! RECOMMENDED nice : Garb-Nice; ) ; ! Inlägg i mötet conf-no sparas i nice dagar innan de raderas. 41=set-motd-of-lyskom ( motd : Text-No; ) ! RECOMMENDED ; ! Privilegierat anrop. ! Texten motd sätts som ny message-of-the-day i LysKOM. 8=set-passwd ( person : Pers-No; ! RECOMMENDED old-pwd : HOLLERITH; new-pwd : HOLLERITH; ) ; ! Ge personen ett nytt lösenord. Old-pwd är det (gamla) ! lösenordet för personen som gör RPC-anropet (inte ! nödvändigt samma som anges av första argumentet). 19=set-permitted-submitters ( conf-no : Conf-No; ! RECOMMENDED perm-sub : Conf-No; ) ; ! Om perm-sub är noll (0) har alla rätt att skriva i conf-no. ! Annars har endast medlemmar i perm-sub rätt att skriva ! inlägg i mötet. perm-sub kan vara en person eller ett möte. ! Om någon som inte har rättighet skriver ett inlägg till ! mötet skickas inlägget automatiskt till supermötet (se 20). 16=set-presentation ( conf-no : Conf-No; ! RECOMMENDED text-no : Text-No; ) ; ! Ändra presentationen för angivet möte eller person. ! Ange text-no 0 (noll) för att ta bort presentationen. ! Set-presentation och set-etc-motd trollar dessutom ! med fältet no-of-marks i textstatusen för den gamla ! och den nya presentationstexten. 7=set-priv-bits ( person : Pers-No; ! RECOMMENDED privileges : Priv-Bits ) ; ! Ge eller ta några bittar för den angivna personen. 20=set-super-conf ( conf-no : Conf-No; ! RECOMMENDED super-conf : Conf-No; ) ; ! Gör super-conf till supermöte (ej organisatör) för mötet ! conf-no. Om conf-no är skrivskyddat, så skickas eventuella ! brev vidare till supermötet. 18=set-supervisor ( conf-no : Conf-No; ! RECOMMENDED admin : Conf-No; ) ; ! Gör alla medlemmar i mötet admin till organisatörer ! för mötet conf-no. Admin är typiskt en persons brevlåda. 40=set-unread ( conference : Conf-No; ! RECOMMENDED no-of-unread : INTEGER; ) ; ! Endast läsa no-of-unread senaste i angivet möte. 57=set-user-area ( pers-no : Pers-No; ! RECOMMENDED user-area : Text-No; ) ; ! Angiven text används för att lagra angiven persons ! variabler. Hur detta går till borde kanske behandlas ! i ett separat kapitel. 44=shutdown-kom ( exit-val : INTEGER; ) ! RECOMMENDED ; ! Detta är ett privilegierat anrop. ! Sparar alla data och stänger av servern. exit-val ! används inte för tillfället. 33=sub-comment ( comment : Text-No; ! RECOMMENDED comment-to : Text-No; ) ; 38=sub-footnote ( footnote : Text-No; ! RECOMMENDED footnote-to : Text-No; ) ; 15=sub-member ( conf-no : Conf-No; ! RECOMMENDED pers-no : Pers-No; ) ; ! Uteslut person från angivet möte. 31=sub-recipient ( text-no : Text-No; ! RECOMMENDED conf-no : Conf-No; ) ; 43=sync-kom ! RECOMMENDED ; ! Detta är ett privilegierat anrop. Medför att LysKOM ! synkar sina databasfiler. 73=unmark-text ( text : Text-No; ) ! RECOMMENDED ; 56=who-am-i ! RECOMMENDED result : Session-No; ! Returnerar sessionsnummer för aktuell session. 51=who-is-on ! OBSOLETE result : Who-Info-List; ! Svaret är en lista med information om nu aktiva sessioner. ! Ersatt av anrop 63. 63=who-is-on-ident ! RECOMMENDED result : Who-Info-Ident-List; ! Svaret är en lista med information om nu aktiva sessioner. 39=who-is-on-old ! OBSOLETE result : Who-Info-List-Old; ! Används ej längre. Använd anrop 63. ) De anrop vars nummer i listan nedan följs av en asterisk (*) är ersatta av modernare varianter. Nummer RPC-Anrop Nummer RPC-Anrop ------------------------------------------------------ 0* login-old 39* who-is-on-old 1 logout 40 set-unread 2 pepsi 41 set-motd-of-lyskom 3 change-name 42 enable 4 change-what-i-am-doing 43 sync-kom 5 create-person 44 shutdown-kom 6* get-person-stat-old 45 broadcast 7 set-priv-bits 46 get-membership 8 set-passwd 47 get-created-texts 9 query-read-texts 48 get-members 10 create-conf 49 get-person-stat 11 delete-conf 50 get-conf-stat 12* lookup-name 51 who-is-on 13* get-conf-stat-old 52 get-unread-confs 14 add-member 53 send-message 15 sub-member 54 get-session-info 16 set-presentation 55 disconnect 17 set-etc-motd 56 who-am-i 18 set-supervisor 57 set-user-area 19 set-permitted-submitters 58 get-last-text 20 set-super-conf 59 create-anonymous-text 21 set-conf-type 60 find-next-text-no 22 set-garb-nice 61 find-previous-text-no 23 get-marks 62 login 24* mark-text-old 63 who-is-on-ident 25 get-text 64 get-session-info-ident 26 get-text-stat 65 re-lookup-person 27 mark-as-read 66 re-lookup-conf 28 create-text 67 lookup-person 29 delete-text 68 lookup-conf 30 add-recipient 69 set-client-version 31 sub-recipient 70 get-client-name 32 add-comment 71 get-client-version 33 sub-comment 72 mark-text 34 get-map 73 unmark-text 35 get-time 74 re_z_lookup 36 get-info 75 get_version_info 37 add-footnote 76 lookup_z_name 38 sub-footnote ------------------------------------------------------ Konstruerade datatyper Här definieras de datatyper som sedan används i RPC-anrop från klienten till servern och i asynkrona anrop från servern till klienten. Datatyperna listas i bokstavsordning. ! Pers-no and Conf-no are u_shorts in the same domain. Conf-No ::= INT16; Conf-No-List ::= ARRAY Conf-No; Conf-List ::= ARRAY ( conference : Conf-No; type : Conf-Type; ) ! Som svar på anrop 12 ges Conf-List-Old, som inte kan formuleras ! med den här BNF-grammatiken. Använd anrop 67 eller 68 i stället. ! Conf-List-Old: "3 { 3 45 62 } { 1001 0000 1001 }" ! Conf-List: "3 { 3 1001 45 0000 62 1001 }" Conf-Type ::= BITSTRING ( rd_prot; ! Kan vem som helst sätta sig själv som medlem? original; ! Kommentarer förbjudna? secret; ! Hemligt? Hemliga personer måste logga in med nummer. letterbox; ! Brevlåda? ) Conf-Z-Info ::= ( name : HOLLERITH; type : Conf-Type; conf_no : Conf-no; ) Conf-Z-Info-List ::= ARRAY Conf-Z-Info; Conference ::= ( name : HOLLERITH; type : Conf-Type; creation-time : Time; last-written : Time; creator : Pers-No; presentation : Text-No; supervisor : Conf-No; permitted-submitters : Conf-No; ! Noll betyder alla får skriva. super-conf : Conf-No; ! Noll betyder författaren själv. msg-of-day : Text-No; ! Lapp på dörren. nice : Garb-Nice; no-of-members : INT16; first-local-no : Local-Text-No; ! Äldsta existerande text. no-of-texts : INTEGER; ! Antal existerande texter. ) Garb-Nice ::= INTEGER; ! Antal dagar. Info ::= ( version : INTEGER; conf-pres-conf : Conf-No; ! Mötet Pres (nya) möten pers-pres-conf : Conf-No; ! Mötet Pres (nya) medlemmar motd-conf : Conf-No; ! Mötet Lappar på dörren kom-news-conf : Conf-No; ! Mötet Nyheter om LysKOM motd-of-lyskom : Text-No; ! Bör visas vid login ) ! kom-types.h defines Info-Datum as the tail in Misc-Info ! kom-types.h defines Info-Type as the selector in Misc-Info Local-Text-No ::= INTEGER; Mark ::= ( text-no : Text-No; type : INT8 ) ! Servern ger sig inte på att tolka markeringstypen, ! det är helt upp till klienten. Mark-List ::= ARRAY Mark; Member ::= Pers-No; Member-List ::= ARRAY Member; Membership ::= ( last-time-read : Time; conference : Conf-No; priority : INT8; last-text-read : Local-Text-No; read-texts : ARRAY Local-Text-No; ) Membership-List ::= ARRAY Membership; Misc-Info ::= SELECTION ( 0=recpt recipient : Conf-No; ! Mottagare 1=cc-recpt cc-recipient : Conf-No; ! Extra kopia 2=comm-to comment-to : Text-No; ! Kommentar till 3=comm-in commented-in: Text-No; ! Kommentar i 4=footn-to footnote-to : Text-No; ! Fotnot till 5=footn-in footnoted-in : Text-No; ! Fotnot i 6=loc-no local-no : Local-Text-No ! Lokalt textnummer 7=rec-time received-at : Time; ! Mottaget tid 8=sent-by sender : Pers-No; ! Sänt av 9=sent-at sent-at : Time; ! Sänt när 10=x-author TBD : INTEGER; ! Ej implementerat 11=x-person TBD : INTEGER; ! Ej implementerat 12=x-recpt TBD : INTEGER; ! Ej implementerat 13=x-text TBD : INTEGER; ! Ej implementerat 14=x-system TBD : INTEGER; ! Ej implementerat ) ! Obs: 10-14 sänds ej av servern, men klienter bör förbereda ! sig på att ta emot dem i framtiden. Pers-List ::= ARRAY Pers-No; Pers-No ::= Conf-no; Person ::= ( username : HOLLERITH; ! E-mail adress privileges : Priv-Bits; flags : Personal-Flags; last-login : Time; ! Eller logout? user-area : Text-No; total-time-present : INTEGER; ! I sekunder sessions : INTEGER; created-lines : INTEGER; created-bytes : INTEGER; read-texts : INTEGER; no-of-text-fetches : INTEGER; created-persons : INT16; created-confs : INT16; first-created-local-no : INTEGER; ! Första i personens sekvensnumrering no-of-created-texts : INTEGER; ! Antal skapade texter. no-of-marks : INT16; no-of-confs : INT16; ) Personal-Flags ::= BITSTRING ( unread-is-secret; ! Värdet 1 betyder att antalet olästa texter hålls hemligt flg2; flg3; flg4; flg5; flg6; flg7; flg8; ) ! Se avsnittet ovan om säkerhetsnivåer och privilegiebittar. Priv-Bits ::= BITSTRING ( wheel; admin; statistic; create_pers; create_conf; change_name; flg7; flg8; flg9; flg10; flg11; flg12; flg13; flg14; flg15; flg16; ) ! Session-Info är väldigt likt Who-Info. Session-Info ::= ( person : Pers-No; working-conference : Conf-No; session : Session-No; what-am-i-doing : HOLLERITH; username : HOLLERITH; ! user@host idle-time : INTEGER; ! Sekunder sedan senaste anrop connection-time : Time; ! Tid och datum för uppkoppling ! Detta är ej detsamma som login-tid ) Session-Info-Ident ::= ( person : Pers-No; working-conference : Conf-No; session : Session-No; what-am-i-doing : HOLLERITH; username : HOLLERITH; ! user@host (det som klienten skickade ! vid uppkopplingen). hostname : HOLLERITH; ! Host som uppkopplingen kom från. ! Om en mux används är detta adressen ! till muxen. ident-user : HOLLERITH; ! User enligt Ident (RFC-931). idle-time : INTEGER; ! Sekunder sedan senaste anrop connection-time : Time; ! Tid och datum för uppkoppling ! Detta är ej detsamma som login-tid ) ! Sessionsnummer är unika för varje session. En person kan ha ! fler än en session aktiva samtidigt. Sessionsnummer tilldelas ! från 1 och uppåt och de återanvänds aldrig under serverns ! livstid. Se också Who-Info-List. Session-No ::= INTEGER; Text-List ::= ( first-local-no : Local-Text-No; texts : ARRAY Text-No; ) Text-No ::= INTEGER; Text-Stat ::= ( creation-time : Time; author : Pers-No; no-of-lines : INTEGER; no-of-chars : String-Size; no-of-marks : INT16; misc-info : ARRAY Misc-Info; ) ! UNIX struct tm. Ingen tidszon. Time ::= ( seconds : INTEGER; ! 0 ... 59 minutes : INTEGER; ! 0 ... 59 hours : INTEGER; ! 0 ... 23 mday : INTEGER; ! 1 ... 31 month : INTEGER; ! jan = 0 ... dec = 11 year : INTEGER; ! Sedan 1900 weekday : INTEGER; ! sön = 0 ... lör = 6 yearday : INTEGER; ! 0 ... 365 isdst : INTEGER; ! positivt = sommartid, 0 = normaltid ) Who-Info-Old ::= ( person : Pers-No; what-am-i-doing : HOLLERITH; working-conference : Conf-No; ) Who-Info-List-Old ::= ARRAY Who-Info-Old; Who-Info ::= ( person : Pers-No; working-conference : Conf-No; session : Session-No; what-am-i-doing : HOLLERITH; username : HOLLERITH; ! user@hostname ) Who-Info-List ::= ARRAY Who-Info; Who-Info-Ident ::= ( person : Pers-No; working-conference : Conf-No; session : Session-No; what-am-i-doing : HOLLERITH; username : HOLLERITH; ! user@hostname hostname : HOLLERITH; ! Host som uppkopplingen kom från ident-user : HOLLERITH; ! User enligt Ident (RFC-931) ) Who-Info-Ident-List ::= ARRAY Who-Info-Ident; Exempel Nedan ett exempel från en verklig LysKOM-session. Kommentarer har jag gett med "!" som i grammatiken. Exemplet är gammalt och innehåller en del detaljer som senare tagits ur bruk, men det ger ändå en ide om hur det råa protokollet ser ut. $ telnet laila 4894 Trying 130.236.254.12 ... Connected to laila.lysator.liu.se. Escape character is '^]'. A8Haronsson ! Jag kör protokoll A LysKOM ! LysKOM svarar 1 12 13HLars Aronsson ! lookup-name (OBSOLETE) =1 2 { 8 38 } { 1001 1001 } ! Person 8 eller Person 38 :3 2 21 7 0H ! Person 21 gick till möte 7 :1 1 56 ! Person 56 loggade just ut 2 0 8 8H******** ! login-old Person 8 med password :3 2 8 0 0H ! Person 8 loggade just in =2 ! login OK 3 10 23HAntikommunistiskt Forum 0000 ! Jag skapar ett öppet möte =3 57 ! OK, möte 57 skapat 4 1 ! Jag loggar ut :1 1 8 ! Person 8 loggade just ut =4 ! logout OK