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

(mark-as-unread): New request.

(set-read-ranges): New request.
(Error Codes): Added invalid-range and invalid-range-list.
(mark-as-read): Added markup.
(set-unread): Ditto.
(get-membership): This was introduced in protocol version 11, not 10.
parent cce01264
......@@ -2895,6 +2895,8 @@ their current status.
* 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)
* mark-as-unread:: r Mark a text as not read (109)
* set-read-ranges:: r Specify which texts that are read (110)
@end menu
@ifnottex
......@@ -4262,11 +4264,11 @@ 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
Text-Stat and calling mark-as-read once for each recipient.
into local text numbers by looking at the misc-info list in the
@type{Text-Stat} and calling @req{mark-as-read} once for each recipient.
There is no need to call mark-as-read on deleted texts. The server will
automatically mark them as read, sooner or later.
There is no need to call @req{mark-as-read} on deleted texts. The
server will automatically mark them as read, sooner or later.
@subheading Error codes
......@@ -4978,9 +4980,9 @@ membership.
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 @req{query-read-texts-old}.
has not read anything in the conference.) After calling
@req{set-unread} and asking to have zero unread texts in conference 6,
this is reflected by the call to @req{query-read-texts-old}.
@subheading Error codes
......@@ -7791,7 +7793,7 @@ privileges to find out if @rarg{person} is a member.
@node get-membership
@section get-membership [108] (10) Recommended
@section get-membership [108] (11) Recommended
@findex get-membership
@example
......@@ -7869,6 +7871,149 @@ person's membership list.
@end table
@node mark-as-unread
@section mark-as-unread [109] (11) Recommended
@findex mark-as-unread
@example
mark-as-unread [109] (( conference : @lt{Conf-No};
text : @lt{Local-Text-No} ))
-> ( );
@end example
Marks text @rarg{text} in conference number @rarg{conference} as not
read for the current user. This call updates the membership record
for the user. It can be used to undo the effect of
@reqlink{mark-as-read}.
@reqexample
@example
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 241 0 *}
1 78 7
@t{=1 @holl{13,@value{IAM}} 00001000 241 1}
1 27 7 241
@t{=1}
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 240 0 *}
@end example
This example shows person 6 marking local text number 241 in
conference 7 as not read. In the first @req{query-read-texts-old}
call the person has read local text 241, and 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 240 in conference 7, but nothing higher.
To mark a global text number as not read it is necessary to translate
it into local text numbers by looking at the misc-info list in the
@type{Text-Stat} and calling @req{mark-as-read} once for each
recipient.
Attempts to mark a deleted text as unread will appear to succeed, but
might have no effect, since the server will automatically mark them as
read, sooner or later.
@subheading Error codes
@table @errorcode
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @rarg{conference} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@item not-member
The person logged on is not a member of conference @rarg{conference}.
@item no-such-local-text
@rarg{text} is not, and has never been, a local text number in
@rarg{conference}. The error argument contains the invalid number.
@item local-text-zero
@rarg{text} is zero.
@end table
@node set-read-ranges
@section set-read-ranges [110] (11) Recommended
@findex set-read-ranges
@example
set-read-ranges [110] (( conference : @lt{Conf-No};
read-ranges : @lt{ARRAY} @lt{Read-Range} ))
-> ( );
@end example
This call tells the server that the person issuing the call has read
exactly those texts specified by @rarg{read-ranges} in conference
@rarg{conference}. This call is typically used to migrate a
membership from one person to another. It can also be used instead of
@reqlink{set-unread} or @reqlink{set-last-read}.
The server may automatically extend the ranges with adjacent local
text numbers that are deleted.
@reqexample
@example
1 9 7 6
@t{=1 2 4 22 18 6 97 5 198 1 6 100 6 0 *}
2 110 6 3 @{ 1 20 23 23 25 28 @}
@t{=2}
3 9 7 6
@t{=3 2 4 22 18 6 97 5 198 1 6 100 20 5 @{ 23 25 26 27 28 @}}
@end example
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-read-ranges}, the @reqlink{query-read-texts-old} call reports
that person 7 has read the local text numbers 1-20, 23 and 25-28.
@subheading Error codes
@table @errorcode
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @rarg{conference} does not exist or is secret.
@item not-member
Not a member of conference @rarg{conference}.
@item local-text-zero
@rarg{read-ranges} contains the number 0.
@item no-such-local-text
@rarg{read-ranges} contains a local text number that never has
existed.
@item long-array
The @rarg{read-ranges} array is too long. @field{error-status}
indicates the maximum range allowed.
@item invalid-range
The @field{first-read} field in one of the ranges in
@rarg{read-ranges} is greater than @field{last-read}. The
@field{error-status} indicates the interval (0 for the first interval,
1 for the second, and so on).
@item invalid-range-list
The @field{first-read} field in one of the ranges in
@rarg{read-ranges} is not greater than the @field{last-read} field of
the previous range. The @field{error-status} indicates the interval
(0 for the first interval, 1 for the second, and so on).
@end table
@node Asynchronous Messages
@chapter Asynchronous Messages
......@@ -8488,6 +8633,15 @@ the server or on a specific conference. @field{error-status} is
undefined unless specifically mentioned in the documentation for a
specific call.
@item invalid-range (55)
The lower limit of a supplied range is greater than the upper limit.
@field{error-status} is undefined.
@item invalid-range-list (56)
The lower limit of a supplied range is not greater than the upper
limit of the previous range in the list.
@field{error-status} is undefined.
@end table
......
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