Node:get-map, Next:, Previous:sub-comment, Up:Protocol Requests

get-map [34] (1) Obsolete (10)

        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.


        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.

Error codes

Login required before issuing this call.
Conference conf-no does not exist or is secret.
conf-no is zero.
Conference conf-no is read protected.
first-local-no is higher than the highest local text number that ever has existed in this conference.