Commit c318bbfd authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(Membership and Reading): Talk about read-ranges, not last-text-read

	and read-texts.
(Person Status Types): Mention read-ranges.
(Membership Information): Mention that obsolete versions of
	Membership exists.
(Membership Information): Renamed Membership to Membership-10, and
	added new Membership and Read-Range types.
(Protocol Requests): Flag 98=query-read-texts-10 and
	99=get-membership-10 as obsolete.  Added 107=query-read-texts
	and 108=get-membership.
(sub-member): Changed get-membership to get-membership-old, since
	that is was the example uses.  Added markup.
(mark-as-read): Changed query-read-texts to query-read-texts-old,
	since that is what the example uses.  Added markup.
(set-unread): Ditto.
(set-last-read): Ditto.
(query-read-texts-10): New name for former request query-read-texts.
	Mark it as obsolete and refer to the new query-read-texts
	request.  Changed return type to Membership-10.
(get-membership-10): New name for former request get-membership.  Mark
	it as obsolete and refer to the new get-membership request.
	Changed return type to ARRAY Membership-10.
(query-read-texts): New request.
(get-membership): New request.
(Membership visibility): Added get-membership-10 and query-read-texts-10.
(What do I have unread): Added markup.
(Future changes): Removed references to bug 52.
(Document Edition History): Tracked the renaming of
	query-read-texts-10 and get-membership-10.
