From a9d4a03638974a0951581c4c890fea51a0528139 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Wed, 3 Jan 2001 22:17:14 +0000 Subject: [PATCH] Not needed in re20 --- .../draft-ietf-ldapext-ldapv3-vlv-xx.txt | 655 ------------------ .../draft-smith-ldap-c-api-ext-vlv-xx.txt | 468 ------------- 2 files changed, 1123 deletions(-) delete mode 100644 doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt delete mode 100644 doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt diff --git a/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt b/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt deleted file mode 100644 index e7bb99ef8a..0000000000 --- a/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt +++ /dev/null @@ -1,655 +0,0 @@ - -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] - - diff --git a/doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt b/doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt deleted file mode 100644 index 6b4f28b6b5..0000000000 --- a/doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt +++ /dev/null @@ -1,468 +0,0 @@ -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 - - -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 . Please send -editorial comments directly to the author . - -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, - , 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, , July 1997. - -[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP - Extensions for Scrolling View Browsing of Search Results", - INTERNET-DRAFT , 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]