prot-A.txt

Hej Emacs!  Denna fil är skriven med hjälp av -*- outline -*-.

			   LysKOM-Projektet
		   --------------------------------
      Specifikation 8.0 av protokoll A mellan klient och server
		   --------------------------------
	     av Lars Aronsson <Aronsson@Lysator.LiU.SE>,
		      Pell <pell@lysator.liu.se>
	      och Per Cederqvist <ceder@lysator.liu.se>


* Innehållsförteckning

	Innehållsförteckning
	LysKOM
	Den här texten
	Dokumenthistorik
	Protokollhistorik
	Filer
	Underliggande protokoll
	Abstrakt syntaxnotation
	Grundläggande datatyper
	Dialog
	Säkerhetsnivåer och privilegiebittar
	Felkoder
	Asynkrona anrop
	RPC-anrop
	Konstruerade datatyper
	Exempel

* 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 kom@lysator.liu.se. 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.

* Dokumenthistorik

** 9.0: 1996-06-09

Protokollversion 9.  Distribueras med lyskomd 1.9.0

** 8.0: 1995-11-08

Protokollversion 8.  Distribueras med lyskomd 1.8.0.

** 7.1: 1995-01-08.

Protokollhistorik och dokumenthistorik tillagda av Per Cederqvist.
Outline-mode används för att göra dokumentet mer hanterbart.
Distribueras med lyskomd 1.7.1.

** 7.0: 1994-12-31.

Den första specifikationen med ett versionsnummer.  Alla anrop som
tillkommit sedan 1991-06-25 dokumenterades.  Pell och ceder gjorde
jobbet.  Distribueras med lyskomd 1.7.0.

** ?.?: 1993-05-19.

Linus Tolke skrev kommentarer för några anrop som saknade förklaring.

** ?.?: 1992-07-06.

Linus Tolke konverterade dokumentet till ISO-8859-1.

** ?.?: 1991-08-12.

ceder började versionshantera detta dokument.

** ?.?: 1991-06-25.

Lars Aronsson dokumenterade det protokoll som kördes då.

* Protokollhistorik

Här dokumenteras kortfattat vad som har hänt med protokollet.
Meningen med denna historik är dels att klientskrivare ska kunna
skriva klienter som kan hantera gamla servrar, dels att dokumentera
historien.  För varje ny protokollversion anges de nya anrop som
tillkommit, vilka anrop som fått utökad funktionalitet, och om något
annat hänt.

Eftersom version 6 och tidigare saknade anropet 75=get-version-info
anges även vilken lyskomd-version som var den första att implementera
protokollet.

** Protokollversion 8 (först implementerat i lyskomd 1.8.0)

*** Utökad funktionalitet:
	30=add-recipient: Kan ändra recpt till cc_recpt och vice versa.
	21=set-conf-type: Kan ta både Conf-Type och Extended-Conf-Type
	10=create-conf: Kan ta både Conf-Type och Extended-Conf-Type

*** Nya anrop:
	77=set-last-read
        78=get-uconf-stat

** Protokollversion 7 (först implementerat i lyskomd 1.7.0).

*** Nya anrop: 
	74=re-z-lookup
	75=get_version_info
	76=lookup_z_name
*** Utökad funktionalitet:
	53=send-message: Mottagaren kan nu vara ett möte.
*** Övrigt:
	Det asynkrona meddelanded 1=i-am-off finns inte längre.

** Protokollversion 6 (först implementerat i lyskomd 1.4.0).

*** Nya anrop: 
	67=lookup_person
	68=lookup_conf
	69=set_client_version
	70=get_client_name
	71=get_client_version
	72=mark_text
	73=unmark_text

** Protokollversion 5 (först implementerat i lyskomd 1.3.0).

*** Nya anrop:
	65=re_lookup_person
	66=re_lookup_conf

** Protokollversion 4 (först implementerat i lyskomd 1.1.1).

*** Nya anrop: 
	62=login
	63=who_is_on_ident
	64=get_session_info_ident

** Protokollversion 3 (först implementerat i lyskomd 1.1.0).

*** Nya anrop:
	61=find_previous_text_no
	60=find_next_text_no
	59=create_anonymous_text
	58=get_last_text

** Protokollversion 2 (först implementerat i lyskomd 0.30.0).

*** Nya anrop: 
	57=set_user_area

** Protokollversion 1 (först implementerad i lyskomd 0.29.2)

Nya anrop: alla från nummer 0-56.  Det fanns tidigare versioner av
lyskomd som implementerade delmängder av protokollet, men vi har inte
längre kvar tillräckligt mycket loggfiler för att kunna återskapa de
protokoll som implementerades.

