Commit 7ed20742 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(get-map): Document what happens when attempting to retrieve texts

	before the start of the map.
(get-created-texts): Likewise.
parent 7aefcd35
\input texinfo @c -*-texinfo-*-
@c $Id: Protocol-A.texi,v 1.14 1998/08/08 21:46:20 ceder Exp $
@c $Id: Protocol-A.texi,v 1.15 1998/08/09 19:01:34 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -4054,28 +4054,54 @@ number @code{first-local-no} plus one; and so forth. The list returned
by the server is at most @code{no-of-texts} long, but may be shorter if
the call specifies more texts that there are in the conference.
If @code{first-local-no} is higher than the highest local text number or
zero, the server will return an error.
If @code{first-local-no} is higher than the highest local text number,
the server will return an error.
If @code{first-local-no} is lower than the lowest number that still
exists, the server will set @code{result.first-local-no} in the returned
Text-List to the first text that still exists. The size of the returned
array will be decreased by the same amount as
@code{result.first-local-no} is increased. This may result in an empty
array being returned. (This paragraph applies even when
@code{first-local-no} is 0.)
If no texts at all exists in @code{conf-no} the resulting array will be
empty, and @code{result.first-local-no} will be set to the number the
next text to be created will receive.
@example
1 34 119 10 5
@t{=1 10 5 @{ 0 0 466 478 391 @}}
1 34 119 16 5
@t{=1 16 3 @{ 481 0 491 @}}
1 34 119 19 5
@t{%2 16 0}
2 34 119 16 5
@t{=2 16 3 @{ 481 0 491 @}}
3 34 119 19 5
@t{%3 16 0}
4 34 120 1 5
@t{=4 4 2 @{ 480 485 @}}
5 34 120 1 2
@t{=5 4 0 *}
@end example
This example shows three @code{get-map} calls. The first retrieves the
This example shows five @code{get-map} calls. The first retrieves the
mappings of local numbers 10 to 15; the second call returns local
numbers 16 to 18. As this example shows the maps are not necessarily
sorted in ascending order, since texts may be added after their
creation, and the maps may contain zeroes anywhere. These represent
texts that have been removed for some reason.
The final exchange in the example shows what happens when
Since the first example returned two leading zeroes we can be certain
that at least one text with a local text number lower than 10 still
exists. Otherwise the result would have been truncated in the front as
it is in examples 4 and 5.
The third exchange in the example shows what happens when
@code{first-local-no} is too large.
The forth and fifth examples shows what happens when an attempt to
retrieve a mapping from a conference where the first local text numbers
have been deleted. In the example local text numbers 1, 2 and 3 no longer
exist, and 4 corresponds to 480, and 5 to 485.
@unnumberedsubsubsec Error codes
@table @code
......@@ -4088,7 +4114,8 @@ Conference @code{conf-no} does not exist or is secret.
@item access-denied
Conference @code{conf-no} is read protected.
@item no-such-local-text
@code{first-local-no} is not a local text number.
@code{first-local-no} is higher than the highest local text number that
ever has existed in this conference.
@end table
......@@ -4567,9 +4594,10 @@ person's membership list.
( result : Text-List );
@end example
This call returns a list of the texts written by a person. is the person
whose created texts are to be retrieved. @code{first} is the first text
to retrieve. @code{no-of-texts} is the number of texts to retrieve.
This call returns a list of the texts written by a person.
@code{person} is the person whose created texts are to be
retrieved. @code{first} is the first text to
retrieve. @code{no-of-texts} is the number of texts to retrieve.
This call is essentially the same as @ref{get-map}, but instead of
returning the texts sent to a single conference, it returns the texts
......@@ -4577,17 +4605,37 @@ written by a single person to any conference. The number of texts
written by any one person is contained in the Person record for that
person.
If @code{first} is lower than the first text written by @code{person}
that still exists, it will be automatically increased to the first still
existing text written by @code{person}. The @code{get-created-texts}
will still attempt to return information about @code{no-of-texts} texts.
(In this regard @code{get-map} and @code{get-created-texts} differ,
since @code{get-map} will never ever return information about a later
text than specified in the arguments to the call.@footnote{This
difference was not intentional, but it is now too late to change the
semantics of either @code{get-map} or @code{get-created-texts}.
Besides, they are both obsolete calls.})
@example
1 47 5 0 100
@t{=1 1 8 @{ 1 2 3 4 5 6 7 8 @}}
1 47 5 4 2
@t{=1 4 2 @{ 4 5 @}}
2 47 5 4 2
@t{=2 4 2 @{ 4 5 @}}
3 47 10 8 8
@t{=3 12 8 @{ 309 312 324 327 329 339 0 387 @}}
@end example
In this example we have retrieved all texts written by person five. The
first call asked for 100 texts, but only 8 were returned, which implies
that person number 5 only created a total of 8 texts. The second call
shows how a part of the map can be retrieved.
that person number 5 only created a total of 8 texts. We can also see
that person 5 wrote all the first 8 texts in the conference system. The
second call shows how a part of the map can be retrieved.
The third call asks for eight texts written by person 10, starting with
the eighth number. Since the first eleven texts written by that person
no longer exists the server instead returns information about eight
texts staring from the twelfth text person 10 created. One of the eight
texts has been deleted.
@unnumberedsubsubsec Error codes
......
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