ldapext-ldapv3-vlv-04.txt

samba最新软件

used  in  a  subsequent  VirtualListViewRequest control.  contextID is a
server-defined octet string. If present, the contents of  the  contextID
field  SHOULD be returned to the server by a client in a subsequent Vir-
tualListViewRequest control.

The virtualListViewResult codes which  are  common  to  the  LDAP  sear-
chResponse  (adminLimitExceeded,  timeLimitExceeded, busy, operationsEr-
ror, unwillingToPerform, insufficientAccessRights) have the  same  mean-
ings  as  defined  in [LDAPv3], but they pertain specifically to the VLV
operation.  For example, the server could exceed an administration limit
processing  a  SearchRequest with a VirtualListViewRequest control. How-
ever, the same administration limit would not  be  exceeded  should  the
same  SearchRequest  be submitted by the client without the VirtualList-
ViewRequest control.  In this case, the client  can  determine  that  an
administration limit has been exceeded in servicing the VLV request, and
can if it chooses resubmit the SearchRequest  without  the  VirtualList-
ViewRequest control.

insufficientAccessRights means that the server denied the client permis-
sion to perform the VLV operation.




Boreham et al                                                   [Page 6]





RFC DRAFT                                                     April 2000


If the server determines that the results of the search presented exceed
the  range  provided  by  the  32-bit  offset  values,  it  MUST  return
offsetRangeError.

6.  Protocol Example

Here we walk through the client-server interaction for a  specific  vir-
tual list view example:  The task is to display a list of all 78564 peo-
ple in the US company "Ace Industry".  This will be done by  creating  a
graphical  user  interface  object  to display the list contents, and by
repeatedly sending different versions of  the  same  virtual  list  view
search  request  to the server. The list view displays 20 entries on the
screen at a time.

We form a search with baseDN "o=Ace Industry, c=us"; search  scope  sub-
tree;  filter "objectClass=inetOrgPerson". We attach a server sort order
control to the search, specifying ascending sort on attribute  "cn".  To
this  base  search,  we  attach a virtual list view request control with
contents determined by the user activity and  send  the  search  to  the
server.  We  display the results from each search in the list window and
update the slider position.

When the list view is first displayed, we want to  initialize  the  con-
tents showing the beginning of the list. Therefore, we set beforeCount =
0, afterCount = 19, contentCount = 0, offset = 1 and send the request to
the  server.  The  server duly returns the first 20 entries in the list,
plus the content count = 78564 and  targetPosition  =  1.  We  therefore
leave  the  scroll  bar  slider  at its current location (the top of its
range).

Say that next the user drags the scroll bar slider down to the bottom of
its  range.   We now wish to display the last 20 entries in the list, so
we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset  =
78564 and send the request to the server. The server returns the last 20
entries in the list, plus the content count = 78564 and targetPosition =
78564.

Next the user presses a page up key. Our page size  is  20,  so  we  set
beforeCount  =  0,  afterCount  =  19,  contentCount  =  78564, offset =
78564-19-20 and send the request to the server. The server  returns  the
preceding  20  entries  in  the list, plus the content count = 78564 and
targetPosition = 78525.

Now the user grabs the scroll bar slider and drags it to 68% of the  way
down its travel. 68% of 78564 is 53424 so we set beforeCount = 9, after-
Count = 10, contentCount = 78564, offset = 53424 and send the request to
the  server.  The  server  returns the preceding 20 entries in the list,
plus the content count = 78564 and targetPosition = 53424.



Boreham et al                                                   [Page 7]





RFC DRAFT                                                     April 2000


Lastly, the user types the letter "B". We set beforeCount  =  9,  after-
Count  =  10  and  greaterThanOrEqual  = "B". The server finds the first
entry in the list not less  than  "B",  let's  say  "Babs  Jensen",  and
returns the nine preceding entries, the target entry, and the proceeding
10 entries.  The server returns content count = 78564 and targetPosition
=  5234  and so the client updates its scroll bar slider to 6.7% of full
scale.

7.  Notes for Implementers

While the feature is expected  to  be  generally  useful  for  arbitrary
search  and  sort  specifications, it is specifically designed for those
cases where the result set is very large.  The intention  is  that  this
feature be implemented efficiently by means of pre-computed indices per-
taining to a set of specific cases. For example, an offset  relating  to
"all  the  employees in the local organization, sorted by surname" would
be a common case.

