upstream/openldap
1
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2025-12-20 22:59:34 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update to -09, last available revision

Browse source
This commit is contained in:
Howard Chu 2009-02-05 20:50:26 +00:00
parent 8227ed9f71
commit e780309a0c
1 changed files with 341 additions and 227 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

552
doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt
View file

@ -2,8 +2,8 @@
Internet-Draft D. Boreham, Bozeman Pass Internet-Draft D. Boreham, Bozeman Pass
LDAPext Working Group J. Sermersheim, Novell LDAPext Working Group J. Sermersheim, Novell
Intended Category: Standards Track A. Kashi, Microsoft Intended Category: Standards Track A. Kashi, Microsoft
<draft-ietf-ldapext-ldapv3-vlv-06.txt> <draft-ietf-ldapext-ldapv3-vlv-09.txt>
Expires: Nov 2002 May 2002 Expires: Jun 2003 Nov 2002
LDAP Extensions for Scrolling View Browsing of Search Results LDAP Extensions for Scrolling View Browsing of Search Results
@ -37,16 +37,16 @@ Expires: Nov 2002 May 2002
2. Abstract 2. Abstract
This document describes a Virtual List View control extension for the This document describes a Virtual List View extension for the
Lightweight Directory Access Protocol (LDAP) Search operation. This Lightweight Directory Access Protocol (LDAP) Search operation. This
control is designed to allow the "virtual list box" feature, common extension is designed to allow the "virtual list box" feature, common
in existing commercial e-mail address book applications, to be in existing commercial e-mail address book applications, to be
supported efficiently by LDAP servers. LDAP servers' inability to supported efficiently by LDAP servers. LDAP servers' inability to
support this client feature is a significant impediment to LDAP support this client feature is a significant impediment to LDAP
replacing proprietary protocols in commercial e-mail systems. replacing proprietary protocols in commercial e-mail systems.
The control allows a client to specify that the server return, for a The extension allows a client to specify that the server return, for
given LDAP search with associated sort keys, a contiguous subset of a given LDAP search with associated sort keys, a contiguous subset of
the search result set. This subset is specified in terms of offsets 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 into the ordered list, or in terms of a greater than or equal
comparison value. comparison value.
@ -54,13 +54,32 @@ Expires: Nov 2002 May 2002
Boreham et al Internet-Draft 1 Boreham et al Internet-Draft 1
LDAP Extensions for Scrolling View May 2002 LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results Browsing of Search Results
3. Conventions used in this document 3. Conventions used in this document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "SHALL", "SHOULD", "SHOULD NOT", and "MAY" in
"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are this document are to be interpreted as described in RFC 2119
to be interpreted as described in RFC 2119 [Bradner97]. [Bradner97].
Protocol elements are described using ASN.1 [X.680]. The term "BER-
encoded" means the element is to be encoded using the Basic Encoding
Rules [X.690] under the restrictions detailed in Section 5.1 of
[LDAPPROT].
The phrase "subsequent virtual list request" is used in this document
to describe a search request accompanied by a VirtualListViewRequest
control, where the search base, scope, and filter are the same as a
previous search request also accompanied by a VirtualListViewRequest
control, and where the contextID of the subsequent
VirtualListViewRequest control, is set to that of the contextID in
the VirtualListViewResponse control that accompanied the previous
search response.
The phrase "contiguous virtual list request" is used to describe a
subsequent virtual list request which is requesting search results
adjoining or overlapping the result returned from the prior virtual
list request.
4. Background 4. Background
@ -80,14 +99,21 @@ Expires: Nov 2002 May 2002
only that information which is required to display the part of the only that information which is required to display the part of the
list currently in view is fetched. The subject of this document is list currently in view is fetched. The subject of this document is
the interaction between client and server required to implement this the interaction between client and server required to implement this
functionality in the context of the results from a sorted LDAP search functionality in the context of the results from an ordered [SSS]
request. Lightweight Directory Access Protocol (LDAP) search operation
[LDAPPROT].
For example, suppose an e-mail address book application displays a 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- list view onto the list containing the names of all the holders of e-
mail accounts at a large university. The list is sorted mail accounts at a large university. The list is ordered
alphabetically. While there may be tens of thousands of entries in alphabetically. While there may be tens of thousands of entries in
this list, the address book list view displays only 20 such accounts this list, the address book list view displays only 20 such accounts
Boreham et al Internet-Draft 2
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
at any one time. The list has an accompanying scroll bar and text 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 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 the first 20 entries in the list, and the scroll bar slider is
@ -109,12 +135,6 @@ Expires: Nov 2002 May 2002
"B". When this happens, the scroll bar slider should also be updated "B". When this happens, the scroll bar slider should also be updated
to reflect the new relative location within the list. to reflect the new relative location within the list.
Boreham et al Internet-Draft 2
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
This document defines a request control which extends the LDAP search This document defines a request control which extends the LDAP search
operation. Always used in conjunction with the server side sorting operation. Always used in conjunction with the server side sorting
control [SSS], this allows a client to retrieve selected portions of control [SSS], this allows a client to retrieve selected portions of
@ -125,21 +145,32 @@ Expires: Nov 2002 May 2002
5. Client-Server Interaction 5. Client-Server Interaction
The Virtual List View control extends a regular LDAP Search operation The Virtual List View control extends a regular LDAP Search operation
which must also include a server-side sorting control [SSS]. Rather which MUST also include a server-side sorting control [SSS]. Rather
than returning the complete set of appropriate SearchResultEntry than returning the complete set of appropriate SearchResultEntry
messages, the server is instructed to return a contiguous subset of messages, the server is instructed to return a contiguous subset of
those entries, taken from the sorted result set, centered around a those entries, taken from the ordered result set, centered around a
particular target entry. Henceforth, in the interests of brevity, the particular target entry. Henceforth, in the interests of brevity, the
sorted search result set will be referred to as "the list". ordered search result set will be referred to as "the list".
The sort control MAY contain any sort specification valid for the The sort control may contain any sort specification valid for the
server. The attributeType field in the first SortKeyList sequence server. The attributeType field in the first SortKeyList sequence
element has special significance for "typedown". element has special significance for "typedown". The Virtual List
View control acts upon a set of ordered entries and this order must
be repeatable for all subsequent virtual list requests. The server-
side sorting control is intended to aid in this ordering, but other
mechanisms may need to be employed to produce a repeatable order--
especially for entries that don't have a value of the sort key.
The desired target entry and the number of entries to be returned, The desired target entry and the number of entries to be returned,
both before and after that target entry in the list, are determined both before and after that target entry in the list, are determined
by the client's VirtualListViewRequest control. by the client's VirtualListViewRequest control.
Boreham et al Internet-Draft 3
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
When the server returns the set of entries to the client, it attaches When the server returns the set of entries to the client, it attaches
a VirtualListViewResponse control to the SearchResultDone message. a VirtualListViewResponse control to the SearchResultDone message.
The server returns in this control: its current estimate for the list The server returns in this control: its current estimate for the list
@ -165,12 +196,6 @@ Expires: Nov 2002 May 2002
entries in the list, and to take account of cases where the list size 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 is changing during the time the user browses the list, and because
the client needs a way to indicate specific list targets "beginning" the client needs a way to indicate specific list targets "beginning"
Boreham et al Internet-Draft 3
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
and "end", offsets within the list are transmitted between client and and "end", offsets within the list are transmitted between client and
server as ratios---offset to content count. The server sends its server as ratios---offset to content count. The server sends its
latest estimate as to the number of entries in the list (content latest estimate as to the number of entries in the list (content
@ -197,11 +222,17 @@ Expires: Nov 2002 May 2002
offset and content count: offset and content count:
- an offset of one and a content count of non-one (Ci = 1, Cc != 1) - an offset of one and a content count of non-one (Ci = 1, Cc != 1)
indicates that the target is the first entry in the list. indicates that the target is the first entry in the list.
Boreham et al Internet-Draft 4
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
- equivalent values (Ci = Cc) indicate that the target is the last - equivalent values (Ci = Cc) indicate that the target is the last
entry in the list. entry in the list.
- a content count of zero, and a non-zero offset (Cc = 0, Ci != 0) - a content count of zero (Cc = 0, Ci != 0) means the client has no
means the client has no idea what the content count is, the server idea what the content count is, the server MUST use its own
MUST use its own content count estimate in place of the client's. content count estimate in place of the client's.
Because the server always returns contentCount and targetPosition, Because the server always returns contentCount and targetPosition,
the client can always determine which of the returned entries is the the client can always determine which of the returned entries is the
@ -209,7 +240,7 @@ Expires: Nov 2002 May 2002
number requested, the client is able to identify the target by simple number requested, the client is able to identify the target by simple
arithmetic. Where the number of entries returned is not the same as arithmetic. Where the number of entries returned is not the same as
the number requested (because the requested range crosses the the number requested (because the requested range crosses the
beginning or end of the list, or both), the client must use 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 target position and content count values returned by the server to
identify the target entry. For example, suppose that 10 entries identify the target entry. For example, suppose that 10 entries
before and 10 after the target were requested, but the server returns before and 10 after the target were requested, but the server returns
@ -218,18 +249,11 @@ Expires: Nov 2002 May 2002
the list, therefore the 13 entries returned are the first 13 entries the list, therefore the 13 entries returned are the first 13 entries
in the list, and the target is the third one. in the list, and the target is the third one.
A server-generated context identifier MAY be returned to clients. A A server-generated contextID MAY be returned to clients. A client
client receiving a context identifier SHOULD return it unchanged in a receiving a contextID MUST return it unchanged or not return it at
subsequent request which relates to the same list. The purpose of all, in a subsequent request which relates to the same list. The
purpose of this interaction is to maintain state information between
the client and server.
Boreham et al Internet-Draft 4
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
this interaction is to enhance the performance and effectiveness of
servers which employ approximate positioning.
6. The Controls 6. The Controls
@ -242,56 +266,89 @@ Expires: Nov 2002 May 2002
This control is included in the SearchRequest message as part of the 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 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 [LDAPPROT]. The controlType is set to "2.16.840.1.113730.3.4.9". If
criticality SHOULD be set to TRUE. If this control is included in a this control is included in a SearchRequest message, a Server Side
SearchRequest message, a Server Side Sorting request control [SSS] Sorting request control [SSS] MUST also be present in the message.
MUST also be present in the message. The controlValue is an OCTET The controlValue, an OCTET STRING, is the BER-encoding of the
STRING whose value is the BER-encoding of the following SEQUENCE: following SEQUENCE:
VirtualListViewRequest ::= SEQUENCE { VirtualListViewRequest ::= SEQUENCE {
beforeCount INTEGER (0..maxInt), beforeCount INTEGER (0..maxInt),
afterCount INTEGER (0..maxInt), afterCount INTEGER (0..maxInt),
CHOICE { target CHOICE {
byoffset [0] SEQUENCE { byOffset [0] SEQUENCE {
offset INTEGER (0 .. maxInt), offset INTEGER (1 .. maxInt),
contentCount INTEGER (0 .. maxInt) }, contentCount INTEGER (0 .. maxInt) },
Boreham et al Internet-Draft 5
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
greaterThanOrEqual [1] AssertionValue }, greaterThanOrEqual [1] AssertionValue },
contextID OCTET STRING OPTIONAL } contextID OCTET STRING OPTIONAL }
beforeCount indicates how many entries before the target entry the beforeCount indicates how many entries before the target entry the
client wants the server to send. afterCount indicates the number of client wants the server to send.
entries after 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 offset and contentCount identify the target entry as detailed in
section 4. greaterThanOrEqual is an attribute assertion value defined section 5.
in [LDAPv3]. If present, the value supplied in greaterThanOrEqual is
used to determine the target entry by comparison with the values of greaterThanOrEqual is a matching rule assertion value defined in
the attribute specified as the primary sort key. The first list entry [LDAPPROT]. The assertion value is encoded according to the ORDERING
matching rule for the attributeDescription in the sort control [SSS].
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 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 order is reversed) the supplied value is the target entry.
present, the contextID field contains the value of the most recently
received contextID field from a VirtualListViewResponse control. The If present, the contextID field contains the value of the most
type AssertionValue and value maxInt are defined in [LDAPv3]. recently received contextID field from a VirtualListViewResponse
contextID values have no validity outwith the connection on which control for the same list view. If the contextID is not known because
they were received. That is, a client should not submit a contextID no contextID has been sent by the server in a VirtualListViewResponse
which it received from another connection, a connection now closed, control, it SHALL be omitted. If the server receives a contextID that
or a different server. is invalid, it SHALL fail the search operation and indicate the
failure with a protocolError (3) value in the virtualListViewResult
field of the VirtualListViewResponse. The contextID provides state
information between the client and server. This state information is
used by the server to ensure continuity contiguous virtual list
requests. When a server receives a VirtualListViewRequest control
that includes a contextID, it SHALL determine whether the client has
sent a contiguous virtual list request and SHALL provide contiguous
entries if possible. If a valid contextID is sent, and the server is
unable to determine whether contiguous data is requested, or is
unable to provide requested contiguous data, it SHALL fail the search
operation and indicate the failure with an unwillingToPerform (53)
value in the virtualListViewResult field of the
VirtualListViewResponse. contextID values have no validity outside
the connection and query with which they were received. A client MUST
NOT submit a contextID which it received from a different connection,
a different query, or a different server.
The type AssertionValue and value maxInt are defined in [LDAPPROT].
6.2. Response Control 6.2. Response Control
Boreham et al Internet-Draft 5
Boreham et al Internet-Draft 6
LDAP Extensions for Scrolling View May 2002 LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results Browsing of Search Results
This control is included in the SearchResultDone message as part of If the request control is serviced, this response control is included
the controls field of the LDAPMessage, as defined in Section 4.1.12 in the SearchResultDone message as part of the controls field of the
of [LDAPv3]. LDAPMessage, as defined in Section 4.1.12 of [LDAPPROT].
The controlType is set to "2.16.840.1.113730.3.4.10". The criticality The controlType is set to "2.16.840.1.113730.3.4.10". The
is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose controlValue, an OCTET STRING, is the BER-encoding of the following
value is the BER encoding of a value of the following SEQUENCE: SEQUENCE:
VirtualListViewResponse ::= SEQUENCE { VirtualListViewResponse ::= SEQUENCE {
targetPosition INTEGER (0 .. maxInt), targetPosition INTEGER (0 .. maxInt),
@ -299,128 +356,137 @@ Expires: Nov 2002 May 2002
virtualListViewResult ENUMERATED { virtualListViewResult ENUMERATED {
success (0), success (0),
operationsError (1), operationsError (1),
protocolError (3),
unwillingToPerform (53), unwillingToPerform (53),
insufficientAccessRights (50), insufficientAccessRights (50),
busy (51),
timeLimitExceeded (3), timeLimitExceeded (3),
adminLimitExceeded (11), adminLimitExceeded (11),
innapropriateMatching (18),
sortControlMissing (60), sortControlMissing (60),
offsetRangeError (61), offsetRangeError (61),
other (80) }, other(80),
... },
contextID OCTET STRING OPTIONAL } contextID OCTET STRING OPTIONAL }
targetPosition gives the list offset for the target entry. targetPosition gives the list offset for the target entry.
contentCount gives the server's estimate of the current number of contentCount gives the server's estimate of the current number of
entries in the list. Together these give sufficient information for entries in the list. Together these give sufficient information for
the client to update a list box slider position to match the newly the client to update a list box slider position to match the newly
retrieved entries and identify the target entry. The contentCount retrieved entries and identify the target entry. The contentCount
value returned SHOULD be used in a subsequent VirtualListViewRequest value returned SHOULD be used in a subsequent VirtualListViewRequest
control. contextID is a server-defined octet string. If present, the control.
contents of the contextID field SHOULD be returned to the server by a
client 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 virtual list request. The presence of a contextID
here indicates that the server is willing to return contiguous data
from a subsequent search request which uses the same search criteria,
accompanied by a VirtualListViewRequest which indicates that the
client wishes to receive an adjoining page of data.
The virtualListViewResult codes which are common to the LDAP The virtualListViewResult codes which are common to the LDAP
searchResponse (adminLimitExceeded, timeLimitExceeded, busy, searchResultDone (adminLimitExceeded, timeLimitExceeded,
operationsError, unwillingToPerform, insufficientAccessRights) have operationsError, unwillingToPerform, insufficientAccessRights,
the same meanings as defined in [LDAPv3], but they pertain success, other) have the same meanings as defined in [LDAPPROT], but
specifically to the VLV operation. For example, the server could they pertain specifically to the VLV operation. For example, the
exceed an administration limit processing a SearchRequest with a server could exceed a VLV-specific administrative limit while
VirtualListViewRequest control. However, the same administration processing a SearchRequest with a VirtualListViewRequest control.
limit would not be exceeded should the same SearchRequest be Obviously, the same administrative limit would not be exceeded should
submitted by the client without the VirtualListViewRequest control.
In this case, the client can determine that an administration limit Boreham et al Internet-Draft 7
has been exceeded in servicing the VLV request, and can if it chooses
resubmit the SearchRequest without the VirtualListViewRequest LDAP Extensions for Scrolling View Nov 2002
control. Browsing of Search Results
the same SearchRequest be submitted by the client without the
VirtualListViewRequest control. In this case, the client can
determine that the administrative limit has been exceeded in
servicing the VLV request, and can if it chooses resubmit the
SearchRequest without the VirtualListViewRequest control, or with
different parameters.
insufficientAccessRights means that the server denied the client insufficientAccessRights means that the server denied the client
permission to perform the VLV operation. permission to perform the VLV operation.
Boreham et al Internet-Draft 6
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
If the server determines that the results of the search presented If the server determines that the results of the search presented
exceed the range specified in INTEGER values, it MUST return exceed the range specified in INTEGER values, or if the client
offsetRangeError. specifies an invalid offset or contentCount, the server MUST set the
virtualListViewResult value to offsetRangeError.
6.2.1 virtualListViewError 6.2.1 virtualListViewError
A new LDAP error is introduced called virtualListViewError. Its value A new LDAP error is introduced called virtualListViewError. Its value
is 76. is 76. This error indicates that the search operation failed due to
[Note to the IESG/IANA/RFC Editor: the value 76 has been suggested by the inclusion of the VirtualListViewRequest control.
experts, had expert review, and is currently being used by some
implementations. The intent is to have this number designated as an
official IANA assigned LDAP Result Code (see draft-ietf-ldapbis-iana-
xx.txt, Section 3.5)]
If the server returns any code other than success (0) for
virtualListViewResult, then the server SHOULD return
virtualListViewError as the resultCode of the SearchResultDone
message.
If the resultCode in the SearchResultDone message is set to
virtualListViewError (76), then the virtualListViewResult value MUST
NOT be success (as virtualListViewResult indicates the specific error
condition). If resultCode in the SearchResultDone message is not set
to virtualListViewError (76), then the virtualListViewResult value
SHOULD be success (0) and its value MUST be ignored.
7. Protocol Example 7. Protocol Example
Here we walk through the client-server interaction for a specific Here we walk through the client-server interaction for a specific
virtual list view example: The task is to display a list of all 78564 virtual list view example: The task is to display a list of all 78564
people in the US company "Ace Industry". This will be done by persons in the US company "Ace Industry". This will be done by
creating a graphical user interface object to display the list creating a graphical user interface object to display the list
contents, and by repeatedly sending different versions of the same contents, and by repeatedly sending different versions of the same
virtual list view search request to the server. The list view virtual list view search request to the server. The list view
displays 20 entries on the screen at a time. displays 20 entries on the screen at a time.
We form a search with baseDN "o=Ace Industry, c=us"; search scope We form a search with baseObject of "o=Ace Industry,c=us"; scope of
subtree; filter "objectClass=inetOrgPerson". We attach a server sort wholeSubtree; and filter of "(objectClass=person)". We attach a
order control to the search, specifying ascending sort on attribute server-side sort control [SSS] to the search request, specifying
"cn". To this base search, we attach a virtual list view request ascending sort on attribute "cn". To this search request, we attach a
control with contents determined by the user activity and send the virtual list view request control with contents determined by the
search to the server. We display the results from each search in the user activity and send the search request to the server. We display
list window and update the slider position. the results from each search result entry in the list window and
update the slider position.
When the list view is first displayed, we want to initialize the When the list view is first displayed, we want to initialize the
contents showing the beginning of the list. Therefore, we set contents showing the beginning of the list. Therefore, we set
beforeCount = 0, afterCount = 19, contentCount = 0, offset = 1 and beforeCount to 0, afterCount to 19, contentCount to 0, offset to 1
send the request to the server. The server duly returns the first 20 and send the request to the server. The server duly returns the first
entries in the list, plus the content count = 78564 and
targetPosition = 1. We therefore leave the scroll bar slider at its Boreham et al Internet-Draft 8
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
20 entries in the list, plus a content count of 78564 and
targetPosition of 1. We therefore leave the scroll bar slider at its
current location (the top of its range). current location (the top of its range).
Say that next the user drags the scroll bar slider down to the bottom 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, of its range. We now wish to display the last 20 entries in the list,
so we set beforeCount = 19, afterCount = 0, contentCount = 78564, so we set beforeCount to 19, afterCount to 0, contentCount to 78564,
offset = 78564 and send the request to the server. The server returns offset to 78564 and send the request to the server. The server
returns the last 20 entries in the list, plus a content count of
78564 and a targetPosition of 78564.
Boreham et al Internet-Draft 7
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
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 Next the user presses a page up key. Our page size is 20, so we set
beforeCount = 0, afterCount = 19, contentCount = 78564, offset = beforeCount to 0, afterCount to 19, contentCount to 78564, offset to
78564-19-20 and send the request to the server. The server returns 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 the preceding 20 entries in the list, plus a content count of 78564
and targetPosition = 78525. and a targetPosition of 78525.
Now the user grabs the scroll bar slider and drags it to 68% of the 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, way down its travel. 68% of 78564 is 53424 so we set beforeCount to
afterCount = 10, contentCount = 78564, offset = 53424 and send the 9, afterCount to 10, contentCount to 78564, offset to 53424 and send
request to the server. The server returns the preceding 20 entries in the request to the server. The server returns the preceding 20
the list, plus the content count = 78564 and targetPosition = 53424. entries in the list, plus a content count of 78564 and a
targetPosition of 53424.
Lastly, the user types the letter "B". We set beforeCount = 9, Lastly, the user types the letter "B". We set beforeCount to 9,
afterCount = 10 and greaterThanOrEqual = "B". The server finds the afterCount to 10 and greaterThanOrEqual to "B". The server finds the
first entry in the list not less than "B", let's say "Babs Jensen", 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 and returns the nine preceding entries, the target entry, and the
proceeding 10 entries. The server returns content count = 78564 and proceeding 10 entries. The server returns a content count of 78564
targetPosition = 5234 and so the client updates its scroll bar slider and a targetPosition of 5234 and so the client updates its scroll bar
to 6.7% of full scale. slider to 6.7% of full scale.
8. Notes for Implementers 8. Notes for Implementers
@ -440,40 +506,44 @@ Expires: Nov 2002 May 2002
information received from the list view code to match the format of information received from the list view code to match the format of
the virtual list view request and response controls. 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
Boreham et al Internet-Draft 8 Boreham et al Internet-Draft 9
LDAP Extensions for Scrolling View May 2002 LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results Browsing of Search Results
accurately to within a short distance of its current position, or to Client implementers MUST be aware that any offset value returned by
reposition to an approximate position. Thus the client will see the server might be approximate. Do not design clients that only
precise offsets for "short" repositioning (e.g. paging up or down), operate correctly when offsets are exact. However, if contextIDs are
but approximate offsets for a "long" reposition (e.g. a slider used, and adjoining pages of information are requested, the server
movement). will return contiguous data.
Server implementers are free to return status code unwillingToPerform Server implementers using indexing technology which features
should their server be unable to service any particular VLV search. approximate positioning should consider returning contextIDs to
This might be because the resolution of the search is computationally clients. The use of a contextID will allow the server to distinguish
infeasible, or because excessive server resources would be required between client requests which relate to different displayed lists on
to service the search. the client. Consequently the server can decide more intelligently
whether to reposition an existing database cursor accurately to
within a short distance of its current position, or to reposition to
an approximate position. Thus the client will see precise offsets for
"short" repositioning (e.g. paging up or down), but approximate
offsets for a "long" reposition (e.g. a slider movement).
Server implementers are free to return an LDAP result code of
virtualListViewError and a virtualListViewResult of
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 Client implementers should note that this control is only defined on
a client interaction with a single server. If a server returns a client interaction with a single server. If a search scope spans
referrals as a part of its response to the search request, the client multiple naming contexts that are not held locally, search result
is responsible for deciding when and how to apply this control to the references will be returned, and may occur at any point in the search
referred-to servers, and how to collate the results from multiple operation. The client is responsible for deciding when and how to
servers. apply this control to the referred-to servers, and how to collate the
results from multiple servers.
9. Relationship to "Simple Paged Results" 9. Relationship to "Simple Paged Results"
@ -494,7 +564,13 @@ Expires: Nov 2002 May 2002
Server implementers may wish to consider whether clients are able to Server implementers may wish to consider whether clients are able to
consume excessive server resources in requesting virtual list consume excessive server resources in requesting virtual list
operations. Access control to the feature itself; configuration operations. Access control to the feature itself; configuration
options limiting the featureÆs use to certain predetermined search
Boreham et al Internet-Draft 10
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
options limiting the feature's use to certain predetermined search
base DNs and filters; throttling mechanisms designed to limit the base DNs and filters; throttling mechanisms designed to limit the
ability for one client to soak up server resources, may be ability for one client to soak up server resources, may be
appropriate. appropriate.
@ -503,43 +579,68 @@ Expires: Nov 2002 May 2002
retrieve the complete contents, or a significant subset of the retrieve the complete contents, or a significant subset of the
complete contents of the directory using this feature. This may be complete contents of the directory using this feature. This may be
undesirable in some circumstances and consequently it may be undesirable in some circumstances and consequently it may be
necessary to enforce some access control. necessary to enforce some access control or administrative limit.
Clients can, using this control, determine how many entries match a
particular filter, before the entries are returned to the client.
This may require special processing in servers which perform access
control checks on entries to determine whether the existence of the
entry can be disclosed to the client.
Server implementers should exercise caution concerning the content of
Boreham et al Internet-Draft 9
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
Clients can, using this control, determine how many entries are
contained 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 the contextID. Should the contextID contain internal server state, it
may be possible for a malicious client to use that information to may be possible for a malicious client to use that information to
gain unauthorized access to information. gain unauthorized access to information.
11. IANA Considerations
11. Acknowledgements 11.1 Request for LDAP Result Code
In accordance with section 3.6 of [LDAPIANA], it is requested that
IANA register the LDAP result code virtualListViewError (76) upon
Standards Action by the IESG. The value 76 has been suggested by
experts, had expert review, and is currently being used by some
implementations. If 76 is unavailable on not chosen, the value in the
paragraphs in Section 6.2.1 will need to be updated. The following
registration template is suggested:
Subject: LDAP Result Code Registration
Person & email address to contact for further information: Jim
Sermersheim
Result Code Name: virtualListViewError
Specification: RFCXXXX
Author/Change Controller: IESG
Comments: request LDAP result codes be assigned
12. Acknowledgements
Chris Weider, Anoop Anantha, and Michael Armijo of Microsoft co- Chris Weider, Anoop Anantha, and Michael Armijo of Microsoft co-
authored previous versions of this document. authored previous versions of this document.
12. References
[LDAPv3] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Boreham et al Internet-Draft 11
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
13. Normative References
[X.680] ITU-T Rec. X.680, "Abstract Syntax Notation One (ASN.1) -
Specification of Basic Notation", 1994.
[X.690] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules:
Basic, Canonical, and Distinguished Encoding Rules",
1994.
[LDAPPROT] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory
Access Protocol (v3)", Internet Standard, RFC 2251, Access Protocol (v3)", Internet Standard, RFC 2251,
December, 1997. December, 1997.
[SPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP
Control Extension for Simple Paged Results Manipulation",
RFC2696, September 1999.
[SSS] Wahl, M., Herron, A. and T. Howes, "LDAP Control [SSS] Wahl, M., Herron, A. and T. Howes, "LDAP Control
Extension for Server Side Sorting of Search Results", Extension for Server Side Sorting of Search Results",
RFC 2891, August, 2000. RFC 2891, August, 2000.
@ -547,30 +648,18 @@ Expires: Nov 2002 May 2002
[Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[LDAPIANA] Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
Considerations for the Lightweight Directory Access
Protocol (LDAP)", RFC 3383, September 2002.
14. Informative References
[SPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP
Control Extension for Simple Paged Results Manipulation",
RFC2696, September 1999.
15. Authors' Addresses
Boreham et al Internet-Draft 10
LDAP Extensions for Scrolling View May 2002
Browsing of Search Results
13. Authors' Addresses
David Boreham David Boreham
Bozeman Pass, Inc Bozeman Pass, Inc
@ -578,7 +667,7 @@ Expires: Nov 2002 May 2002
david@bozemanpass.com david@bozemanpass.com
Jim Sermersheim Jim Sermersheim
Novell, Inc Novell
1800 South Novell Place 1800 South Novell Place
Provo, Utah 84606, USA Provo, Utah 84606, USA
jimse@novell.com jimse@novell.com
@ -590,8 +679,14 @@ Expires: Nov 2002 May 2002
+1 425 882-8080 +1 425 882-8080
asafk@microsoft.com asafk@microsoft.com
Boreham et al Internet-Draft 12
LDAP Extensions for Scrolling View Nov 2002
Browsing of Search Results
14. Full Copyright Statement
16. Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved. Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to This document and translations of it may be copied and furnished to
@ -622,4 +717,23 @@ Expires: Nov 2002 May 2002
Boreham et al Internet-Draft 11
Boreham et al Internet-Draft 13