One document matched: draft-ietf-asid-ldapv3-api-ext-00.txt

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
	<draft-ietf-asid-ldapv3-api-ext-00.txt>

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