HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 00:52:10 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Tue, 17 Mar 1998 16:31:00 GMT ETag: "2e7a0c-22bd-350ea544" Accept-Ranges: bytes Content-Length: 8893 Connection: close Content-Type: text/plain Network Working Group C. Weider INTERNET-DRAFT Microsoft Corp. Intended Category: Standards Track A. Herron Expires: January 1998 Microsoft Corp. T. Howes Netscape Communications Corp. M. Smith Netscape Communications Corp. M. Wahl Critical Angle, Inc. 29 July 1997 LDAP API Extensions for Sort and Simple Paged Results 1. Status of this Memo This draft document will be submitted to the RFC Editor as an informational document. Distribution of this memo is unlimited. Please send comments to the authors. This document is an Internet-Draft. Internet-Drafts are working documents 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.'' To learn the current status of any Internet-Draft, please check the ''1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 2. Introduction This document defines extensions to the LDAP v3 C language API defined in [1]. These extensions cover the sort extended control, defined in [2], and the simple paged results control, defined in [3]. N.B.: while the sort extended control can be used on its own, the simple paged results control is most useful when used on results that have already been sorted. 3. Common Data Structures This paper assumes the common data structures defined in [1]. 4. Simple Paged Results 4.1 Overview of Simple Paged Results usage When an LDAP client is accessing a server across a slow link, or if the client suspects that the result set from a given query may be very large, the client should be able to retrieve a result set in small pieces. The Simple Paged Result extended control allows this type of retrieval by allowing a one-way walk-through of a result set. Options on this control allow the client to set the initial page size and reset the page size with each subsequent request to the server. The interaction between client and server is as follows: The client sends the server a search request with the Simple Paged Resultscontrol with an empty previousEnumerationKey (also known as a 'cookie') and the initial page size. The server then returns the number of entries specified by the page size and also returns a cookie that is used on the next client request to get the next page of results. The client then issues a search with the cookie included (optionally resetting the page size) and the server then responds with up to that number of entries. Details of the protocol operations of Simple Paged Results can be found in [3]. 4.2 API extensions for Simple Paged Results Paged results are indicated as a control on the ldap_search_ext function call. To construct this control, the API provides ldap_create_page_control. This control structure must then be added to the list of server controls in the ldap_search_ext call. When the server returns the first page of results, it includes the resume cookie in the controls field of the searchResultDone message. The client must then extract the cookie from the search result by retrieving the server controls by using ldap_parse_result and parsing the control with ldap_parse_page_control. The client then uses the cookie in the next call to LDAP_create_page_control to retrieve the next page of results. int ldap_create_page_control( LDAP * connection, unsigned long pagesize, struct berval * cookie, char isCritical, LDAPControl ** output ); int ldap_parse_page_control( LDAP * connection, LDAPControl ** controls, unsigned long * totalcount, struct berval **cookie ); Parameters are: connection the connection block for the connection you wish to control pagesize The number of entries to return in each page. cookie An opaque cookie, used by the server to determine its location in the result set. This will be NULL for the first call to ldap_create_page_control. output The address of a place to put the constructed control controls An array of controls (obtained by calling ldap_parse_result() on the set of results returned by the server) that includes a page control. The page control contains the cookie and total count fields returned by the server. totalcount A pointer to the total count of entries returned in this page. 5. Sort Results 5.1 Overview of sort results usage When an LDAP client needs search results sorted and is not able or is unwilling to perform the sort itself, the client can request that the server do it. The Sort control allows the client to give the server the information required to sort the result set. The interaction between client and server is as follows: The client sends the server a search request with the Sort control which specifies the sort keys. Each sort key consists of an AttributeType, an orderingRule, and a flag that indicates whether entries are sorted in forward or reverse order. The server then tells the client whether or not the sort was successful and returns entries. Details of the protocol operations for Sort can be found in [2]. 5.2 API extensions for Sort Sort is indicated as a control on the ldap_search_ext function call. To construct this control, the API provides ldap_create_sort_control. The control must then be added to the list of server controls in the ldap_search_ext call. When the server returns the results, it returns a control in the searchResultDone message to reflect the success or failure of the search. The API provides ldap_parse_search_control as a method of parsing the sort control as returned by the server in the searchResultDone message. The functions are as follows: int ldap_create_sort_control( LDAP * connection, LDAPsortkey ** sortKeyList, char isCritical, LDAPControl ** output ); int ldap_parse_sort_control( LDAP * connection, LDAPControl ** controls, ulong * result, char ** attributes ) typedef struct LDAPsortkey { char * sk_attrtype; char * sk_matchruleoid; boolean sk_reverseorder; } LDAPsortkey; Parameters are connection LDAP pointer to the desired connection sortKeyList an array of sortkeys output the address of a place to put the constructed control controls An array of controls obtained from calling ldap_parse_result on the set of results returned by the server result the address of a place to put the result code attributes the address of a place to put the name of the attribute which cause the operation to fail, optionally returned by the server 6. New error codes When a control is not found by ldap_parse_page_control() or ldap_parse_sort_control(), those functions MUST return a new error code, LDAP_CONTROL_NOT_FOUND. This error code MUST have hex value 0x5D. 7. Using sort and paged results together The Paged Results draft [3] explicitly states that the search command used to get subsequent pages of the result set must have everything the same with the exception of the cookie on the control and with the possible exception of the page size. Therefore when sort and paged results are used together, the sort control must be set to the same value for every retrieval of a page of a given result set. 8. References [1] Howes, et al, the LDAP Application Program Interface, Internet Draft, July 1997. Available as draft-ietf-asid-ldapv3-api-00.txt from any Internet Draft server. [2] Herron, Howes, and Wahl, LDAP Control Extension for Server Side Sorting of Search Results, Internet Draft, April, 1997. Available as draft-ietf-asid-ldapv3-sorting-00.txt from any Internet Draft server. [3] Weider, Herron, and Howes, LDAP Control Extension for Simple Paged Results Manipulation, Internet Draft, March 1997. Available as draft-ietf-asid-ldapv3-simplepaged-01.txt from any Internet Draft server. 9. Author's addresses Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA +1 425 882-8080 cweider@microsoft.com Andy Herron Microsoft Corp 1 Microsoft Way Redmond, WA 98052 USA +1 425-882-8080 andyhe@microsoft.com Tim Howes Netscape Communications Corp. 501 E. Middlefield Rd., Mailstop MV068 Mountain View, CA 94043 USA +1 415 937-3419 howes@netscape.com Mark Smith Netscape Communications Corp. 501 E. Middlefield Rd., Mailstop MV068 Mountain View, CA 94043 USA +1 313 937-3477 mcs@netscape.com Mark Wahl Critical Angle Inc. 4815 W Braker Lane #502-385 Austin, TX 78759 USA M.Wahl@critical-angle.com