idnits 2.17.1 draft-ietf-asid-ldapv3-api-ext-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 272 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 67 instances of lines with control characters in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 204: '... those functions MUST return a new err...' RFC 2119 keyword, line 205: '...D. This error code MUST have hex value...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 88 has weird spacing: '... result by re...' == Unrecognized Status in 'Intended Category: Standards Track A. Herron', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (29 July 1997) is 9767 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- No information found for draft-ietf-asid-ldapv3-api - is the name correct? -- Possible downref: Normative reference to a draft: ref. '1' -- Possible downref: Normative reference to a draft: ref. '2' == Outdated reference: A later version (-03) exists of draft-ietf-asid-ldapv3-simplepaged-01 ** Downref: Normative reference to an Informational draft: draft-ietf-asid-ldapv3-simplepaged (ref. '3') Summary: 13 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group C. Weider 2 INTERNET-DRAFT Microsoft Corp. 3 Intended Category: Standards Track A. Herron 4 Expires: January 1998 Microsoft Corp. 5 T. Howes 6 Netscape Communications Corp. 7 M. Smith 8 Netscape Communications Corp. 9 M. Wahl 10 Critical Angle, Inc. 12 29 July 1997 14 LDAP API Extensions for Sort and Simple Paged Results 15 17 1. Status of this Memo 19 This draft document will be submitted to the RFC Editor as an 20 informational document. Distribution of this memo is unlimited. Please 21 send comments to the authors. 23 This document is an Internet-Draft. Internet-Drafts are working 24 documents of the Internet Engineering Task Force (IETF), its areas, and 25 its working groups. Note that other groups may also distribute working 26 documents as Internet-Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference material 31 or to cite them other than as ''work in progress.'' 33 To learn the current status of any Internet-Draft, please check the 34 ''1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 35 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 36 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 38 2. Introduction 40 This document defines extensions to the LDAP v3 C language API defined 41 in [1]. These extensions cover the sort extended control, defined in 42 [2], 43 and the simple paged results control, defined in [3]. N.B.: while the 44 sort extended control can be used on its own, the simple paged results 45 control is most useful when used on results that have already been 46 sorted. 48 3. Common Data Structures 50 This paper assumes the common data structures defined in [1]. 52 4. Simple Paged Results 54 4.1 Overview of Simple Paged Results usage 56 When an LDAP client is accessing a server across a slow link, or if the 57 client suspects that the result set from a given query may be very 58 large, 59 the client should be able to retrieve a result set in small pieces. The 60 Simple Paged Result extended control allows this type of retrieval by 61 allowing a one-way walk-through of a result set. Options on this control 63 allow the client to set the initial page size and reset the page size 64 with each subsequent request to the server. 66 The interaction between client and server is as follows: 68 The client sends the server a search request with the Simple Paged 69 Resultscontrol with an empty previousEnumerationKey (also known as a 70 'cookie') and the initial page size. The server then returns the number 71 of entries specified by the page size and also returns a cookie that is 72 used on the next client request to get the next page of results. The 73 client then issues a search with the cookie included (optionally 74 resetting the page size) and the server then responds with up to that 75 number of entries. 77 Details of the protocol operations of Simple Paged Results can be found 78 in [3]. 80 4.2 API extensions for Simple Paged Results 82 Paged results are indicated as a control on the ldap_search_ext function 83 call. To construct this control, the API provides 84 ldap_create_page_control. This control structure must then be added to 85 the list of server controls in the ldap_search_ext call. When the server 86 returns the first page of results, it includes the resume cookie in the 87 controls field of the searchResultDone message. The client must then 88 extract the cookie from the search result by retrieving the server 89 controls by using ldap_parse_result and parsing the control with 90 ldap_parse_page_control. The client then uses the cookie in the next 91 call to LDAP_create_page_control to retrieve the next page of results. 93 int ldap_create_page_control( 94 LDAP * connection, 95 unsigned long pagesize, 96 struct berval * cookie, 97 char isCritical, 98 LDAPControl ** output 99 ); 101 int ldap_parse_page_control( 102 LDAP * connection, 103 LDAPControl ** controls, 104 unsigned long * totalcount, 105 struct berval **cookie 106 ); 108 Parameters are: 110 connection the connection block for the connection you wish to 111 control 113 pagesize The number of entries to return in each page. 115 cookie An opaque cookie, used by the server to determine its 116 location in the result set. This will be NULL for the 117 first call to ldap_create_page_control. 119 output The address of a place to put the constructed control 121 controls An array of controls (obtained by calling 122 ldap_parse_result() on the set of results returned by 123 the server) that includes a page control. The page 124 control contains the cookie and total count fields 125 returned by the server. 127 totalcount A pointer to the total count of entries returned in 128 this page. 130 5. Sort Results 132 5.1 Overview of sort results usage 134 When an LDAP client needs search results sorted and is not able or is 135 unwilling to perform the sort itself, the client can request that the 136 server do it. The Sort control allows the client to give the server 137 the information required to sort the result set. 139 The interaction between client and server is as follows: 141 The client sends the server a search request with the Sort control 142 which specifies the sort keys. Each sort key consists of an 143 AttributeType, an orderingRule, and a flag that indicates whether 144 entries are sorted in forward or reverse order. The server then tells 145 the client whether or not the sort was successful and returns 146 entries. 148 Details of the protocol operations for Sort can be found in [2]. 150 5.2 API extensions for Sort 152 Sort is indicated as a control on the ldap_search_ext function call. 153 To construct this control, the API provides ldap_create_sort_control. 154 The control must then be added to the list of server controls in the 155 ldap_search_ext call. When the server returns the results, it returns 156 a control in the searchResultDone message to reflect the success or 157 failure of the search. The API provides ldap_parse_search_control as a 158 method of parsing the sort control as returned by the server in the 159 searchResultDone message. 161 The functions are as follows: 163 int ldap_create_sort_control( 164 LDAP * connection, 165 LDAPsortkey ** sortKeyList, 166 char isCritical, 167 LDAPControl ** output 168 ); 170 int ldap_parse_sort_control( 171 LDAP * connection, 172 LDAPControl ** controls, 173 ulong * result, 174 char ** attributes 175 ) 177 typedef struct LDAPsortkey { 178 char * sk_attrtype; 179 char * sk_matchruleoid; 180 boolean sk_reverseorder; 181 } LDAPsortkey; 183 Parameters are 185 connection LDAP pointer to the desired connection 187 sortKeyList an array of sortkeys 189 output the address of a place to put the constructed control 191 controls An array of controls obtained from calling 192 ldap_parse_result on the set of results returned by 193 the server 195 result the address of a place to put the result code 197 attributes the address of a place to put the name of the 198 attribute which cause the operation to fail, optionally 199 returned by the server 201 6. New error codes 203 When a control is not found by ldap_parse_page_control() or 204 ldap_parse_sort_control(), those functions MUST return a new error 205 code, LDAP_CONTROL_NOT_FOUND. This error code MUST have hex value 206 0x5D. 208 7. Using sort and paged results together 210 The Paged Results draft [3] explicitly states that the search command 211 used to get subsequent pages of the result set must have everything the 212 same with the exception of the cookie on the control and with the 213 possible exception of the page size. Therefore when sort and paged 214 results are used together, the sort control must be set to the same 215 value for every retrieval of a page of a given result set. 217 8. References 219 [1] Howes, et al, the LDAP Application Program Interface, Internet 220 Draft, July 1997. Available as 221 draft-ietf-asid-ldapv3-api-00.txt from any Internet Draft server. 223 [2] Herron, Howes, and Wahl, LDAP Control Extension for Server Side 224 Sorting of Search Results, Internet Draft, April, 1997. Available as 225 draft-ietf-asid-ldapv3-sorting-00.txt from any Internet Draft server. 227 [3] Weider, Herron, and Howes, LDAP Control Extension for Simple Paged 228 Results Manipulation, Internet Draft, March 1997. Available as 229 draft-ietf-asid-ldapv3-simplepaged-01.txt from any Internet Draft 230 server. 232 9. Author's addresses 234 Chris Weider 235 Microsoft Corp. 236 1 Microsoft Way 237 Redmond, WA 98052 238 USA 239 +1 425 882-8080 240 cweider@microsoft.com 242 Andy Herron 243 Microsoft Corp 244 1 Microsoft Way 245 Redmond, WA 98052 246 USA 247 +1 425-882-8080 248 andyhe@microsoft.com 250 Tim Howes 251 Netscape Communications Corp. 252 501 E. Middlefield Rd., Mailstop MV068 253 Mountain View, CA 94043 254 USA 255 +1 415 937-3419 256 howes@netscape.com 258 Mark Smith 259 Netscape Communications Corp. 260 501 E. Middlefield Rd., Mailstop MV068 261 Mountain View, CA 94043 262 USA 263 +1 313 937-3477 264 mcs@netscape.com 266 Mark Wahl 267 Critical Angle Inc. 4815 W Braker Lane #502-385 268 Austin, TX 78759 269 USA 270 M.Wahl@critical-angle.com