[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01                                                         
LDAPEXT Working Group                                           M. Smith
INTERNET-DRAFT                             Netscape Communications Corp.
Intended Category: Standards Track
Expires: 12 September 1998


                                                           12 March 1998


  LDAP C API Extensions for Scrolling View Browsing of Search Results
                 <draft-ietf-ldapext-c-api-vlv-01.txt>



1.  Status of this Memo

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 <ietf-ldapext@netscape.com>.  Please send
editorial comments directly to the author <mcs@netscape.com>.

This document is an Internet-Draft.  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.''

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).

Copyright (C) The Internet Society (1998). All Rights Reserved.

Please see the Copyright section near the end of this document for more
information.










Expires: 12 September 1998                                      [Page 1]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


2.  Abstract

This document defines extensions to the LDAP C API to support the LDAP
Extensions for Scrolling View Browsing of Search Results.  More specifi-
cally, 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.  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 extensions to that API to support an optional LDAP
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
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_virtuallist_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_virtuallist_control() function described
in this document.







Expires: 12 September 1998                                      [Page 2]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


4.  Creating a Virtual List View Request Control

The LDAPVirtualList structure describes a Virtual List View Request con-
trol and is passed to the ldap_create_virtuallist_control() function to
create a VLV Request control.  The resulting control SHOULD be passed to
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
MUST be passed to the server along with the VLV request.

The LDAPVirtualList structure MAY also be used by applications to manage
the state information associated with a series of virtual list view
client/server interactions.

       typedef struct ldapvirtuallist {
           unsigned long   ldvlist_before_count;
           unsigned long   ldvlist_after_count;
           char            *ldvlist_attrvalue;
           unsigned long   ldvlist_index;
           unsigned long   ldvlist_size;
           void            *ldvlist_extradata;
       } LDAPVirtualList;

       int ldap_create_virtuallist_control(
           LDAP            *ld,
           LDAPVirtualList *ldvlistp,
           LDAPControl     **ctrlp
       );

       #define LDAP_CONTROL_VLVREQUEST         "2.16.840.1.113730.3.4.9"

The parameters to the ldap_create_virtuallist_control() function are:

ld                   An LDAP session handle, as obtained from a call to
                     ldap_init().

ldvlistp             The address of an LDAPVirtualList structure whose
                     contents 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 VLV Request control created by this function.
                     The memory occupied by the LDAPControl structure
                     should be freed when it is no longer in use by cal-
                     ling ldap_control_free().

The ldap_create_virtuallist_control() function returns an LDAP error



Expires: 12 September 1998                                      [Page 3]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


code to indicate success or failure (LDAP_SUCCESS if all goes well).

The members of the LDAPVirtualList structure are:

ldvlist_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.

ldvlist_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.

ldvlist_attrvalue    If this is not NULL, it indicates that the byValue
                     choice within the VirtualListViewRequest is to be
                     used, and 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.

ldvlist_index        This field is only used if ldvlist_attrvalue is
                     NULL, i.e, if the byIndex choice within the Virtu-
                     alListViewRequest control is to be used.
                     ldvlist_index is used along with the ldvlist_size
                     value by the server to determine the target entry.
                     This field corresponds to the index element within
                     the BER-encoded VirtualListViewRequest control
                     value itself.

ldvlist_size         This field is only used if ldvlist_attrvalue is
                     NULL, i.e., if the byIndex choice within the Virtu-
                     alListViewRequest control is to be used.
                     ldvlist_size is used along with the ldvlist_index
                     value by the server to determine the target entry.
                     This field corresponds to the contentCount element
                     within the BER-encoded VirtualListViewRequest con-
                     trol value itself.

ldvlist_extradata    This field is reserved for application-specific use
                     and is not used by the
                     ldap_create_virtuallist_control() function; it has
                     no effect on the control that is created.





Expires: 12 September 1998                                      [Page 4]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


5.  Parsing a Virtual List View Response Control

When an application receives the result from a VLV search, it SHOULD use
the ldap_parse_virtuallist_control() function to look for and parse the
Virtual List View Response control returned by the server.

       int ldap_parse_virtuallist_control(
           LDAP            *ld,
           LDAPControl     **ctrls,
           unsigned long   *target_posp,
           unsigned long   *list_sizep,
           int             *errcodep
       );

       #define LDAP_CONTROL_VLVRESPONSE        "2.16.840.1.113730.3.4.10"

       #define LDAP_SORT_CONTROL_MISSING       0x3C    /* 60 */
       #define LDAP_INDEX_RANGE_ERROR          0x3D    /* 61 */


The parameters to the ldap_parse_virtuallist_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
                     value for this result parameter is pulled from the
                     targetPosition element of the BER-encoded Virtual-
                     ListViewResponse control value itself.

list_sizep           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
                     contentCount element of the BER-encoded Virtual-
                     ListViewResponse control value itself.

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.  It SHOULD have one of the



Expires: 12 September 1998                                      [Page 5]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


                     following 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                  (50); defined in [CAPI]

The ldap_parse_virtuallist_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
VLV Response control, and another LDAP error code that is defined in
[CAPI] is returned if a parsing error or other problem occurs.


6.  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.


7.  Copyright

Copyright (C) The Internet Society (1998). All Rights Reserved.


others, 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,



Expires: 12 September 1998                                      [Page 6]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


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.



8.  Bibliography

[CAPI]      M. Smith, T. Howes, A. Herron, C. Weider, M. Wahl, A. Anan-
            tha, "The C LDAP Application Program Interface", INTERNET-
            DRAFT, <draft-ietf-ldapext-ldap-c-api-00.txt>, March 1998.

[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, C.Weider, A. Anantha, "LDAP
            Control Extension for Server Side Sorting of Search
            Results", INTERNET-DRAFT, March 1997.

[SSSAPI]    C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API
            Extensions for Sort and Simple Paged Results", INTERNET-
            DRAFT, <draft-ietf-asid-ldapv3-api-ext-00.txt>, July 1997.

[VLV]       David Boreham, "LDAP Extensions for Scrolling View Browsing
            of Search Results", INTERNET-DRAFT <draft-ietf-ldapext-
            ldapv3-vlv-02.txt>, March 1998.


9.  Author's Address

   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd., Mailstop MV068
   Mountain View, CA 94043



Expires: 12 September 1998                                      [Page 7]


INTERNET-DRAFT        LDAP C Virtual List View API         12 March 1998


   USA
   +1 650 937-3477
   mcs@netscape.com
















































Expires: 12 September 1998                                      [Page 8]

1.     Status of this Memo............................................1
2.     Abstract.......................................................2
3.     Background and Intended Usage..................................2
4.     Creating a Virtual List View Request Control...................3
5.     Parsing a Virtual List View Response Control...................5
6.     Security Considerations........................................6
7.     Copyright......................................................6
8.     Bibliography...................................................7
9.     Author's Address...............................................7