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

New membership data type. Multiple bug fixes

parent 6fdcfb3c
1998-06-10 David Byers <davby@ida.liu.se>
* src/server/membership.c (sub_member): Return KOM_NOT_MEMBER for
secret memberships.
1998-06-08 David Byers <davby@ida.liu.se>
* src/server/membership.c (set_membership_type): New function.
* src/server/prot-a-output.c (prot_a_output_membership): Output
added_at.
(prot_a_output_member): Output added_at
* src/server/membership.c (do_add_member): Set added_at.
(get_members): Filter out added_at.
* src/server/memory.c (init_membership): Init added_at.
* src/server/ram-output.c (foutput_member_2): Added output of
added_at.
* src/server/ram-parse.c (fparse_member_2): Added parsing of added_at.
* src/include/kom-types.h: Added added_at to Membership och Member.
* src/server/ram-parse.c (fparse_membership_2): Added parsning of
added_at.
* src/server/ram-output.c (foutput_membership_2): Added output of
added_at.
Fri Jan 16 22:51:52 1998 David Byers <davby@litefix.ida.liu.se>
* src/include/kom-types.h (Aux_item_flags): Added dont_garb.
* src/server/text-garb.c (garb_text): Check dont_garb aux-item
flag.
Mon Sep 22 19:06:05 1997 David Byers <davby@litefix.ida.liu.se>
* src/server/cache-node.h: New flags: snapshot and synced.
......
#! /bin/sh
# From configure.in Revision: 1.41
# From configure.in Revision: 1.42
# Guess values for system-dependent variables and create Makefiles.
# Generated automatically using autoconf version 2.12
......
No preview for this file type
\input texinfo @c -*-texinfo-*-
@c $Id: Protocol-A.texi,v 1.6 1997/10/23 12:40:35 byers Exp $
@c $Id: Protocol-A.texi,v 1.7 1998/06/14 14:50:17 byers Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -172,15 +172,23 @@ Lars Aronsson documented the protocol that was in use at the time.
@item 95=modify-system-info
@item 96=query-predefined-aux-items
@item 97=set-expire
@item 98=query-read-texts
@item 99=get-membership
@item 100=add-member
@item 101=get-members
@end itemize
@item Removed Server Calls
@itemize @bullet
@item 5=create-person
@item 9=query-read-texts
@item 10=create-conf
@item 14=add-member
@item 26=get-text-stat
@item 28=create-text
@item 36=get-info-old
@item 46=get-membership-old
@item 48=get-members-old
@item 50=get-conf-stat
@item 59=create-anonymous-text
@end itemize
......@@ -191,6 +199,9 @@ Lars Aronsson documented the protocol that was in use at the time.
@item Aux-item-list
@item Conference
@item Info
@item Member
@item Membership
@item Membership-Type
@item Misc-info
@item Text-stat
@end itemize
......@@ -1283,7 +1294,7 @@ relating to information about active LysKOM sessions.
inherit;
secret;
hide-creator;
reserved1;
dont-garb;
reserved2;
reserved3;
reserved4;
......@@ -1329,6 +1340,8 @@ supervisors of the creator.
@item hide-creator
The item creator will be withheld from everyone but the item's creator
and supervisors of the creator.
@item dont-garb
The object the item is set on will not be garbage-collected.
@end table
......@@ -1697,8 +1710,85 @@ The numer of conferences the person is a member of.
@subsection Membership Information
@example
Member ::= Pers-No;
Membership-Type ::= BITSTRING
( invitation : BOOL;
passive : BOOL;
secret : BOOL;
reserved1 : BOOL;
reserved2 : BOOL;
reserved3 : BOOL;
reserved4 : BOOL;
reserved5 : BOOL;
)
@end example
The @code{Membership-Type} type contains flags that modify a membership.
It is passed as part of both @code{Member} and @code{Membership}. The
flags are:
@table @code
@item invitation
The member has been invited, but has not yet accepted membership.
Clients should set this flag when adding other users as members. The
server may force this flag to be set when adding another person as a
member of a conference.
@item passive
The member is not actively participating in the conference. Passive
members do not revceive group messages and should not be displayed as
active members by clients.
@item secret
The member does not wish to disclose the membership. Secret memberships
and members are cleared before being returned to a person who is not a
subervisor of the member or has sufficient privileges enabled.
@end table
The remaining flags in the @code{Membership-Type} structure are reserved
and should be set to false on all new memberships and retained on all
existing memberships.
@example
Member-Old ::= Pers-No;
Member-List-Old ::= ARRAY Member-Old;
Member ::=
( member : Pers-No;
added-by : Pers-No;
added-at : Time;
type : Membership-Type;
)
Member-List ::= ARRAY Member;
@end example
The @code{Member} structure encodes information about a member in a
conference. It is returned by the @ref{get-members} call. The fields of
a @code{Member} structure are
@table @code
@item member
The person who is a member of the conference.
@item added-by
The person who created the membership. This field is zero only if the
membership was created before protocol version 10 was introduced.
@item added-at
The time when the membership was created. This field is meaningless if
added-by is zero.
@item type
Flags modifying the membership.
@end table
The contents of a @code{Member} structure can be cleared (all fields set
to zero) if the person requesting the record has insufficient privileges
to see the contents of the structure.
@example
Membership-Old ::=
( last-time-read : Time;
conference : Conf-No;
priority : INT8;
last-text-read : Local-Text-No;
read-texts : ARRAY Local-Text-No;
)
Membership ::=
( last-time-read : Time;
......@@ -1706,16 +1796,18 @@ The numer of conferences the person is a member of.
priority : INT8;
last-text-read : Local-Text-No;
read-texts : ARRAY Local-Text-No;
added-by : Pers-No;
added-at : Time;
type : Membership-Type;
)
Membership-List-Old ::= ARRAY Membership-Old;
Membership-List ::= ARRAY Membership;
@end example
These data types contain information about which conferences a person is
a member of and what that person has unread in the conference.
@code{Member} represents a member and @code{Member-List} several.
@code{Membership} is information pertaining to the membership of a
single person. Its fields are
The @code{Membership} structure encodes information about a person's
membership in a conference. It is returned by the @ref{query-read-texts}
and @ref{get-membership} calls.
@table @code
@item last-time-read
......@@ -1730,8 +1822,21 @@ used to indicate a passive membership.
The local number of last text read in the conference.
@item read-texts
Additional texts beyond @code{last-text-read} that have also been read.
@item added-by
The person who created the membership. This field is zero if the
membership was created before protocol version 10 was introduced.
@item added-at
The time when the membership was created. This field is meaningless if
added-by is zero.
@item type
Flags modifying the membership.
@end table
A membership record may be cleared by the server (all fields set to
zero) if the person requesting the membership has insufficient
privileges to see the contents membership, but has sufficient privileges
to know about the person.
@subsection Article Marks
......@@ -2216,12 +2321,12 @@ in the example.
* get-person-stat-old:: O Get person information. Use call 49 (6)
* set-priv-bits:: Set privileges of a person (7)
* set-passwd:: Set password of a person (8)
* query-read-texts:: Get info on what is read (9)
* query-read-texts-old:: O Get info on what is read (9)
* create-conf-old:: O Create a conference (10)
* delete-conf:: Delete a conference (11)
* lookup-name:: O Look up a name. Replaced by call 76 (12)
* get-conf-stat-older:: O Get conference information. Use call 50 (13)
* add-member:: Add a member to a conference (14)
* add-member-old:: O Add a member to a conference (14)
* sub-member:: Remove a member from a conference (15)
* set-presentation:: Set the presentation of a conference (16)
* set-etc-motd:: Set conference notice (17)
......@@ -2253,9 +2358,9 @@ in the example.
* sync-kom:: Save the database (43)
* shutdown-kom:: Shut LysKOM down (44)
* broadcast:: O Broadcast a message. Replaced by call 53 (45)
* get-membership:: Get membership for a person (46)
* get-membership-old:: O Get membership for a person (46)
* get-created-texts:: Get texts created by a user (47)
* get-members:: Get members of a conference (48)
* get-members-old:: O Get members of a conference (48)
* get-person-stat:: Get status information for a person (49)
* get-conf-stat-old:: O Get status information for a conference (50)
* who-is-on:: O Get current sessions. Replaced by call 63 (51)
......@@ -2305,6 +2410,10 @@ in the example.
* modify-system-info:: Add or delete conference aux items (95)
* query-predefined-aux-items:: Get list of aux-items the server knows (96)
* set-expire:: Set the expire field in of conference (97)
* query-read-texts:: Get info on what is read (98)
* get-membership:: Get membership for a person (99)
* add-member:: Add a member to a conference (100)
* get-members:: Get members of a conference (101)
@end menu
@iftex
......@@ -2562,7 +2671,7 @@ and privilege level set to 6 or higher.
@end table
@node set-passwd, query-read-texts, set-priv-bits, Protocol Requests
@node set-passwd, query-read-texts-old, set-priv-bits, Protocol Requests
@subsection set-passwd (1) Recommended
@example
......@@ -2608,13 +2717,13 @@ privilege level 7 or higher enabled.
@node query-read-texts, create-conf-old, set-passwd, Protocol Requests
@subsection query-read-texts (1) Recommended
@node query-read-texts-old, create-conf-old, set-passwd, Protocol Requests
@subsection query-read-texts-old (1) Obsolete (10)
@example
query-read-texts [9] (( person : Pers-No;
conference : Conf-No; ))
-> ( read-texts : Membership );
query-read-texts-old [9] (( person : Pers-No;
conference : Conf-No; ))
-> ( read-texts : Membership-Old );
@end example
This call is used to find the number of unread texts in a conference.
......@@ -2625,7 +2734,7 @@ be made and @code{conference} is the conference in question.
This call may be issued without logging in.
Calling @code{query-read-texts} does not require the session to be logged in.
Calling @code{query-read-texts-old} does not require the session to be logged in.
@i{Example:}
@example
......@@ -2656,7 +2765,7 @@ Conference @code{conference} does not exist, or is secret.
@node create-conf-old, delete-conf, query-read-texts, Protocol Requests
@node create-conf-old, delete-conf, query-read-texts-old, Protocol Requests
@subsection create-conf-old (1) Obsolete (10)
@example
......@@ -2802,7 +2911,7 @@ lookup-name has been superseded by call 76, @ref{lookup-z-name}.
This call always succeeds.
@node get-conf-stat-older, add-member, lookup-name, Protocol Requests
@node get-conf-stat-older, add-member-old, lookup-name, Protocol Requests
@subsection get-conf-stat-older (1) Obsolete
@example
......@@ -2829,15 +2938,15 @@ use call 91, @ref{get-conf-stat} instead.
@node add-member, sub-member, get-conf-stat-older, Protocol Requests
@subsection add-member (1) Recommended
@node add-member-old, sub-member, get-conf-stat-older, Protocol Requests
@subsection add-member-old (1) Obsolete (10)
@i{Example:}
@example
add-member [14] (( conf-no : Conf-No;
pers-no : Pers-No;
priority : INT8;
where : INT16 ))
add-member-old [14] (( conf-no : Conf-No;
pers-no : Pers-No;
priority : INT8;
where : INT16 ))
-> ( );
@end example
......@@ -2893,7 +3002,7 @@ privileges to change the priorities of person @code{pers-no}.
@node sub-member, set-presentation, add-member, Protocol Requests
@node sub-member, set-presentation, add-member-old, Protocol Requests
@subsection sub-member (1) Recommended
@example
......@@ -4326,7 +4435,7 @@ Administrator bit not set or privileges not enabled.
@end table
@node broadcast, get-membership, shutdown-kom, Protocol Requests
@node broadcast, get-membership-old, shutdown-kom, Protocol Requests
@subsection broadcast (1) Obsolete
......@@ -4350,19 +4459,19 @@ Messages have been disabled.
@end table
@node get-membership, get-created-texts, broadcast, Protocol Requests
@node get-membership-old, get-created-texts, broadcast, Protocol Requests
@subsection get-membership (1) Recommended
@subsection get-membership-old (1) Obsolete (10)
@example
get-membership [46] (( person : Pers-No;
first : INT16;
no-of-confs : INT16;
mask : BITSTRING
(
want-read-texts
); ))
-> ( result : Membership-List );
get-membership-old [46] (( person : Pers-No;
first : INT16;
no-of-confs : INT16;
mask : BITSTRING
(
want-read-texts
); ))
-> ( result : Membership-List-Old );
@end example
This call retrieves the membership record for a list of conferences for
......@@ -4410,7 +4519,7 @@ person's membership list.
@node get-created-texts, get-members, get-membership, Protocol Requests
@node get-created-texts, get-members-old, get-membership-old, Protocol Requests
@subsection get-created-texts (1) Recommended
......@@ -4459,15 +4568,15 @@ text.
@node get-members, get-person-stat, get-created-texts, Protocol Requests
@node get-members-old, get-person-stat, get-created-texts, Protocol Requests
@subsection get-members (1) Recommended
@subsection get-members-old (1) Obsolete (10)
@example
get-members [48] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
-> ( result : Member-List );
get-members-old [48] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
-> ( result : Member-List-Old );
@end example
This call returns a list of members of the conference @code{conf-no}.
......@@ -4499,7 +4608,7 @@ The conference @code{conf} does not exist or is secret.
@node get-person-stat, get-conf-stat-old, get-members, Protocol Requests
@node get-person-stat, get-conf-stat-old, get-members-old, Protocol Requests
@subsection get-person-stat (1) Recommended
......@@ -6174,7 +6283,7 @@ This call always succeeds.
@node set-expire, , query-predefined-aux-items, Protocol Requests
@node set-expire, query-read-texts, query-predefined-aux-items, Protocol Requests
@subsection set-expire (10) Recommended
@example
......@@ -6199,8 +6308,249 @@ Not supervisor of conference @code{conf-no} and not privileged enough to
complete the call anyway.
@end table
@node query-read-texts, get-membership, set-expire, Protocol Requests
@subsection query-read-texts (10) Recommended
@example
query-read-texts [98] (( person : Pers-No;
conference : Conf-No; ))
-> ( read-texts : Membership );
@end example
This call is used to find the number of unread texts in a conference.
The data it returns is actually a membership structure which specifies
which texts have been read. It is up to the client to transform the data
to a more usable form. @code{person} is the person being queried is to
be made and @code{conference} is the conference in question.
This call may be issued without logging in.
Calling @code{query-read-texts-old} does not require the session to be logged in.
@i{Example:}
@example
1 98 6 1
@t{=1 32 5 11 12 7 93 1 193 1 1 20 133}
@t{ 3 @{ 135 136 137 @} 5 01000000}
@end example
This example finds the read texts for user 6 in conference 1. The
returned data indicates that the user last read conference 1 (the tenth
number) on Monday July 12th, 1993 at 11:05:32 (the first nine numbers),
that the person has assigned priority 20 to the conference (the eleventh
number) and that all articles up to and including local number 133 plus
articles 135, 136 and 137 have been read. The membership was added by
person 5, and it is passive.
@unnumberedsubsubsec Error codes
@table @code
@item undefined-person
@code{person} does not exist, or no access to person.
@item undefined-conference
Conference @code{conference} does not exist, or is secret.
@item zero-conference
@code{conference} is zero.
@item not-member
@code{person} is not a member of @code{conference} or insufficient
privileges to find out if @code{person} is a member.
@end table
@node get-membership, add-member, query-read-texts, Protocol Requests
@subsection get-membership (10) Recommended
@example
get-membership [99] (( person : Pers-No;
first : INT16;
no-of-confs : INT16;
mask : BITSTRING
(
want-read-texts
); ))
-> ( result : Membership-List );
@end example
This call retrieves the membership record for a list of conferences for
a single person. @code{person} is the person whose memberships are to be
retrieved. @code{first} is the first position in the membership list to
retrieve, numbered from 0 and up. @code{no-of-confs} is the number of
membership records to retrieve. @code{mask} is a set of flags. Currently
the only flag is @code{want-red-texts}, which instructs the server not
to send the @code{read-texts} array of the memberships.
The server will return a membership list that is shorter than
@code{no-of-confs} if @code{no-of-confs} + @code{first} is larger than
the number of conferences the person is a member of. Elements of the
member list that the person requesting the list does not have sufficient
privileges to see may be cleared. Cleared elements simply have all
fields set to zero.
@example
1 99 5 0 3 1
@t{=1 2 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000}
@t{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 00000000 @}}
1 99 5 0 1 1
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000 @}}
1 99 5 1 4 1
@t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 00000000 @}}
@end example
In this example we retrieve the memberships of person 5. The first call
asks for three memberships, starting with number 0. Since this person is
only a member of two conferences, the list returned only contains two
memberships. The next two calls retrieve a single membership each. The
first by asking for only one, and the second by asking for four
memberships, starting with number 1.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-person
The person @code{person} does not exist.
@item undefined-conference
The conference @code{person} does not exist or is secret.
@item index-out-of-range
@code{first} is higher than the index of the first conference in the
person's membership list.
@end table
@node add-member, get-members, get-membership, Protocol Requests
@subsection add-member (10) Recommended
@example
add-member [100] (( conf-no : Conf-No;
pers-no : Pers-No;
priority : INT8;
where : INT16;
type : Membership-Type; ))
-> ( );
@end example
Make the person @code{pers-no} a member of conference @code{conf-no}.
The membership priority is set to @code{priority} and its position in
the membership list is set to @code{where}.
This call can be used to change the priority, position and flags of a
conference in the person's membership list if the person is already a
member of the conference. The person doing this must either be a
supervisor of the affected person, or have sufficient privileges
enabled.
@example
1 99 119 0 10 0
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * 119 00001111 @}}
1 100 1 119 250 0 10000000
@t{=1}
1 100 119 119 251 1 00000000
@t{=1}
1 99 119 0 10 0
@t{=1 2 @{ 52 30 14 11 5 96 2 162 1 1 250 0 0 * 119 00000000
49 14 17 13 8 91 5 251 1 119 255 0 0 * 10000000 @}}
@end example
This example makes person 119 (me) a member of conference number 1 and
changes the priority and some flags of the preexisting membership in
conference 119. The priority is set to 250 and the conference is placed
first in the membership list. The first and last calls of the example
show the membership list for person 119 before and after the calls.
@unnumberedsubsubsec Error codes
@table @code
@item login-first
Login required before issuing this call.
@item undefined-conference
Conference @code{conf-no} does not exist or is secret.
@item zero-conference
@code{conference} is zero.
@item undefined-person
Person @code{pers-no} does not exist
@item access-denied
Not enough permissions or privileges to add members to conference or to
change privileges, position or type of a preexisting membership.
@code{conf-no}.
@item permission-denied
Person @code{pers-no} is already a member of conference @code{conf-no},
but the person logged on is not a supervisor and does not have enough
privileges to change the priorities of person @code{pers-no}.
@end table
@node get-members, set-membership-type, add-member, Protocol Requests
@subsection get-members (10) Recommended
@example
get-members [101] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
-> ( result : Member-List );
@end example
This call returns a list of members of the conference @code{conf-no}.
@code{first} is the first index in the membership to return, numbered
from zero and up. @code{no-of-members} is the maximum number of members
to return.
Some of the elements of the result may be cleared if the person
requesting the information does not have sufficient privileges to see
the contents. Cleared elements simply have all fields set to zero.
@example
1 101 1 0 100
@t{=1 4 @{ 7 7 00000000 8 8 00000000 9 8 00000000 }
@t{ 10 10 00000000 @}}
1 101 6 0 100
@t{=1 4 @{ 5 5 01000000 7 7 01000000 9 8 10000000 }
@t{ 10 10 00000000 @}}
1 101 6 2 2