ldapext-ldapv3-vlv-04.txt

samba最新软件

INTERNET-DRAFT                                   David Boreham, Netscape
                                                 Jim Sermersheim, Novell
                                                Anoop Anantha, Microsoft
                                               Michael Armijo, Microsoft
ldapext Working Group                                      6 April, 2000


     LDAP Extensions for Scrolling View Browsing of Search Results

                  draft-ietf-ldapext-ldapv3-vlv-04.txt
                This document expires on 5 October 2000

1.  Status of this Memo

This document is an Internet-Draft and is in full conformance  with  all
provisions  of Section 10 of RFC2026.  Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and  its
working  groups.   Note  that  other  groups may also distribute working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum  of  six  months
and  may  be  updated,  replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet- Drafts as reference material
or to cite them other than as "work in progress."

The   list   of   current   Internet-Drafts   can   be    accessed    at
http://www.ietf.org/ietf/1id-abstracts.txt

The list  of  Internet-Draft  Shadow  Directories  can  be  accessed  at
http://www.ietf.org/shadow.html.

2.  Abstract

This document describes a Virtual List View control  extension  for  the
LDAP  Search  operation.  This control is designed to allow the "virtual
list box" feature, common in existing  commercial  e-mail  address  book
applications, to be supported efficiently by LDAP servers. LDAP servers'
inability to support this client feature is a significant impediment  to
LDAP replacing proprietary protocols in commercial e-mail systems.

The control allows a client to specify that the  server  return,  for  a
given  LDAP search with associated sort keys, a contiguous subset of the
search result set. This subset is specified in terms of offsets into the
ordered list, or in terms of a greater than or equal comparison value.

3.  Background

A Virtual List is a graphical user interface  technique  employed  where



Boreham et al                                                   [Page 1]





RFC DRAFT                                                     April 2000


ordered lists containing a large number of entries need to be displayed.
A window containing a small number of visible list entries is drawn. The
visible  portion of the list may be relocated to different points within
the list by means of user input. This input  can  be  to  a  scroll  bar
slider; from cursor keys; from page up/down keys; from alphanumeric keys
for "typedown".  The user is given the impression that they  may  browse
the  complete  list  at  will,  even  though  it may contain millions of
entries. It is the fact  that  the  complete  list  contents  are  never
required  at  any one time that characterizes Virtual List View.  Rather
than fetch the complete list from wherever it is stored (typically  from
disk  or  a  remote  server), only that information which is required to
display the part of the list currently in view is fetched.  The  subject
of  this  document is the interaction between client and server required
to implement this functionality in the context of  the  results  from  a
sorted LDAP search request.

For example, suppose an e-mail address book application displays a  list
view  onto  the  list  containing the names of all the holders of e-mail
accounts at a large  university.  The  list  is  sorted  alphabetically.
While  there  may  be  tens  of  thousands  of entries in this list, the
address book list view displays only 20 such accounts at any  one  time.
The  list has an accompanying scroll bar and text input window for type-
down.  When first displayed, the list view shows the first 20 entries in
the  list,  and  the  scroll  bar slider is positioned at the top of its
range. Should the user drag the slider to the bottom of its  range,  the
displayed  contents  of the list view should be updated to show the last
20 entries in the list. Similarly, if the slider is positioned somewhere
in  the  middle  of  its travel, the displayed contents of the list view
should be updated to contain the 20 entries  located  at  that  relative
position  within the complete list.  Starting from any display point, if
the user uses the cursor keys or clicks on the  scroll  bar  to  request
that  the  list  be scrolled up or down by one entry, the displayed con-
tents should be updated to reflect this. Similarly the  list  should  be
displayed  correctly  when  the  user requests a page scroll up or down.
Finally, when the user types characters in  the  type-down  window,  the
displayed  contents of the list should "jump" or "seek" to the appropri-
ate point within the list.  For example, if  the  user  types  "B",  the
displayed  list could center around the first user with a name beginning
with the letter "B".  When this happens, the scroll  bar  slider  should
also be updated to reflect the new relative location within the list.

