Commit ed2bc376 authored by David Byers's avatar David Byers
Browse files

Documented Version-Info and a few more calls

parent a46310d5
\input texinfo @c -*-texinfo-*-
@c $Id: Protocol-A.texi,v 1.3 1996/06/14 16:14:32 byers Exp $
@c $Id: Protocol-A.texi,v 1.4 1996/07/27 11:43:04 byers Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -7,7 +7,7 @@
@c %**end of header
@iftex
@parindent 0pt
@font@tensltt=cmsltt12
@font@tensltt=cmsltt10
@begin tex
\global\def\rett#1{{\let\t\sltt\tt #1}}
\global\def\sltt#1{{\fam\ttfam\tensltt\let\t\rett #1}}
......@@ -18,7 +18,7 @@
@ifinfo
This is the specification of LysKOM Protocol A v. 9.0
Copyright @copyright{} 1995 Lysator ACS.
Copyright @copyright{} 1995, 1996 Lysator ACS.
Permission is granted to make and distribute verbatim copies of this
specification provided the copyright notice and this permission notice
......@@ -785,8 +785,9 @@ type of the array elements.
Arrays are transmitted as an @code{<n> @{ <element> <element> ... @}} where
@code{<n>} is the number of elements and each @code{<element>} is an element
of the array. A special case is when the array is empty, in which case it is
transmitted as @code{0 *}.
of the array. A special case is when the array is empty, in which case
the server transmits it as @code{0 *}. Note that the client must always
transmit empty arrays as @code{0 @{ @}}.
In some calls the client can ask the server not to send the array contents,
only its length. In these cases the array is transmitted as @code{<n> *} where
......@@ -1120,16 +1121,23 @@ The number of days an article should be kept before being removed from the confe
@example
Info ::=
( version : INT32;
conf-pres-conf : Conf-No;
pers-pres-conf : Conf-No;
motd-conf : Conf-No;
kom-news-conf : Conf-No;
motd-of-lyskom : Text-No;
( version : INT32;
conf-pres-conf : Conf-No;
pers-pres-conf : Conf-No;
motd-conf : Conf-No;
kom-news-conf : Conf-No;
motd-of-lyskom : Text-No;
)
Version-Info ::=
( protocol-version : INT32;
server-software : HOLLERITH
software-version : HOLLERITH
)
@end example
This data type contains information about the LysKOM server. The fields are
These data types contain information about the LysKOM server. The fields
of @code{Info} are
@table @code
@item version
......@@ -1150,6 +1158,18 @@ The number of an article to display when LysKOM is entered or zero if there is
none.
@end table
The fields of @code{Version-Info} are:
@table @code
@item protocol-version
The version of protocol A the server is using. This may be used to
ascertain which calls are available.
@item server-software
Human-readable name of the server software.
@item software-version
Human-readable name of the server software version.
@end table
@subsection Person Status Types
......@@ -1897,10 +1917,10 @@ create conferences (@pxref{Security}).
@example
1 50 8
@t{%1 9 0}
1 10 13HInlägg åt mig 00001000
1 10 13HInlägg @}t mig 00001000
@t{=1 8}
1 50 8
@t{=1 13HInlägg åt mig 0000
@t{=1 13HInlägg @}t mig 0000
43 9 17 14 5 96 5 165 1
43 9 17 14 5 96 5 165 1
5 0 5 0 5 0 77 0 1 0}
......@@ -1922,10 +1942,10 @@ create conferences (@pxref{Security}).
This example creates a new conference named
@ifinfo
``Inlägg åt
``Inlägg @}t
@end ifinfo
@iftex
``Inl@"a{}gg @aa{}t
``Inl@"a{}gg @}t
@end iftex
mig''@footnote{This conference is a standard Lysator conference. It's
all Padrone's fault.} which accepts all users as members and accepts
......@@ -1952,7 +1972,7 @@ delete it. @b{[Is it possible to delete mailboxes?]}
1 11 7
@t{=1}
1 50 7
@i{%1 9 0}
@t{%1 9 0}
@end example
This example shows the successful deletion of conference number seven.
......@@ -2002,11 +2022,11 @@ member of the conference.
@example
1 46 119 0 10 0
@t{=1 @t{1} @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
1 14 1 119 250 0
@t{=1}
1 46 119 0 10 0
@t{=1 @t{2} @{ @t{52 30 14 11 5 96 2 162 1 1 250 0 0 *}
@t{=1 2 @{ 52 30 14 11 5 96 2 162 1 1 250 0 0 *
49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
@end example
......@@ -2031,12 +2051,12 @@ memberships.
@i{Example:}
@example
1 46 5 0 100 0
@t{=1 @t{2} @{ @t{44 14 19 10 5 96 1 161 1 1 0 0 0 *}
@t{=1 2 @{ 44 14 19 10 5 96 1 161 1 1 0 0 0 *
49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
1 15 1 5
@t{=1}
1 46 5 0 100 0
@t{=1 @t{1} @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * @}}
@end example
This example shows how person 5 is removed from conference one. The
......@@ -2065,14 +2085,14 @@ count on presentation texts.
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 @t{0} 5 0 5 0 77 1 1 0}
5 0 5 0 5 0 77 1 1 0}
1 16 6 1
@t{=1}
1 50 6
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 @t{1} 5 0 5 0 77 1 1 0}
5 1 5 0 5 0 77 1 1 0}
@end example
This example shows how the presentation of person 6 is being changed. To
......@@ -2103,14 +2123,14 @@ as @ref{set-presentation}.
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 0 5 0 5 @t{0} 77 1 1 0}
5 0 5 0 5 0 77 1 1 0}
1 17 6 1
@t{=1}
1 50 6
@t{=1 11HDavid Byers 1001
26 15 11 9 5 96 0 160 1
26 15 11 9 5 96 0 160 1
5 0 5 0 5 @t{1} 77 1 1 0}
5 0 5 0 5 1 77 1 1 0}
@end example
This example shows how text number one is used as the message of the day
......@@ -2139,14 +2159,14 @@ Typically, but not always, @code{admin} will be a letterbox.
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 @t{0} 0 0 0 77 1 1 1}
0 0 0 0 0 0 77 1 1 1}
1 18 4 6
@t{=1}
1 50 4
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 @t{6} 0 0 0 77 1 1 1}
0 0 6 0 0 0 77 1 1 1}
@end example
This example makes the members of conference six supervisors of
......@@ -2180,14 +2200,14 @@ the super-conference instead.
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 6 @t{0} 0 0 77 1 1 1}
0 0 6 0 0 0 77 1 1 1}
1 19 4 1
@t{=1}
1 50 4
@t{=1 17HNyheter om LysKOM 0000
48 11 17 13 8 91 5 255 1
15 12 11 9 5 96 0 160 1
0 0 6 @t{1} 0 0 77 1 1 1}
0 0 6 1 0 0 77 1 1 1}
@end example
This example shows how all members of conference one are given
......@@ -2219,14 +2239,188 @@ set to conference 8. the calls to @ref{get-conf-stat} demonstrate the
change in the conference structure.
@node set-conf-type, set-garb-nice, set-super-conf, Protocol Requests
@subsection set-conf-type (1) Recommended
@example
set-conf-type [21] (( conf-no : Conf-No;
type : Any-Conf-Type ))
-> ( );
@end example
Sets the conference type of conference @code{conf-no} to @code{type}.
Before protocol version 8, @code{type} could only be four bits. Starting
with protocol version 8, either a four-bit conference type or an
@code{Extended-Conf-Type} is allowed.
@example
1 78 4
@t{=1 17HNyheter om LysKOM 00001000 1 77}
1 21 4 00000000
@t{=1}
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 77}
@end example
This example show a user removing the anarchy bit from conference four.
The @ref{get-uconf-stat} call shows all eiht bits of the conference type
before and after the set-conf-type call.
@node set-garb-nice, get-marks, set-conf-type, Protocol Requests
@subsection set-garb-nice (1) Recommended
@example
set-garb-nice [22] (( conf-no : Conf-No;
nice : Garb-Nice ))
-> ( );
@end example
Sets the expiration time for articles in conference @code{conf-no} to
@code{nice} days. An article that is older than the maximum expiration
time of each conference it is sent to may be deleted by the LysKOM
server unless it has marks.
@example
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 77}
1 22 4 7
@t{=1}
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 7}
@end example
This example shows the expiration time of conference four being lowered
from 77 to just seven days.
@node get-marks, mark-text-old, set-garb-nice, Protocol Requests
@subsection get-marks (1) Recommended
@example
set-marks [23] ( )
-> ( result : Mark-List );
@end example
This call returns the list of marks the current user has set.
@example
1 23
@t{=1 3 @{ 13020 100 13043 95 12213 95 @}}
@end example
In this example, the current user has three marks, one on text 13020
with mark type 100, one on text 13042 with mark type 95 and one on text
12213 with mark type 95. The maximum number of marks may be arbitrarily
limited in the LysKOM server.
@node mark-text-old, get-text, get-marks, Protocol Requests
@subsection mark-text-old (1) Obsolete
@example
mark-text-old [24] (( text : Text-No;
mark-type : INT8 ))
-> ( );
@end example
This call has been replaced by @ref{mark-text} and @ref{unmark-text} and
should no longer be used.
@node get-text, get-text-stat, mark-text-old, Protocol Requests
@subsection get-text (1) Recommended
@example
get-text [25] (( text : Text-No;
start-char : INTEGER;
end-char : INTEGER; ))
-> ( result : HOLLERITH );
@end example
Retreive text number @code{text} from the LysKOM database, starting at
position @code{start-char} and ending at position @code{end-char}. The
first character in the text is numbered 0 and the last can be retrieved
using @ref{get-text-stat}. It is also permitted to request a character
position beyond the actual end of the text, in which case as much text
as is available will be returned.
@example
1 25 100 0 32766
@t{=1 25HYawn^JNothing is happening}
2 25 100 5 32766
@t{=2 20HNothing is happening}
3 25 100 0 3
@t{=3 4HYawn}
@end example
In this example, text 100 is requested three times, first from position
0 to position 32766, then from position 5 to position 32766 and finally
from position 0 to position 4. The first reply contains the entire text,
the following two contain only the requested portion.
@node get-text-stat, mark-as-read, get-text, Protocol Requests
@subsection get-text-stat (1) Recommended
@example
get-text-stat [26] ( text-no : Text-No )
-> ( result : Text-Stat );
@end example
Get information about text number @code{text-no}. The text-stat contains
information about the size of the text, its recipients, comments, author
and more.
@example
1 26 100
=1 7 35 16 15 6 96 1 196 1 14 1 22 1
@t{7 @{ 0 7 6 85 0 15 6 1
8 13 9 12 37 16 15 6 96 1 196 1
3 311 @}}
@end example
In this example, text number 100 was created by person 7 at
approximately 4:35PM on July 15 1996. Its recipients are conferences 7
and 15, and it was sent to conference 15 by person 13 at 16:37 on the
day it was created. The text has a single comment: text 311.
@node mark-as-read, create-text, get-text-stat, Protocol Requests
@subsection mark-as-read (1) Recommended
@example
mark-as-read [27] (( conference : Conf-No;
text : ARRAY Local-Text-No; ))
-> ( );
@end example
Marks text @code{text} in confernece number @code{conference} as read
for the current user. This call updates the membership record for the
user.
@example
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 240 0 *}
1 78 7
@ifinfo
@t{=1 13HInlägg @}t mig 00001000 241 1}
@end ifinfo
@iftex
@t{=1 13HInl@"a{}gg @}t mig 00001000 241 1}
@end iftex
1 27 7 1 @{ 241 @}
@t{=1}
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 241 0 *}
@end example
This example shows person 6 marking local text number 241 in conference
7 as read. In the firs query-read-texts call the person has read local
text 240, but nothing higher. The mark-as-read call is reflected in the
second query-unread-texts call, where the user is seen to have read text
241 in conference 7.
To mark a global text number as read it is necessary to translate it
into local text numbers by looking as the Misc-Info List in the
Text-Stat and calling mark-as-read once for each recipient.
@node create-text, delete-text, mark-as-read, Protocol Requests
@node delete-text, add-recipient, create-text, Protocol Requests
@node add-recipient, sub-recipient, delete-text, Protocol Requests
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment