+++ /dev/null
-
-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
-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
- +1 650 937-5206
- dboreham@netscape.com
-
- Jim Sermersheim
- Novell
- 122 East 1700 South
- Provo, Utah 84606, USA
- jimse@novell.com
-
- Anoop Anantha
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052, USA
- +1 425 882-8080
- anoopa@microsoft.com
-
- Michael Armijo
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052, USA
- +1 425 882-8080
- micharm@microsoft.com
- This document expires on 5 October 2000
-
-
-
-Boreham et al [Page 10]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Boreham et al [Page 11]
-
-
+++ /dev/null
-Network Working Group M. Smith
-INTERNET-DRAFT Netscape Communications Corp.
-Intended Category: Standards Track
-Expires: 18 April 2000
-
- 18 October 1999
-
- LDAP C API Virtual List View Extension
- <draft-smith-ldap-c-api-ext-vlv-00.txt>
-
-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.
-
-This draft document will be submitted to the RFC Editor as a Standards
-Track document. Distribution of this memo is unlimited. Technical dis-
-cussion of this document will take place on the IETF LDAP Extension
-Working Group mailing list <ietf-ldapext@netscape.com>. Please send
-editorial comments directly to the author <mcs@netscape.com>.
-
-Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
-
-Please see the Copyright section near the end of this document for more
-information.
-
-Expires: 18 April 2000 [Page 1]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-2. Introduction
-
-This document defines a virtual list view extension for the LDAP C API
-to support the LDAP protocol extensions for scrolling view browsing of
-search results. More specifically, this document defines functions to
-create virtual list view request controls and to parse virtual list view
-response controls.
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
-to be interpreted as described in RFC 2119 [KEYWORDS].
-
-3. Table of Contents
-
-1. Status of this Memo............................................1
-2. Introduction...................................................2
-3. Table of Contents..............................................2
-4. Background and Intended Usage..................................2
-5. Advertising the Virtual List View C LDAP API Extension.........3
-6. Creating a Virtual List View Request Control...................3
-7. Parsing a Virtual List View Response Control...................6
-8. Example Code...................................................8
-9. Security Considerations........................................8
-10. Copyright......................................................8
-11. Bibliography...................................................9
-12. Author's Address...............................................9
-13. Appendix A - Summary of Additions to the C LDAP API............9
-
-4. Background and Intended Usage
-
-The LDAP C API [CAPI] defines a C language application programming
-interface (API) to the Lightweight Directory Access Protocol [LDAP].
-This document defines an extension to that API to support an optional
-LDAP protocol extension for scrolling view browsing of search results,
-also known as Virtual List View [VLV].
-
-The scrolling view browsing LDAP extension itself is designed to allow a
-"virtual list box" feature to be supported efficiently by LDAP servers
-and clients. The protocol extension consists of two LDAP controls: a
-Virtual List View (VLV) Request control which is sent by a client to a
-server along with an LDAP search request and a Virtual List View
-Response control which is returned by the server to send back status
-information about the VLV request.
-
-LDAP clients that wish to use the "virtual list box" feature SHOULD
-first check the supportedControls attribute in a server's rootDSE to
-
-Expires: 18 April 2000 [Page 2]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-determine if a value identical to the Virtual List View Request
-control's OID is present. If the OID is present and the client chooses
-to use the VLV feature, it MUST construct a Virtual List View Request
-control and a Server Side Sorting Control [SSS] and send both controls
-to the server within an LDAP searchRequest message. Both controls
-SHOULD be marked critical. Client applications MAY use the
-ldap_create_vlv_control() function described in this document to create
-a Virtual List View Request control.
-
-At the end of the search request processing, the server SHOULD return a
-Virtual List View Response control in the LDAP searchResultDone message.
-A Virtual List View Response control MAY be parsed to extract its con-
-tents by using the ldap_parse_vlv_control() function described in this
-document.
-
-5. Advertising the Virtual List View C LDAP API Extension
-
-To conform with the requirements defined in the C LDAP API specification
-[CAPI], implementations that support this extension SHOULD advertise the
-existence of this extension as follows:
-
- Define the macro LDAP_API_FEATURE_VIRTUAL_LIST_VIEW as a value that
- corresponds to the "level" or revision of this specification. When
- this document is published as an RFC, the value to use for
- LDAP_API_FEATURE_VIRTUAL_LIST_VIEW is the RFC number itself. While
- this document is an Internet Draft, the value to use is 1000 plus the
- revision number of this draft, i.e., 1000 for the -00 revision of
- this draft, 1001 for the -01 version, and so on.
-
- Return the text string VIRTUAL_LIST_VIEW in the ldapai_extensions
- array of the LDAPAPIInfo structure following a successful call to
- ldap_get_option() with an option parameter value of
- LDAP_OPT_API_INFO.
-
- Return information about the extension when the ldapaif_name field in
- the LDAPAPIFeatureInfo structure is set to the text string
- VIRTUAL_LIST_VIEW and a call to ldap_get_option() with an option
- parameter value of LDAP_OPT_API_FEATURE_INFO is made.
-
-6. Creating a Virtual List View Request Control
-
-The LDAPVLVInfo structure describes a Virtual List View Request control
-and is passed to the ldap_create_vlv_control() function to create a Vir-
-tualListViewRequest control. The resulting control SHOULD be passed to
-
-Expires: 18 April 2000 [Page 3]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-the ldap_search_ext() or ldap_search_ext_s() functions described in
-[CAPI] to send them to the server. The ldap_create_sort_control() func-
-tion described in [SSSAPI] MAY be used to create a Sort control that is
-be passed to the server along with the VirtualListViewRequest control.
-
-The LDAPVLVInfo structure MAY also be used by applications to manage the
-state information associated with a series of virtual list view
-client/server interactions.
-
- /* LDAPVLVInfo structure: */
- typedef struct ldapvlvinfo {
- int ldvlv_version; /* version of this struct (1) */
- unsigned long ldvlv_before_count;
- unsigned long ldvlv_after_count;
- unsigned long ldvlv_offset; /* used if ldvlv_attrvalue is NULL
-*/
- unsigned long ldvlv_count; /* used if ldvlv_attrvalue is NULL
-*
- struct berval *ldvlv_attrvalue;
- struct berval *ldvlv_context;
- void *ldvlv_extradata; /* for use by application */
- } LDAPVLVInfo;
-
- /* value for the ldvlv_version field of the LDAPVLVInfo structure: */
- #define LDAP_VLVINFO_VERSION 1
-
- /* function used to create a VirtualListViewRequest control: */
- int ldap_create_vlv_control(
- LDAP *ld,
- LDAPVLVInfo *vlvinfop,
- LDAPControl **ctrlp
- );
-
- /* OID of the VirtualListViewRequest control: */
- #define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
-
-The parameters to the ldap_create_vlv_control() function are:
-
-ld An LDAP session handle, as obtained from a call to
- ldap_init().
-
-vlvinfop The address of an LDAPVLVInfo structure whose con-
- tents are used to construct the value of the control
- that is created.
-
-ctrlp A result parameter that will be assigned the address
- of an LDAPControl structure that contains the Virtu-
- alListViewRequest control created by this function.
- The memory occupied by the LDAPControl structure
- SHOULD be freed when it is no longer in use by
-
-Expires: 18 April 2000 [Page 4]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
- calling ldap_control_free().
-
-The ldap_create_vlv_control() function returns a C LDAP API error code
-to indicate success or failure (LDAP_SUCCESS if all goes well).
-
-The members of the LDAPVLVInfo structure are:
-
-ldvlv_version A number that identifies the version of the
- LDAPVLVInfo structure. This SHOULD always be set to
- the value LDAP_VLVINFO_VERSION (1).
-
-ldvlv_before_count A count of the number of entries before the target
- entry the client wants the server to send back.
- This field corresponds to the beforeCount element of
- the BER-encoded VirtualListViewRequest control value
- itself.
-
-ldvlv_after_count A count of the number of entries after the target
- entry the client wants the server to send back.
- This field corresponds to the afterCount element of
- the BER-encoded VirtualListViewRequest control value
- itself.
-
-ldvlv_offset This field is only used if ldvlv_attrvalue is NULL,
- i.e, if the byoffset choice within the VirtualList-
- ViewRequest control is to be used. ldvlv_offset is
- used along with the ldvlv_count value by the server
- to determine the target entry. This field
- corresponds to the offset element within the BER-
- encoded VirtualListViewRequest control value itself.
-
-ldvlv_count This field is only used if ldvlv_attrvalue is NULL,
- i.e., if the byIndex choice within the VirtualList-
- ViewRequest control is to be used. ldvlv_count is
- used along with the ldvlv_offset value by the server
- to determine the target entry. This field
- corresponds to the contentCount element within the
- BER-encoded VirtualListViewRequest control value
- itself.
-
-ldvlv_attrvalue If this is not NULL, it indicates that the
- greaterThanOrEqual choice within the VirtualList-
- ViewRequest is to be used. ldvlv_attrvalue
- corresponds to the assertionValue element of the
- BER-encoded VirtualListViewRequest control value
- itself. This value is compared by the server with
- the values of the attribute specified by the primary
- sort key to determine the target entry.
-
-Expires: 18 April 2000 [Page 5]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-ldvlv_context If this is not NULL, it is included as the context
- identifier in the VirtualListViewRequest control;
- ldvlv_context corresponds to the contextID element
- within the BER-encoded VirtualListViewRequest con-
- trol value itself. If ldvlv_context is NULL, no
- context identifier is included in the VirtualList-
- ViewRequest control.
-
-ldvlv_extradata This field is reserved for application-specific use
- and is not used by the ldap_create_vlv_control()
- function; it has no effect on the control that is
- created.
-
-7. Parsing a Virtual List View Response Control
-
-When an application receives the result from a VLV search, it SHOULD use
-the ldap_parse_vlv_control() function to look for and parse the Virtual
-List View Response control returned by the server.
-
- /* function used to look for and parse a VirtualListViewResponse
-control: */
- int ldap_parse_vlv_control(
- LDAP *ld,
- LDAPControl **ctrls,
- unsigned long *target_posp,
- unsigned long *list_countp,
- struct berval **contextp,
- int *errcodep
- );
-
- /* OID of the VirtualListViewResponse control: */
- #define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
-
- /* new error codes: */
- #define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */
- #define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */
-
-The parameters to the ldap_parse_vlv_control() function are:
-
-ld An LDAP session handle.
-
-ctrls The address of a NULL-terminated array of LDAPCon-
- trol structures, typically obtained by a call to
- ldap_parse_result().
-
-target_posp This result parameter is filled in with the list
- index of the target entry. If this parameter is
- NULL, the target position is not returned. The
-
-Expires: 18 April 2000 [Page 6]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
- value for this result parameter is pulled from the
- targetPosition element of the BER-encoded Virtual-
- ListViewResponse control value itself.
-
-list_countp This result parameter is filled in with the server's
- estimate of the size of the list. If this parameter
- is NULL, the size is not returned. The value for
- this result parameter is pulled from the con-
- tentCount element of the BER-encoded VirtualList-
- ViewResponse control value itself.
-
-contextp This result parameter is filled in with the address
- of a struct berval that contains the server-
- generated context identifier if one was returned by
- the server. If the server did not return a context
- identifier, this parameter will be set to NULL. The
- struct berval returned SHOULD be disposed of by cal-
- ling ber_bvfree() when it is no longer needed. If
- NULL is passed for contextp, the context identifier
- is not returned.
-
-errcodep This result parameter is filled in with the VLV
- result code. If this parameter is NULL, the result
- code is not returned. The value for this result
- parameter is pulled from the virtualListViewResult
- element of the BER-encoded VirtualListViewResponse
- control value itself. As specified in the VLV pro-
- tocol extension [VLV], it will have one of the fol-
- lowing values:
-
- LDAP_SUCCESS (0); defined in [CAPI]
- LDAP_OPERATIONS_ERROR (1); defined in [CAPI]
- LDAP_UNWILLING_TO_PERFORM (53); defined in [CAPI]
- LDAP_INSUFFICIENT_ACCESS (50); defined in [CAPI]
- LDAP_BUSY (51); defined in [CAPI]
- LDAP_TIMELIMIT_EXCEEDED (3); defined in [CAPI]
- LDAP_ADMINLIMIT_EXCEEDED (11); defined in [CAPI]
- LDAP_SORT_CONTROL_MISSING (60); defined above
- LDAP_INDEX_RANGE_ERROR (61); defined above
- LDAP_OTHER (80); defined in [CAPI]
-
-The ldap_parse_vlv_control() function returns an LDAP error code that
-indicates whether a VLV Result control was found and whether the parsing
-was successful. LDAP_SUCCESS is returned if all goes well,
-LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does not include a
-VirtualListViewResponse control, and another LDAP error code that is
-defined in [CAPI] is returned if a parsing error or other problem
-occurs.
-
-Expires: 18 April 2000 [Page 7]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-8. Example Code
-
-To be provided.
-
-9. Security Considerations
-
-Most servers will be configured to restrict access to the Virtual List
-View feature since poorly-behaved or malicious clients may cause many
-resources to be consumed on the server, or allow users to retrieve too
-many entries, or allow users to get an accurate count of the number of
-entries present in a portion of the DIT. Clients should take care to
-not abuse the VLV feature and should be prepared for servers to refuse
-to service a particular VLV request due to access control or other
-site-defined policies.
-
-Please see the protocol extension document [VLV] for a discussion of
-related security considerations.
-
-10. Copyright
-
-Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
-
-This document and translations of it may be copied and furnished to oth-
-ers, and derivative works that comment on or otherwise explain it or
-assist in its implementation may be prepared, copied, published and dis-
-tributed, in whole or in part, without restriction of any kind, provided
-that the above copyright notice and this paragraph are included on all
-such copies and derivative works. However, this document itself may not
-be modified in any way, such as by removing the copyright notice or
-references to the Internet Society or other Internet organizations,
-except as needed for the purpose of developing Internet standards in
-which case the procedures for copyrights defined in the Internet Stan-
-dards process must be followed, or as required to translate it into
-languages other than English.
-
-The limited permissions granted above are perpetual and will not be
-revoked by the Internet Society or its successors or assigns.
-
-This document and the information contained herein is provided on an "AS
-IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
-FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
-LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
-INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
-NESS FOR A PARTICULAR PURPOSE.
-
-Expires: 18 April 2000 [Page 8]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-11. Bibliography
-
-[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C
- LDAP Application Program Interface", INTERNET-DRAFT,
- <draft-ietf-ldapext-ldap-c-api-04.txt>, 8 October 1999.
-
-[KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
- ment Levels", RFC 2119, March 1997.
-
-[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
- Protocol (v3)", RFC 2251, December 1997.
-
-[SSS] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control
- Extension for Server Side Sorting of Search Results",
- INTERNET-DRAFT, April 1999.
-
-[SSSAPI] C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API
- Extensions for Sort and Simple Paged Results", INTERNET-
- DRAFT, <draft-ietf-asid-ldapv3-api-ext-00.txt>, July 1997.
-
-[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP
- Extensions for Scrolling View Browsing of Search Results",
- INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-vlv-03.txt>, 11
- June 1999.
-
-12. Author's Address
-
- Mark Smith
- Netscape Communications Corp.
- 501 E. Middlefield Rd., Mailstop MV068
- Mountain View, CA 94043
- USA
- +1 650 937-3477
- mcs@netscape.com
-
-13. Appendix A - Summary of Additions to the C LDAP API
-
-This extension introduces the following macros:
-
- LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
- LDAP_VLVINFO_VERSION
- LDAP_CONTROL_VLVREQUEST
- LDAP_CONTROL_VLVRESPONSE
- LDAP_SORT_CONTROL_MISSING
- LDAP_INDEX_RANGE_ERROR
-
-Expires: 18 April 2000 [Page 9]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-This extension introduces the following structures and typedefs:
-
- ldapvlvinfo
- LDAPVLVInfo
-
-This extension introduces the following functions:
-
- ldap_create_vlv_control()
- ldap_parse_vlv_control()
-
-Expires: 18 April 2000 [Page 10]
projects / thirdparty / openldap.git / commitdiff