This document defines a request control which extends  the  LDAP  search
operation.  Always  used  in  conjunction  with  the server side sorting
control[SSS], this allows a client  to  retrieve  selected  portions  of
large  search result set in a fashion suitable for the implementation of
a virtual list view.

The key words "MUST", "SHOULD", and "MAY" used in this document  are  to



Boreham et al                                                   [Page 2]





RFC DRAFT                                                     April 2000


be interpreted as described in [Bradner97].

4.  Client-Server Interaction

The Virtual List View control extends a regular  LDAP  Search  operation
which must also include a server-side sorting control[SSS].  Rather than
returning the complete set of  appropriate  SearchResultEntry  messages,
the server is instructed to return a contiguous subset of those entries,
taken from the sorted result set, centered around  a  particular  target
entry. Henceforth, in the interests of brevity, the sorted search result
set will be referred to as "the list".

The sort control MAY  contain  any  sort  specification  valid  for  the
server.  The  attributeType field in the first SortKeyList sequence ele-
ment has special significance for "typedown".

The desired target entry, and the number of entries to be returned  both
before,  and after, that target entry in the list, are determined by the
client's VirtualListViewRequest control.

When the server returns the set of entries to the client, it attaches  a
VirtualListViewResponse  control  to  the SearchResultDone message.  The
server returns in this control: its current estimate for the  list  con-
tent  count,  the  location  within the list corresponding to the target
entry, and any error codes.

The target entry is specified in the VirtualListViewRequest  control  by
one  of  two methods. The first method is for the client to indicate the
target entry's offset within the list.  The second way is for the client
to  supply  an  attribute assertion value. The value is compared against
the values of the attribute specified as the primary  sort  key  in  the
sort  control  attached  to the search operation.  The first sort key in
the SortKeyList is the primary sort key.  The target entry is the  first
entry  in  the  list with value greater than or equal to (in the primary
sort order), the presented value.  The  order  is  determined  by  rules
defined  in  [SSS].   Selection  of  the  target  entry by this means is
designed to implement "typedown".  Note that  it  is  possible  that  no
entry  satisfies  these  conditions,  in  which  case there is no target
entry. This condition is indicated by the server returning  the  special
value contentCount + 1 in the target position field.

Because the server may not have an accurate estimate of  the  number  of
entries in the list, and to take account of cases where the list size is
changing during the time the user browses  the  list,  and  because  the
client  needs  a  way  to indicate specific list targets "beginning" and
"end", offsets within the list are transmitted between client and server
as  ratios---offset  to content count. The server sends its latest esti-
mate as to the number of entries in the  list  (content  count)  to  the



Boreham et al                                                   [Page 3]





RFC DRAFT                                                     April 2000


client  in  every  response control.  The client sends its assumed value
for the content count in every request control.  The server examines the
content  count  and  offsets  presented  by  the client and computes the
corresponding offsets within the list, based on its own idea of the con-
tent count.

     Si = Sc * (Ci / Cc)

     Where:
     Si is the actual list offset used by the server
     Sc is the server's estimate for content count
     Ci is the client's submitted offset
     Cc is the client's submitted content count
     The result is rounded to the nearest integer.

If the content count is stable, and the client returns to the server the
content  count most recently received, Cc = Sc and the offsets transmit-
ted become the actual server list offsets.

The following special cases are allowed:  a  client  sending  a  content
count  of zero (Cc = 0) means "client has no idea what the content count
is, server MUST use its own content  count  estimate  in  place  of  the
client's".  An offset value of one (Ci = 1) always means that the target
is the first entry in the list. Client specifying an offset which equals
the  content count specified in the same request control (Ci = Cc) means
that the target is the last entry in the list.  Ci may only  equal  zero
when Cc is also zero. This signifies the last entry in the list.