The intention for client software is that the feature should fit  easily
with  the  host  platform's  graphical user interface facilities for the
display of scrolling lists. Thus the task  of  the  client  implementers
should  be  one of reformatting up the requests for information received
from the list view code to match the format of  the  virtual  list  view
request and response controls.

Client implementers should note that any offset value  returned  by  the
server  may  be  approximate. Do not design clients > which only operate
correctly when offsets are exact.

Server implementers using indexing technology which features approximate
positioning  should  consider  returning context identifiers to clients.
The use of a context identifier will allow  the  server  to  distinguish
between client requests which relate to different displayed lists on the
client. Consequently the server can decide more intelligently whether to
reposition an existing database cursor accurately to within a short dis-
tance of its current position, or to reposition to an approximate  posi-
tion. Thus the client will see precise offsets for "short" repositioning
(e.g. paging up or down), but approximate offsets for a  "long"  reposi-
tion (e.g. a slider movement).

Server implementers are free to return  status  code  unwillingToPerform
should  their  server  be  unable  to service any particular VLV search.
This might be because the resolution of the  search  is  computationally
infeasible,  or  because excessive server resources would be required to
service the search.

Client implementers should note that this control is only defined  on  a
client  interaction  with a single server. If a server returns referrals



Boreham et al                                                   [Page 8]





RFC DRAFT                                                     April 2000


as a part of its response to the search request, the client is responsi-
ble  for  deciding when and how to apply this control to the referred-to
servers, and how to collate the results from multiple servers.


8.  Relationship to "Simple Paged Results"

These controls are designed to support the virtual list view, which  has
proved  hard  to  implement  with  the  Simple  Paged  Results mechanism
[SPaged]. However, the controls described  here  support  any  operation
possible with the Simple Paged Results mechanism. The two mechanisms are
not complementary, rather one has a superset of  the  other's  features.
One  area where the mechanism presented here is not a strict superset of
the Simple Paged Results scheme is that here we require a sort order  to
be specified. No such requirement is made for paged results.


9.  Security Considerations

Server implementers may wish to consider whether  clients  are  able  to
consume  excessive  server  resources  in requesting virtual list opera-
tions. Access control to the feature itself; configuration options  lim-
iting  the  feature's  use  to certain predetermined search base DNs and
filters; throttling mechanisms designed to limit  the  ability  for  one
client to soak up server resources, may be appropriate.

Consideration should be given as to whether a client  will  be  able  to
retrieve  the complete contents, or a significant subset of the complete
contents of the directory using this feature. This may be undesirable in
some  circumstances and consequently it may be necessary to enforce some
access control.

Clients can, using this control, determine how  many  entries  are  con-
tained  within  a  portion  of  the  DIT. This may constitute a security
hazard. Again, access controls may be appropriate.

Server implementers SHOULD exercise caution concerning  the  content  of
the  contextID.   Should the contextID contain internal server state, it
may be possible for a malicious client to use that information  to  gain
unauthorized access to information.

10.  Acknowledgements

Chris Weider of Microsoft co-authored a previous version of  this  docu-
ment.






Boreham et al                                                   [Page 9]





RFC DRAFT                                                     April 2000


11.  References

[LDAPv3]
     Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access  Pro-
     tocol (v3)", Internet Standard, December, 1997. RFC2251.

[SPaged]
     Weider, C, A. Herron, A.  Anantha,  and  T.  Howes,  "LDAP  Control
     Extension  for  Simple   Paged   Results   Manipulation", September
     1999. RFC2696

[SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
     Side  Sorting  of  Search  Results",  Internet  Draft, April, 1999.
     Available as draft-ietf-asid-ldapv3-sorting-02.txt.

[Bradner97]
     Bradner, S., "Key Words for use in  RFCs  to  Indicate  Requirement
     Levels", BCP 14, RFC 2119, March 1997.

12.  Authors' Addresses

   David Boreham
   iPlanet e-commerce solutions
   501 E. Middlefield Road
   Mountain View, CA 94043, USA
   [phone]
   [e-mail]

   Jim Sermersheim
   Novell
   122 East 1700 South
   Provo, Utah 84606, USA
   [e-mail]

   Anoop Anantha
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052, USA
   [phone]
   [e-mail]

   Michael Armijo
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052, USA
   [phone]
   [e-mail]
   This document expires on 5 October 2000



Boreham et al                                                  [Page 10]





RFC DRAFT                                                     April 2000





















































Boreham et al                                                  [Page 11]