* 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). Alternativ betecknas med "|" (som i egrep) 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 NUL (0x0).  Undvik att skicka NUL. I
meddelanden från server till klient åtskiljs dataelementen av exakt
ett mellanslag och varje meddelande avslutas alltid med line-feed.

** Heltal

INT32, INT16, INT8 samt BOOL är icke-negativa heltal som skall rymmas
på 32, 16, 8 och 1 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.

** Strängar

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.

** Bit-strängar

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"
	)

** Arrayer

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

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

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. Dessutom anges den protokollversion där anropet
infördes. Selectornumret skickas bara tillsammans med frågan. Exempel:

	phrases : RPC (
	  1=cost(6) inventory:INTEGER;	price:INTEGER;
	  2=time(6) timezone:INTEGER;	hours:INTEGER;
	  3=name(7) ;			name:HOLLERITH;
	)
	! t.ex. "1 23"->"498" "3"->"4HLars" "2 1"->"1430"
	! cost och time infördes i protokollversion 6, medan
	! name infördes i protokollversion 7.

** Struct/record

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

** RPC-anrop i alfabetisk ordning

commands : RPC (
  ! Anropsnummer och -namn(protokollversion)
	! Datayp för anropsparameter
	! Datatyp för returvärde
	
  32=add-comment(1)	( 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(1)	( 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(1)	( 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(1)	( text-no : Text-No;		! RECOMMENDED
			  conf-no : Conf-No;
			  carbon_copy : BOOL;    )
	;
	! Om carbon_copy är sann kommer en cc-recpt att skapas, annars
	! en recpt.  (I tidigare specar angavs det tredje argumentet
	! som "type : Misc-Info" men det var felaktigt.  Det har
	! alltid varit strängen "0" eller "1" som har överförts, och
	! beskrivningen blir snyggare om det tredje argumentet
	! betraktas som en BOOL).

  45=broadcast(1)		( message : HOLLERITH; )	! OBSOLETE
	;
	! Ett privilegierat anrop. Används ej längre. Ersätts av anrop 53.

   3=change-name(1)	( conf-no : Conf-No;		! RECOMMENDED
			  new-name : HOLLERITH; )
	;
	! Byter namn på angivet möte eller person.

   4=change-what-i-am-doing(1) ( what-am-i-doing : HOLLERITH; ) ! RECOMMENDED
	;
	! Den medskickade texten kommer att visas i vilka-listan,
	! se även anropet nummer 51.

  59=create-anonymous-text(3)	( 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(1)	( name : HOLLERITH;		! RECOMMENDED
			  type : Any-Conf-Type;  )
	result : Conf-No;
	! En ny konferens med angivet namn och typ skapas.
	! Den skapade konferensens nummer returneras.

   5=create-person(1)	( 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(1)	( 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(1)	( conf : Conf-No; )		! RECOMMENDED
	;
	! Utplåna ett möte eller en person.

  29=delete-text(1)	( text: Text-No; )		! RECOMMENDED
	;

  55=disconnect(1)		( 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(1)		( 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(3)	( 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(3)	( 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(6)	( 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(6) ( 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(1)	( conf-no : Conf-No; )		! RECOMMENDED
	result : Conference;
	! Returnera mötesstatus för angivet möte
 
  78=get-uconf-stat(8)  ( conf-no : Conf-No; )		! EXPERIMENTAL
	result: UConference
	! Returnerar de delar av mötet som lyskomd alltid har i minnet
	! och är därför snabbare än get-conf-stat

  13=get-conf-stat-old(1) ( conf-no : Conf-No;		! OBSOLETE
			  mask : INTEGER;	 )
	result : Conference
	! Används ej längre. Ersatt av anrop 50.

  47=get-created-texts(1) ( 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(1)						! RECOMMENDED
	;
	result : Info;
	! Returnerar information om servern.

  58=get-last-text(3)	( 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(1)	( 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(1)						! RECOMMENDED
	;
	Mark-List;

  48=get-members(1)	( conf : Conf-No;		! RECOMMENDED
			  first : INT16;
			  no-of-members : INT16; )
	result : Member-List;
	! Första medlemmen är nummer 0

  46=get-membership(1)	( 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(1)	( person : Pers-No; )		! RECOMMENDED
	result : Person;
	! Personstatusen för den angivna personen returneras.

   6=get-person-stat-old(1)	( person : Pers-No;	! OBSOLETE
				  mask : INTEGER;   )
	result : Person;
	! Används ej längre. Ersatt av anrop 49.

  54=get-session-info(1)	( session-no : Session-No; )	! OBSOLETE
	result : Session-Info;
	! Används ej längre. Ersatt av anrop 64.

  64=get-session-info-ident(4) ( session-no : Session-No; ) ! RECOMMENDED
	result : Session-Info-Ident;

  25=get-text(1)	( 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(1)	( text : Text-No; )		! RECOMMENDED
	result : Text-Stat;

  35=get-time(1)					! RECOMMENDED
	result : Time;
	;
	! Lokal tid enligt servern.

  52=get-unread-confs(1) ( 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(7)					! RECOMMENDED
	result : Version-Info;
	! Hämta information om vilken protokollversion,
	! serverprogramvara och version av serverprogramvaran som
	! körs.

   62=login(4)	( 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(1) ( person : Pers-No;			! OBSOLETE
		  passwd : HOLLERITH; )
	;
	! Inte helt dött, men anrop 62 rekommenderas.

   1=logout(1)						! 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(6)	( 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(1)	( name : HOLLERITH; )		! OBSOLETE
	result : Conf-List-Old;
	! Ersatt av anrop nummer 76.

  67=lookup-person(6)	( 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(7)   ( 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(1)	( conference : Conf-No;		! RECOMMENDED
			  texts : ARRAY Local-Text-No; )
	;

  72=mark-text(4)	( 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(1)	( text : Text-No;		! OBSOLETE
			  mark-type : INT8; )
	;
	! Används ej längre. Använd anrop 72 och 73.

   2=pepsi(1)	( 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(1)	( 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(5)	( 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(5) ( 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(7)	( 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(1)	( 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(6) ( client-name : HOLLERITH;	! RECOMMENDED
			  client-version : HOLLERITH; )
	;

  21=set-conf-type(1)	( conf-no : Conf-No;		! RECOMMENDED
			  type : Any-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(1)	( 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(1)	( conf-no : Conf-No;		! RECOMMENDED
			  nice : Garb-Nice;  )
	;
	! Inlägg i mötet conf-no sparas i nice dagar innan de raderas.

  79=set-info(9)  ( info : Info )                       ! RECOMMENDED
        ;
        ! Sätt information om servern. Serverns versionsnummer ignoreras,
        ! övriga fält sparas i databasen. Detta är ett priviligierat
        ! anrop.

  77=set-last-read(8)	( conference : Conf-No;		! EXPERIMENTAL
			  last-read : Local-Text-No; )
	;
	! Sätt last-read som senast lästa text i conference. Detta
	! anrop är ett alternativ till nr 40, set-unread.

  41=set-motd-of-lyskom(1) ( motd : Text-No; )		! RECOMMENDED
	;
	! Privilegierat anrop.
	! Texten motd sätts som ny message-of-the-day i LysKOM.

   8=set-passwd(1)	( 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(1) ( 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(1) ( 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(1)	( person : Pers-No;		! RECOMMENDED
			  privileges : Priv-Bits )
	;
	! Ge eller ta några bittar för den angivna personen.

  20=set-super-conf(1)	( 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(1)	( 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(1)	( conference : Conf-No;		! RECOMMENDED
			  no-of-unread : INTEGER; )
	;
	! Endast läsa no-of-unread senaste i angivet möte.

  57=set-user-area(2)	( 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(1)	( 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(1)	( comment : Text-No;		! RECOMMENDED
			  comment-to : Text-No; )
	;

  38=sub-footnote(1)	( footnote : Text-No;		! RECOMMENDED
			  footnote-to : Text-No; )
	;

  15=sub-member(1)		( conf-no : Conf-No;		! RECOMMENDED
			  pers-no : Pers-No; )
	;
	! Uteslut person från angivet möte.

  31=sub-recipient(1)	( text-no : Text-No;		! RECOMMENDED
			  conf-no : Conf-No; )
	;

  43=sync-kom(1)						! RECOMMENDED
	;
	! Detta är ett privilegierat anrop.  Medför att LysKOM
	! synkar sina databasfiler.

  73=unmark-text(6)	( text : Text-No; )		! RECOMMENDED
	;

  56=who-am-i(1)					! RECOMMENDED
	result : Session-No;
	! Returnerar sessionsnummer för aktuell session.

  51=who-is-on(1)					! OBSOLETE
	result : Who-Info-List;
	! Svaret är en lista med information om nu aktiva sessioner.
	! Ersatt av anrop 63.

  63=who-is-on-ident(4)					! RECOMMENDED
	result : Who-Info-Ident-List;
	! Svaret är en lista med information om nu aktiva sessioner.

  39=who-is-on-old(1)					! OBSOLETE
	result : Who-Info-List-Old;
	! Används ej längre. Använd anrop 63.
)

** RPC-anrop i nummerordning

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		77  set-last-read
	------------------------------------------------------


* 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 }"