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