Node:get-map, Next:get-time, Previous:sub-comment, Up:Protocol Requests
get-map [34] (( conf-no : Conf-No;
first-local-no : Local-Text-No;
no-of-texts : INT32 ))
-> ( Text-List );
This call has been superseded by local-to-global.
This call retrieves an array mapping local text numbers to global
numbers. It is most often used to get a list of unread texts in a
conference. Clients will usually use the query-read-texts or
get-membership calls to find the last local number a user has
read in a particular conference, then use the get-map call to
retrieve the global numbers of all unread texts in the conference.
The conf-no parameter specifies which conference to get the map
of. first-local-no is the local number of the first text returned
by the call. no-of-texts is the maximum number of text the client
wants.
The result is a list of global text numbers. The first element of the
list is the global number of local number first-local-no,
specified by the call; the second element is the global number of local
number first-local-no plus one; and so forth. The list returned
by the server is at most no-of-texts long, but may be shorter if
the call specifies more texts that there are in the conference.
If first-local-no is higher than the highest local text number,
the server will return an error.
If first-local-no is lower than the lowest number that still
exists, the server will set 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
first-local-no is increased. This may result in an empty array
being returned. (This paragraph applies even when first-local-no
is 0.)
If no texts at all exists in conf-no the resulting array will be
empty, and first-local-no will be set to the number the next text
to be created will receive.
Example:
1 34 119 10 5
=1 10 5 { 0 0 466 478 391 }
2 34 119 16 5
=2 16 3 { 481 0 491 }
3 34 119 19 5
%3 16 0
4 34 120 1 5
=4 4 2 { 480 485 }
5 34 120 1 2
=5 4 0 *
This example shows five 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.
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
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.
login-first
undefined-conference
conf-no does not exist or is secret.
conference-zero
conf-no is zero.
access-denied
conf-no is read protected.
no-such-local-text
first-local-no is higher than the highest local text number that
ever has existed in this conference.