parent dbfc152a
......@@ -962,17 +962,15 @@ passive memberships, but there was a convention that clients should
treat the priority level zero as a passive membership.
The membership record indicates which texts have been read through the
@field{last-text-read} and @field{read-texts} fields. All texts with local
numbers up to @field{last-text-read} have been read. In addition, all
texts with local numbers contained in the @field{read-texts} array have
been read.
@field{read-ranges} field, which contains a list of ranges of local
text numbers that has been read.
Finding out which articles a person has read in a particular conference
requires a few calls. Normally, a client will retrieve a batch of
perhaps 50 articles at a time. The outline of the process is as follows:
@enumerate
@item Fetch the membership to get the @field{last-text-read}
@item Fetch the membership to get the @field{read-ranges}.
@item Use @reqlink{local-to-global} to translate a number of local
numbers to global numbers.
@item Remove the global numbers corresponding to local numbers contained
......@@ -2179,9 +2177,10 @@ The fields of @type{Personal-Flags} are
@item unread-is-secret
If this is set, only the person and his supervisors can see how many
texts this persons have read in a certain conference. The server will
clear the @field{read-texts}, @field{last-time-read} and
@field{last-text-read} fields of @type{Membership} and
@type{Membership-Old} when other persons asks about the information.
clear the @field{read-ranges} field of @type{Membership} (and
@field{read-texts}, @field{last-time-read} and @field{last-text-read}
fields of @type{Membership-10} and @type{Membership-Old}) when other
persons asks about the information.
@item flg2
@itemx flg3
......@@ -2213,8 +2212,9 @@ have.
@end example
The @type{Membership-Type} type contains flags that modify a membership.
It is passed as part of both @type{Member} and @type{Membership}. The
flags are:
It is passed as part of both @type{Member} and @type{Membership} (and
obsolete versions of those types).
The flags are:
@table @field
@item invitation
......@@ -2269,10 +2269,29 @@ to zero) if the person requesting the record has insufficient privileges
to see the contents of the structure.
@anchor{Membership-Old}
@anchor{Membership}
@anchor{Read-Range}
@tindex Membership-Old
@tindex Membership
@tindex Read-Range
@tindex Membership-10
@example
Read-Range ::=
( first-read : @lt{Local-Text-No};
last-read : @lt{Local-Text-No};
)
Membership ::=
( position : @lt{INT32};
last-time-read : @lt{Time};
conference : @lt{Conf-No};
priority : @lt{INT8};
read-ranges : @lt{ARRAY} @lt{Read-Range};
added-by : @lt{Pers-No};
added-at : @lt{Time};
type : @lt{Membership-Type};
)
@anchor{Membership-Old}
Membership-Old ::=
( last-time-read : @lt{Time};
conference : @lt{Conf-No};
......@@ -2281,8 +2300,8 @@ to see the contents of the structure.
read-texts : @lt{ARRAY} @lt{Local-Text-No};
)
@anchor{Membership}
Membership ::=
@anchor{Membership-10}
Membership-10 ::=
( position : @lt{INT32};
last-time-read : @lt{Time};
conference : @lt{Conf-No};
......@@ -2299,6 +2318,12 @@ The @type{Membership} structure encodes information about a person's
membership in a conference. It is returned by the
@reqlink{query-read-texts} and @reqdlink{get-membership} calls@linkhere{}.
The @type{Membership-10} and @type{Membership-Old} types are obsolete
variants of the same type, returned by older requests.
@type{Membership-Old} contains less information. The encoding of the
read texts in @type{Membership-10} is very inefficient in the common
case where you have read many texts after the first unread text.
@table @field
@item position
The position of this membership in the membership list.
......@@ -2316,11 +2341,17 @@ passive membership. This usage is now obsolete.
@item last-text-read
The local number of last text read in the conference. This will be
set to 0 if @field{unread-is-secret} is set, unless you have access to
the data anyhow.
the data anyhow. This field is not available in @type{Membership},
but you can easily derive the same information from
@field{read-ranges}.
@item read-texts
Additional texts beyond @field{last-text-read} that have also been
read. This will be empty if @field{unread-is-secret} is set, unless
you have access to the data anyhow.
@item read-ranges
A list of ranges of all read texts. This will be empty if
@field{unread-is-secret} is set, unless you have access to the data
anyhow.
@item added-by
The person who created the membership. This field is zero if the
membership was created before protocol version 10 was introduced.
......@@ -2853,8 +2884,8 @@ their current status.
* modify-system-info:: r Add or delete system aux items (95)
* query-predefined-aux-items:: r Get list of aux-items the server knows (96)
* set-expire:: e Set the expire field of a conference (97)
* query-read-texts:: r Get info on what is read (98)
* get-membership:: r Get membership for a person (99)
* query-read-texts-10:: O Get info on what is read (98)
* get-membership-10:: O Get membership for a person (99)
* add-member:: r Add a member to a conference (100)
* get-members:: r Get members of a conference (101)
* set-membership-type:: r Modify the type of conference (102)
......@@ -2862,6 +2893,8 @@ their current status.
* map-created-texts:: r Map texts created by a person to global (104)
* set-keep-commented:: e Set how new comments protect old texts (105)
* set-pers-flags:: r Set personal flags (106)
* query-read-texts:: r Get info on what is read (107)
* get-membership:: r Get membership for a person (108)
@end menu
@ifnottex
......@@ -3578,7 +3611,8 @@ memberships.
@end example
This example shows how person 5 is removed from conference one. The
calls to get-membership demonstrate the effects on the LysKOM database.
calls to @req{get-membership-old} demonstrate the effects on the
LysKOM database.
@subheading Error codes
......@@ -4222,10 +4256,10 @@ user.
@end example
This example shows person 6 marking local text number 241 in conference
7 as read. In the first 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-read-texts call, where the user is seen to have read text
241 in conference 7.
7 as read. In the first @req{query-read-texts-old} call the person
has read local text 240, but nothing higher. The @req{mark-as-read}
call is reflected in the second @req{query-read-texts-old} 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 at the Misc-Info list in the
......@@ -4946,7 +4980,7 @@ This example shows that person 5 last read text 0 in conference 6 (and
since 0 is an illegal local text number, that implies that the person
has not read anything in the conference.) After calling set-unread and
asking to have zero unread texts in conference 6, this is reflected by
the call to query-read-texts.
the call to @req{query-read-texts-old}.
@subheading Error codes
......@@ -6397,7 +6431,7 @@ a specific number of unread texts in a particular conference.
This example shows how person 7 originally had read everything up to and
including local text number 6 in conference 6. After the call to
@req{set-last-read}, the @reqlink{query-read-texts} call reports that
@req{set-last-read}, the @reqlink{query-read-texts-old} call reports that
person 7 has read everything up to and including local text number 3.
@subheading Error codes
......@@ -7182,23 +7216,26 @@ Not supervisor of conference @rarg{conf-no} and not privileged enough to
complete the call anyway.
@end table
@node query-read-texts
@section query-read-texts [98] (10) Recommended
@node query-read-texts-10
@section query-read-texts-10 [98] (10) Obsolete
@findex query-read-texts
@findex query-read-texts-10
@example
query-read-texts [98] (( person : @lt{Pers-No};
conference : @lt{Conf-No} ))
-> ( @lt{Membership} );
query-read-texts-10 [98] (( person : @lt{Pers-No};
conference : @lt{Conf-No} ))
-> ( @lt{Membership-10} );
@end example
This call is obsolete. Use @reqlink{query-read-texts}.
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. @rarg{person} is the person being queried
and @rarg{conference} is the conference in question.
Calling @req{query-read-texts} does not require the session to be logged in.
Calling @req{query-read-texts-10} does not require the session to be
logged in.
@reqexample
@example
......@@ -7235,18 +7272,20 @@ privileges to find out if @rarg{person} is a member.
@end table
@node get-membership
@section get-membership [99] (10) Recommended
@node get-membership-10
@section get-membership-10 [99] (10) Obsolete
@findex get-membership
@findex get-membership-10
@example
get-membership [99] (( person : @lt{Pers-No};
first : @lt{INT16};
no-of-confs : @lt{INT16};
want-read-texts : @lt{BOOL} ))
-> ( @lt{ARRAY} @lt{Membership} );
get-membership-10 [99] (( person : @lt{Pers-No};
first : @lt{INT16};
no-of-confs : @lt{INT16};
want-read-texts : @lt{BOOL} ))
-> ( @lt{ARRAY} @lt{Membership-10} );
@end example
This call is obsolete. Use @reqlink{get-membership}.
This call retrieves the membership record for a list of conferences
for a single person. @rarg{person} is the person whose memberships are
to be retrieved. @rarg{first} is the first position in the membership
......@@ -7677,6 +7716,158 @@ Person exists, but the session does not have permission to change the
flags.
@end table
@node query-read-texts
@section query-read-texts [107] (11) Recommended
@findex query-read-texts
@example
query-read-texts [107] (( person : @lt{Pers-No};
conference : @lt{Conf-No};
want-read-ranges : @lt{BOOL};
max-ranges : @lt{INT32} ))
-> ( @lt{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. @rarg{person} is the person being queried
and @rarg{conference} is the conference in question.
If @rarg{want-read-ranges} is @samp{0}, the server will not send the
contents of the @field{read-ranges} array of the memberships. (The
size will be transmitted, but a single asterisk (@samp{*}) will be
sent instead of the array itself.) The @rarg{max-ranges} argument is
ignored in this case.
If @rarg{want-read-ranges} is @samp{1}, the @field{read-ranges} array
will be returned. If @rarg{max-ranges} is non-zero, the array will be
truncated to @rarg{max-ranges} ranges. (It isn't possible to
determine if the array has been truncated, or if the array actually
contained exactly that many ranges.) Setting @rarg{max-ranges} to
@samp{1} gives you enough information to find out the first unread
text.
When you call this request with @rarg{want-read-ranges} set to
@samp{1}, the ranges will expand to include any adjacent texts that
are now deleted. This may not happen if @reqlink{get-membership} is
used to retrieve the information.
Calling @req{query-read-texts} does not require the session to be
logged in.
@reqexample
@example
1 107 6 1 1 0
@t{=1 4 32 5 11 12 7 93 1 193 1 1 20}
@t{ 2 @{ 1 133 135 137 @} 5 43 8 3 12 7 93 1 193 1 01000000}
@end example
This example finds the read texts for user 6 in conference 1. The
returned data indicates that conference 1 is the fifth conference on
the users' membership list (@samp{4}; remember that the
@field{position} starts its count at 0), user last read the conference
on Monday July 12th, 1993 at 11:05:32 (@samp{32 5 11 12 7 93 1 193
1}), that it is the membership in conference number 1 (@samp{1}), that
the person has assigned priority 20 to the conference (@samp{20}) and
that all texts 1-133 and 135-137 have been read (@samp{2 @{ 1 133 135
137 @}}). The membership was added by person 5 (@samp{5}) at Monday
July 12th, 1993 at 03:08:43 (@samp{43 8 3 12 7 93 1 193 1}) and it is
passive (@samp{01000000}).
@subheading Error codes
@table @errorcode
@item undefined-person
@rarg{person} does not exist, or no access to person.
@item undefined-conference
Conference @rarg{conference} does not exist, or is secret.
@item conference-zero
@rarg{conference} is zero.
@item not-member
@rarg{person} is not a member of @rarg{conference} or insufficient
privileges to find out if @rarg{person} is a member.
@end table
@node get-membership
@section get-membership [108] (10) Recommended
@findex get-membership
@example
get-membership [108] (( person : @lt{Pers-No};
first : @lt{INT16};
no-of-confs : @lt{INT16};
want-read-ranges : @lt{BOOL};
max-ranges : @lt{INT32} ))
-> ( @lt{ARRAY} @lt{Membership} );
@end example
This call retrieves the membership record for a list of conferences
for a single person. @rarg{person} is the person whose memberships are
to be retrieved. @rarg{first} is the first position in the membership
list to retrieve, numbered from 0 and up. @rarg{no-of-confs} is the
number of membership records to retrieve.
If @rarg{want-read-ranges} is @samp{0}, the server will not send the
contents of the @field{read-texts} array of the memberships. (The
sizes will be transmitted, but a single asterisk (@samp{*}) will be
sent instead of the array itself.) The @rarg{max-ranges} argument is
ignored in this case.
If @rarg{want-read-ranges} is @samp{1}, the @field{read-ranges} arrays
of the memberships will be returned. If @rarg{max-ranges} is
non-zero, each array will be truncated to @rarg{max-ranges} ranges.
(It isn't possible to determine if an array has been truncated, or if
that array actually contained exactly that many ranges.) Unlike
@reqlink{query-read-texts}, the ranges may not expand to include
deleted texts, so it isn't certain that you get enough information
to find the first unread text if you specify a non-zero
@rarg{max-ranges} argument.
The server will return a membership list that is shorter than
@rarg{no-of-confs} if @rarg{no-of-confs} + @rarg{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.
@reqexample
@example
1 108 5 0 3 1 0
@t{=1 2 @{ 0 49 14 17 13 8 91 5 255 1 5 255 0 * 5 }
@t{ 49 14 17 13 8 91 5 255 1 00000000 }
@t{ 1 20 14 22 17 6 97 4 197 1 6 100 1 @{ 1 2 @} 5 }
@t{ 49 14 17 13 8 91 5 255 1 00000000 @}}
2 108 5 0 1 1 0
@t{=2 1 @{ 0 49 14 17 13 8 91 5 255 1 5 255 0 * 5 }
@t{ 49 14 17 13 8 91 5 255 1 00000000 @}}
3 108 5 1 4 1 0
@t{=3 1 @{ 1 20 14 22 17 6 97 4 197 1 6 100 1 @{ 1 2 @} 5 }
@t{ 49 14 17 13 8 91 5 255 1 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.
@subheading Error codes
@table @errorcode
@item login-first
Login required before issuing this call.
@item undefined-person
The person @rarg{person} does not exist.
@item undefined-conference
The conference @rarg{person} does not exist or is secret.
@item index-out-of-range
@rarg{first} is higher than the index of the last conference in the
person's membership list.
@end table
@node Asynchronous Messages
@chapter Asynchronous Messages
......@@ -9107,6 +9298,7 @@ the person is a member of.
@itemize @bullet
@item @reqlink{get-membership}
@item @reqlink{get-membership-10}
@item @reqlink{get-membership-old}
@item @reqlink{get-unread-confs}
@end itemize
......@@ -9120,6 +9312,7 @@ to the rules below.
@itemize @bullet
@item @reqlink{query-read-texts}
@item @reqlink{query-read-texts-10}
@item @reqlink{query-read-texts-old}
@end itemize
......@@ -9197,7 +9390,7 @@ to answer some questions that seem to come up over and over again.
@subsection What do I have unread
Each person has a membership list containing the conferences the person
is a member of. Each element is an object of type Membership. Among
is a member of. Each element is an object of type @type{Membership}. Among
other things it contains the number of the conference, the priority of
the membership, when the person most recently marked a text as read in
the conference, and which texts the person has read.
......@@ -9671,16 +9864,6 @@ The security system is too complex, yet unable to do many useful
things, and should be rethought. (This is
@uref{http://bugzilla.lysator.liu.se/show_bug.cgi?id=137, bug 137}.)
@item
The @field{last-text-read} and @field{read-texts} fields of a
@type{Membership} is a very poor way to store information about what
is read. Consider the case where somebody has read everything up to
text 100, and text 102-2002. Using the current protocol specification
more than 2000 numbers must be transmitted to convey that information.
A much more attractive solution would be to send a list of ranges of
read texts. (This is
@uref{http://bugzilla.lysator.liu.se/show_bug.cgi?id=52, bug 52}.)
@item
The @reqlink{mark-as-read} call is a reasonably good way to mark a
single text as read (but one could argue that it should take a single
......@@ -10073,7 +10256,7 @@ Distributed with lyskomd 2.0.7.
@item 10.6: 2002-03-29
@emph{Fixed errors:} The format of the user area was plain wrong. The
examples for @req{query-read-texts} and @req{get-membership} were
examples for @req{query-read-texts-10} and @req{get-membership-10} were
wrong. The @field{idle-time} field is only affected by the
@req{user-active} request, not by all activity (@pxref{Session
Information}).
......@@ -10156,7 +10339,7 @@ now makes heavy use of Texinfo macros. Due to bugs in the current
version of @file{texinfo.tex} this file cannot currently be typeset
using @TeX{}. (All bugs are reported to the Texinfo maintainers.)
@req{get-membership-old}, @req{get-membership} and @req{login} used to
@req{get-membership-old}, @req{get-membership-10} and @req{login} used to
take an argument of type @code{BITSTRING(@var{a-single-field})}. The
type has now been changed to @type{BOOL} instead, to simplify the
description. The encoding of the protocol is unchanged.
......
Supports Markdown
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