Because the server always returns contentCount and  targetPosition,  the
client  can always determine which of the returned entries is the target
entry. Where the number of entries returned is the same  as  the  number
requested,  the  client  is able to identify the target by simple arith-
metic. Where the number of entries returned  is  not  the  same  as  the
number  requested  (because the requested range crosses the beginning or
end of the list, or both), the client must use the target  position  and
content  count  values  returned  by  the  server to identify the target
entry. For example, suppose that 10 entries before and 10 after the tar-
get  were  requested, but the server returns 13 entries, a content count
of 100 and a target position of 3. The client  can  determine  that  the
first entry must be entry number 1 in the list, therefore the 13 entries
returned are the first 13 entries in the list, and  the  target  is  the
third one.

A server-generated context identifier MAY be  returned  to  clients.   A
client  receiving  a  context identifier SHOULD return it unchanged in a
subsequent request which relates to the same list.  The purpose of  this
interaction  is  to enhance the performance and effectiveness of servers
which employ approximate positioning.



Boreham et al                                                   [Page 4]





RFC DRAFT                                                     April 2000


5.  The Controls

Support for the virtual list view control extension is indicated by  the
presence  of  the  OID "2.16.840.1.113730.3.4.9" in the supportedControl
attribute of a server's root DSE.

5.1.  Request Control

This control is included in the SearchRequest message  as  part  of  the
controls  field  of  the  LDAPMessage,  as  defined in Section 4.1.12 of
[LDAPv3].  The controlType is set to "2.16.840.1.113730.3.4.9". The cri-
ticality   SHOULD be set to TRUE. If this control is included in a Sear-
chRequest message, a Server Side Sorting request control [SSS] MUST also
be  present  in  the  message. The controlValue is an OCTET STRING whose
value is the BER-encoding of the following SEQUENCE:

          VirtualListViewRequest ::= SEQUENCE {
                  beforeCount    INTEGER (0..maxInt),
                  afterCount     INTEGER (0..maxInt),
                  CHOICE {
                          byoffset [0] SEQUENCE {
                           offset          INTEGER (0 .. maxInt),
                           contentCount    INTEGER (0 .. maxInt) },
                          greaterThanOrEqual [1] AssertionValue },
                  contextID     OCTET STRING OPTIONAL }

beforeCount indicates how many  entries  before  the  target  entry  the
client  wants  the  server  to  send. afterCount indicates the number of
entries after the target entry the client  wants  the  server  to  send.
offset and contentCount identify the target entry as detailed in section
4.  greaterThanOrEqual  is  an  attribute  assertion  value  defined  in
[LDAPv3].  If  present, the value supplied in greaterThanOrEqual is used
to determine the target entry by  comparison  with  the  values  of  the
attribute  specified as the primary sort key. The first list entry who's
value is no less than (less than or equal to  when  the  sort  order  is
reversed)  the  supplied value is the target entry. If present, the con-
textID field contains the value of the most recently received  contextID
field  from  a  VirtualListViewResponse control. The type AssertionValue
and value maxInt are defined in  [LDAPv3].   contextID  values  have  no
validity outwith the connection on which they were received.  That is, a
client should not submit a contextID which it received from another con-
nection, a connection now closed, or a different server.


5.2.  Response Control

This control is included in the SearchResultDone message as part of  the
controls   field  of the  LDAPMessage, as  defined in Section  4.1.12 of



Boreham et al                                                   [Page 5]





RFC DRAFT                                                     April 2000


[LDAPv3].

The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is
FALSE (MAY be absent).  The controlValue is an OCTET STRING, whose value
is the BER encoding of a value of the following SEQUENCE:

     VirtualListViewResponse ::= SEQUENCE {
             targetPosition    INTEGER (0 .. maxInt),
             contentCount     INTEGER (0 .. maxInt),
             virtualListViewResult ENUMERATED {
             success (0),
             operationsError (1),
             unwillingToPerform (53),
             insufficientAccessRights (50),
             busy (51),
             timeLimitExceeded (3),
             adminLimitExceeded (11),
             sortControlMissing (60),
             offsetRangeError (61),
             other (80) },
             contextID     OCTET STRING OPTIONAL }

targetPosition gives the list offset for the target entry.  contentCount
gives  the  server's  estimate  of  the current number of entries in the
list.  Together these give sufficient  information  for  the  client  to
update  a  list box slider position to match the newly retrieved entries
and identify the target entry. The contentCount value returned SHOULD be