Node:query-read-texts, Next:, Previous:set-pers-flags, Up:Protocol Requests



query-read-texts [107] (11) Recommended


        query-read-texts [107] (( person           : Pers-No;
                                  conference       : Conf-No;
                                  want-read-ranges : BOOL;
                                  max-ranges       : INT32 ))
                -> ( Membership );

This call is used to find the number of unread texts in a conference. The data it returns is actually a membership structure which specifies which texts have been read. It is up to the client to transform the data to a more usable form. person is the person being queried and conference is the conference in question.

If want-read-ranges is 0, the server will not send the contents of the read-ranges array of the memberships. (The size will be transmitted, but a single asterisk (*) will be sent instead of the array itself.) The max-ranges argument is ignored in this case.

If want-read-ranges is 1, the read-ranges array will be returned. If max-ranges is non-zero, the array will be truncated to max-ranges ranges. (It isn't possible to determine if the array has been truncated, or if the array actually contained exactly that many ranges.) Setting max-ranges to 1 gives you enough information to find out the first unread text.

When you call this request with want-read-ranges set to 1, the ranges will expand to include any adjacent texts that are now deleted. This may not happen if get-membership is used to retrieve the information.

Calling query-read-texts does not require the session to be logged in.

Example:

        1 107 6 1 1 0
        =1 4 32 5 11 12 7 93 1 193 1 1 20
           2 { 1 133 135 137 } 5 43 8 3 12 7 93 1 193 1 01000000

This example finds the read texts for user 6 in conference 1. The returned data indicates that conference 1 is the fifth conference on the users' membership list (4; remember that the position starts its count at 0), user last read the conference on Monday July 12th, 1993 at 11:05:32 (32 5 11 12 7 93 1 193 1), that it is the membership in conference number 1 (1), that the person has assigned priority 20 to the conference (20) and that all texts 1-133 and 135-137 have been read (2 { 1 133 135 137 }). The membership was added by person 5 (5) at Monday July 12th, 1993 at 03:08:43 (43 8 3 12 7 93 1 193 1) and it is passive (01000000).

Error codes

undefined-person
person does not exist, or no access to person.
undefined-conference
Conference conference does not exist, or is secret.
conference-zero
conference is zero.
not-member
person is not a member of conference or insufficient privileges to find out if person is a member.
bad-bool
want-read-ranges must be either 0 or 1.