Commit 14290d8b authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(Simple Data Types): The %g format specifier is locale-dependent in

	the C specification, so say that FLOAT is formatted as %g is
	formatted in the "C" locale.
(Conference Status Types): Fixed the description of the no-of-texts
	field.  It is actually the difference between the first unused
	local text number and first-local-no, and that will differ
	from the number of texts in the conference if a text other
	than the oldest one is removed.
(Membership Information): Document that read-ranges is kept in
	ascending order.
(What do I have unread): Update the description with the version
	11 requests.
parent 077c57d5
......@@ -1098,11 +1098,11 @@ transmitted to the server in ASCII-encoded decimal notation.
@tindex FLOAT
@type{FLOAT} are floating point numbers. They are represented as if
printed via @code{printf("%g", val);} in C. See @cite{7.19.6.1 The
fprintf function} in @cite{ISO/IEC 9899:1999 Programming languages -
C} for the details. @xref{Floating-Point Conversions, , The %g
conversion, libc, The GNU C Library Reference Manual}, if you don't
have the C standard handy.
printed via @code{printf("%g", val);} in C, in the default (@samp{C})
locale. See @cite{7.19.6.1 The fprintf function} in @cite{ISO/IEC
9899:1999 Programming languages - C} for the details.
@xref{Floating-Point Conversions, , The %g conversion, libc, The GNU C
Library Reference Manual}, if you don't have the C standard handy.
@anchor{HOLLERITH}
@subsection Strings
......@@ -1935,7 +1935,15 @@ The number of members of this conference.
@item first-local-no
The local number of the oldest existing article in the conference.
@item no-of-texts
The number of articles in the conference.
If you add @field{first-local-no} and @field{no-of-texts} you will get
the first unused local text number of this conference. If texts are
always removed in the order they were created, this would be the
number of articles in the conference. Unfortunately, when the name of
this field was defined, nobody considered the fact that text removal
in a typical KOM system is not that linear. Don't let the name
confuse you.
@item expire
This field will be used to control when a conference expires.
It is not used at the moment, and should be set to zero for future
......@@ -2496,7 +2504,7 @@ 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.
anyhow. The data will be sorted in ascending order.
@item added-by
The person who created the membership. This field is zero if the
membership was created before protocol version 10 was introduced.
......@@ -10708,51 +10716,59 @@ 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.
The list of read texts consists of two parts: a local text number called
@field{last-text-read} and a list of local text numbers called
@field{read-texts}. The person has marked all texts up to and including
@field{last-text-read} as read, and also the texts listed in
@field{read-texts}. All other texts in the conference are unread. Clients
can use either the @req{query-read-texts} or
@req{get-membership} calls to get membership data.
The list of read texts consists of a list of ranges. Since a typical
reader reads texts more-or-less in order from oldest to newest, this
will result in a reasonably compact data structure. The server will
automatically grow the ranges when adjacent texts are
removed@footnote{but not right away, so clients must handle the case
when a text doesn't exist}, and if the gap between two ranges
disappears the ranges will of course be merged.
All texts that are not included in any of the ranges are unread.
Clients can use either the @reqlink{query-read-texts} or
@reqlink{get-membership} calls to get membership data.
The standard procedure for finding out which texts are unread is the
following:
@enumerate
@item Call @req{get-unread-confs} for the person.
@item Call @reqdlink{get-unread-confs} for the person@linkhere{}.
This returns a list of conferences in which the person may have unread
texts. This call may return conferences that do not contain any unread
texts, but it will never forget to return a conference that does contain
an unread text.
@item Call @req{query-read-texts} for each conference returned in
@item Call @reqlink{query-read-texts} for each conference returned in
the previous step. This will return the membership data for all the
conferences that may contain unread texts.
@item Call @req{get-uconf-stat} for each conference returned in
the first step. The conference status will be needed shortly. Repeat the
following steps for each conference.
@item Call @reqlink{get-uconf-stat} for each conference returned in
the first step. The @field{highest-local-no} field in the result is
the highest existing local text number in the conference, and it will
be needed shortly. Repeat the following steps for each conference.
@item Compare the highest existing local number in the conference (from
the conference status) with the @field{last-text-read} field for the
corresponding membership. If the highest existing local text is higher
than @field{last-text-read}, the conference may contain unread texts.
@item Compute the set of possibly unread texts. This can be done by
creating the interval 1@dots{}@field{highest-local-no} and then
removing all intervals in the result from @req{query-read-texts}. If
the resulting set is non-empty, the conference may contain unread
texts.
@item Get part of the local to global map from the conference starting
at @field{last-text-read} and ending at the highest existing local
number. Every local number in the map that is not read according to the
membership data and that has a mapping to a global number is an unread
text. You might say that you remove the read texts from the map to get
the unread texts.
@item Use the @reqdlink{local-to-global} request@linkhere{} to get the
parts of the local to global map that are present in the set. Unless
you have an extremely long round-trip time, it is best to only have a
single pending pending @req{local-to-global} request per conference,
as it may return a sparse mapping. Every local number in the map that
is not read according to the membership data and that has a mapping to
a global number is an unread text.
@end enumerate
Take care not to call get-map or get-membership too much since they tend
to be expensive operations. Use @req{get-unread-confs} and
@req{query-read-texts} to minimize the work. Another point to remember
is that the server will send asynchronous messages with information
about new texts. Clients need to listen to these messages.
Take care not to call @req{get-map} or @req{get-membership} too much
since they tend to be expensive operations. Use
@req{get-unread-confs} and @req{query-read-texts} to minimize the
work. Another point to remember is that the server will send
asynchronous messages with information about new texts. Clients need
to listen to these messages.
@node Client Conventions
......
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