git.sur5r.net Git - openldap/blob - doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt

   1 Network Working Group                                           M. Smith
   2 INTERNET-DRAFT                             Netscape Communications Corp.
   3 Intended Category: Standards Track
   4 Expires: 18 April 2000
   5
   6                                                           18 October 1999
   7
   8                  LDAP C API Virtual List View Extension
   9                 <draft-smith-ldap-c-api-ext-vlv-00.txt>
  10
  11 1.  Status of this Memo
  12
  13 This document is an Internet-Draft and is in full conformance with all
  14 provisions of Section 10 of RFC2026.  Internet-Drafts are working docu-
  15 ments of the Internet Engineering Task Force (IETF), its areas, and its
  16 working groups.  Note that other groups may also distribute working
  17 documents as Internet-Drafts.
  18
  19 Internet-Drafts are draft documents valid for a maximum of six months
  20 and may be updated, replaced, or obsoleted by other documents at any
  21 time.  It is inappropriate to use Internet-Drafts as reference material
  22 or to cite them other than as "work in progress."
  23
  24 The list of current Internet-Drafts can be accessed at
  25 http://www.ietf.org/ietf/1id-abstracts.txt.
  26
  27 The list of Internet-Draft Shadow Directories can be accessed at
  28 http://www.ietf.org/shadow.html.
  29
  30 This draft document will be submitted to the RFC Editor as a Standards
  31 Track document. Distribution of this memo is unlimited.  Technical dis-
  32 cussion of this document will take place on the IETF LDAP Extension
  33 Working Group mailing list <ietf-ldapext@netscape.com>.  Please send
  34 editorial comments directly to the author <mcs@netscape.com>.
  35
  36 Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
  37
  38 Please see the Copyright section near the end of this document for more
  39 information.
  40
  41 Expires: 18 April 2000                                          [Page 1]
  42
  43 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
  44
  45 2.  Introduction
  46
  47 This document defines a virtual list view extension for the LDAP C API
  48 to support the LDAP protocol extensions for scrolling view browsing of
  49 search results.  More specifically, this document defines functions to
  50 create virtual list view request controls and to parse virtual list view
  51 response controls.
  52
  53 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  54 "SHOULD", "SHOULD NOT", "RECOMMENDED",  and "MAY" in this document are
  55 to be interpreted as described in RFC 2119 [KEYWORDS].
  56
  57 3.  Table of Contents
  58
  59 1.     Status of this Memo............................................1
  60 2.     Introduction...................................................2
  61 3.     Table of Contents..............................................2
  62 4.     Background and Intended Usage..................................2
  63 5.     Advertising the Virtual List View C LDAP API Extension.........3
  64 6.     Creating a Virtual List View Request Control...................3
  65 7.     Parsing a Virtual List View Response Control...................6
  66 8.     Example Code...................................................8
  67 9.     Security Considerations........................................8
  68 10.    Copyright......................................................8
  69 11.    Bibliography...................................................9
  70 12.    Author's Address...............................................9
  71 13.    Appendix A - Summary of Additions to the C LDAP API............9
  72
  73 4.  Background and Intended Usage
  74
  75 The LDAP C API [CAPI] defines a C language application programming
  76 interface (API) to the Lightweight Directory Access Protocol [LDAP].
  77 This document defines an extension to that API to support an optional
  78 LDAP protocol extension for scrolling view browsing of search results,
  79 also known as Virtual List View [VLV].
  80
  81 The scrolling view browsing LDAP extension itself is designed to allow a
  82 "virtual list box" feature to be supported efficiently by LDAP servers
  83 and clients.  The protocol extension consists of two LDAP controls:  a
  84 Virtual List View (VLV) Request control which is sent by a client to a
  85 server along with an LDAP search request and a Virtual List View
  86 Response control which is returned by the server to send back status
  87 information about the VLV request.
  88
  89 LDAP clients that wish to use the "virtual list box" feature SHOULD
  90 first check the supportedControls attribute in a server's rootDSE to
  91
  92 Expires: 18 April 2000                                          [Page 2]
  93
  94 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
  95
  96 determine if a value identical to the Virtual List View Request
  97 control's OID is present.  If the OID is present and the client chooses
  98 to use the VLV feature, it MUST construct a Virtual List View Request
  99 control and a Server Side Sorting Control [SSS] and send both controls
 100 to the server within an LDAP searchRequest message.  Both controls
 101 SHOULD be marked critical.  Client applications MAY use the
 102 ldap_create_vlv_control() function described in this document to create
 103 a Virtual List View Request control.
 104
 105 At the end of the search request processing, the server SHOULD return a
 106 Virtual List View Response control in the LDAP searchResultDone message.
 107 A Virtual List View Response control MAY be parsed to extract its con-
 108 tents by using the ldap_parse_vlv_control() function described in this
 109 document.
 110
 111 5.  Advertising the Virtual List View C LDAP API Extension
 112
 113 To conform with the requirements defined in the C LDAP API specification
 114 [CAPI], implementations that support this extension SHOULD advertise the
 115 existence of this extension as follows:
 116
 117    Define the macro LDAP_API_FEATURE_VIRTUAL_LIST_VIEW as a value that
 118    corresponds to the "level" or revision of this specification.  When
 119    this document is published as an RFC, the value to use for
 120    LDAP_API_FEATURE_VIRTUAL_LIST_VIEW is the RFC number itself.  While
 121    this document is an Internet Draft, the value to use is 1000 plus the
 122    revision number of this draft, i.e., 1000 for the -00 revision of
 123    this draft, 1001 for the -01 version, and so on.
 124
 125    Return the text string VIRTUAL_LIST_VIEW in the ldapai_extensions
 126    array of the LDAPAPIInfo structure following a successful call to
 127    ldap_get_option() with an option parameter value of
 128    LDAP_OPT_API_INFO.
 129
 130    Return information about the extension when the ldapaif_name field in
 131    the LDAPAPIFeatureInfo structure is set to the text string
 132    VIRTUAL_LIST_VIEW and a call to ldap_get_option() with an option
 133    parameter value of LDAP_OPT_API_FEATURE_INFO is made.
 134
 135 6.  Creating a Virtual List View Request Control
 136
 137 The LDAPVLVInfo structure describes a Virtual List View Request control
 138 and is passed to the ldap_create_vlv_control() function to create a Vir-
 139 tualListViewRequest control.  The resulting control SHOULD be passed to
 140
 141 Expires: 18 April 2000                                          [Page 3]
 142
 143 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 144
 145 the ldap_search_ext() or ldap_search_ext_s() functions described in
 146 [CAPI] to send them to the server.  The ldap_create_sort_control() func-
 147 tion described in [SSSAPI] MAY be used to create a Sort control that is
 148 be passed to the server along with the VirtualListViewRequest control.
 149
 150 The LDAPVLVInfo structure MAY also be used by applications to manage the
 151 state information associated with a series of virtual list view
 152 client/server interactions.
 153
 154     /* LDAPVLVInfo structure: */
 155     typedef struct ldapvlvinfo {
 156         int             ldvlv_version;    /* version of this struct (1) */
 157         unsigned long   ldvlv_before_count;
 158         unsigned long   ldvlv_after_count;
 159         unsigned long   ldvlv_offset;     /* used if ldvlv_attrvalue is NULL
 160 */
 161         unsigned long   ldvlv_count;      /* used if ldvlv_attrvalue is NULL
 162 *
 163         struct berval   *ldvlv_attrvalue;
 164         struct berval   *ldvlv_context;
 165         void            *ldvlv_extradata; /* for use by application */
 166     } LDAPVLVInfo;
 167
 168     /* value for the ldvlv_version field of the LDAPVLVInfo structure: */
 169     #define LDAP_VLVINFO_VERSION        1
 170
 171     /* function used to create a VirtualListViewRequest control: */
 172     int ldap_create_vlv_control(
 173         LDAP            *ld,
 174         LDAPVLVInfo     *vlvinfop,
 175         LDAPControl     **ctrlp
 176     );
 177
 178     /* OID of the VirtualListViewRequest control: */
 179     #define LDAP_CONTROL_VLVREQUEST     "2.16.840.1.113730.3.4.9"
 180
 181 The parameters to the ldap_create_vlv_control() function are:
 182
 183 ld                  An LDAP session handle, as obtained from a call to
 184                     ldap_init().
 185
 186 vlvinfop            The address of an LDAPVLVInfo structure whose con-
 187                     tents are used to construct the value of the control
 188                     that is created.
 189
 190 ctrlp               A result parameter that will be assigned the address
 191                     of an LDAPControl structure that contains the Virtu-
 192                     alListViewRequest control created by this function.
 193                     The memory occupied by the LDAPControl structure
 194                     SHOULD be freed when it is no longer in use by
 195
 196 Expires: 18 April 2000                                          [Page 4]
 197
 198 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 199
 200                     calling ldap_control_free().
 201
 202 The ldap_create_vlv_control() function returns a C LDAP API error code
 203 to indicate success or failure (LDAP_SUCCESS if all goes well).
 204
 205 The members of the LDAPVLVInfo structure are:
 206
 207 ldvlv_version       A number that identifies the version of the
 208                     LDAPVLVInfo structure.  This SHOULD always be set to
 209                     the value LDAP_VLVINFO_VERSION (1).
 210
 211 ldvlv_before_count  A count of the number of entries before the target
 212                     entry the client wants the server to send back.
 213                     This field corresponds to the beforeCount element of
 214                     the BER-encoded VirtualListViewRequest control value
 215                     itself.
 216
 217 ldvlv_after_count   A count of the number of entries after the target
 218                     entry the client wants the server to send back.
 219                     This field corresponds to the afterCount element of
 220                     the BER-encoded VirtualListViewRequest control value
 221                     itself.
 222
 223 ldvlv_offset        This field is only used if ldvlv_attrvalue is NULL,
 224                     i.e, if the byoffset choice within the VirtualList-
 225                     ViewRequest control is to be used.  ldvlv_offset is
 226                     used along with the ldvlv_count value by the server
 227                     to determine the target entry.  This field
 228                     corresponds to the offset element within the BER-
 229                     encoded VirtualListViewRequest control value itself.
 230
 231 ldvlv_count         This field is only used if ldvlv_attrvalue is NULL,
 232                     i.e., if the byIndex choice within the VirtualList-
 233                     ViewRequest control is to be used.  ldvlv_count is
 234                     used along with the ldvlv_offset value by the server
 235                     to determine the target entry.  This field
 236                     corresponds to the contentCount element within the
 237                     BER-encoded VirtualListViewRequest control value
 238                     itself.
 239
 240 ldvlv_attrvalue     If this is not NULL, it indicates that the
 241                     greaterThanOrEqual choice within the VirtualList-
 242                     ViewRequest is to be used.  ldvlv_attrvalue
 243                     corresponds to the assertionValue element of the
 244                     BER-encoded VirtualListViewRequest control value
 245                     itself.  This value is compared by the server with
 246                     the values of the attribute specified by the primary
 247                     sort key to determine the target entry.
 248
 249 Expires: 18 April 2000                                          [Page 5]
 250
 251 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 252
 253 ldvlv_context       If this is not NULL, it is included as the context
 254                     identifier in the VirtualListViewRequest control;
 255                     ldvlv_context corresponds to the contextID element
 256                     within the BER-encoded VirtualListViewRequest con-
 257                     trol value itself.  If ldvlv_context is NULL, no
 258                     context identifier is included in the VirtualList-
 259                     ViewRequest control.
 260
 261 ldvlv_extradata     This field is reserved for application-specific use
 262                     and is not used by the ldap_create_vlv_control()
 263                     function; it has no effect on the control that is
 264                     created.
 265
 266 7.  Parsing a Virtual List View Response Control
 267
 268 When an application receives the result from a VLV search, it SHOULD use
 269 the ldap_parse_vlv_control() function to look for and parse the Virtual
 270 List View Response control returned by the server.
 271
 272     /* function used to look for and parse a VirtualListViewResponse
 273 control: */
 274     int ldap_parse_vlv_control(
 275         LDAP            *ld,
 276         LDAPControl     **ctrls,
 277         unsigned long   *target_posp,
 278         unsigned long   *list_countp,
 279         struct berval   **contextp,
 280         int             *errcodep
 281     );
 282
 283     /* OID of the VirtualListViewResponse control: */
 284     #define LDAP_CONTROL_VLVRESPONSE        "2.16.840.1.113730.3.4.10"
 285
 286     /* new error codes: */
 287     #define LDAP_SORT_CONTROL_MISSING       0x3C    /* 60 */
 288     #define LDAP_INDEX_RANGE_ERROR          0x3D    /* 61 */
 289
 290 The parameters to the ldap_parse_vlv_control() function are:
 291
 292 ld                  An LDAP session handle.
 293
 294 ctrls               The address of a NULL-terminated array of LDAPCon-
 295                     trol structures, typically obtained by a call to
 296                     ldap_parse_result().
 297
 298 target_posp         This result parameter is filled in with the list
 299                     index of the target entry.  If this parameter is
 300                     NULL, the target position is not returned.  The
 301
 302 Expires: 18 April 2000                                          [Page 6]
 303
 304 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 305
 306                     value for this result parameter is pulled from the
 307                     targetPosition element of the BER-encoded Virtual-
 308                     ListViewResponse control value itself.
 309
 310 list_countp         This result parameter is filled in with the server's
 311                     estimate of the size of the list.  If this parameter
 312                     is NULL, the size is not returned.  The value for
 313                     this result parameter is pulled from the con-
 314                     tentCount element of the BER-encoded VirtualList-
 315                     ViewResponse control value itself.
 316
 317 contextp            This result parameter is filled in with the address
 318                     of a struct berval that contains the server-
 319                     generated context identifier if one was returned by
 320                     the server.  If the server did not return a context
 321                     identifier, this parameter will be set to NULL.  The
 322                     struct berval returned SHOULD be disposed of by cal-
 323                     ling ber_bvfree() when it is no longer needed.  If
 324                     NULL is passed for contextp, the context identifier
 325                     is not returned.
 326
 327 errcodep            This result parameter is filled in with the VLV
 328                     result code.  If this parameter is NULL, the result
 329                     code is not returned.  The value for this result
 330                     parameter is pulled from the virtualListViewResult
 331                     element of the BER-encoded VirtualListViewResponse
 332                     control value itself.  As specified in the VLV pro-
 333                     tocol extension [VLV], it will have one of the fol-
 334                     lowing values:
 335
 336                        LDAP_SUCCESS                (0);  defined in [CAPI]
 337                        LDAP_OPERATIONS_ERROR       (1);  defined in [CAPI]
 338                        LDAP_UNWILLING_TO_PERFORM   (53); defined in [CAPI]
 339                        LDAP_INSUFFICIENT_ACCESS    (50); defined in [CAPI]
 340                        LDAP_BUSY                   (51); defined in [CAPI]
 341                        LDAP_TIMELIMIT_EXCEEDED     (3);  defined in [CAPI]
 342                        LDAP_ADMINLIMIT_EXCEEDED    (11); defined in [CAPI]
 343                        LDAP_SORT_CONTROL_MISSING   (60); defined above
 344                        LDAP_INDEX_RANGE_ERROR      (61); defined above
 345                        LDAP_OTHER                  (80); defined in [CAPI]
 346
 347 The ldap_parse_vlv_control() function returns an LDAP error code that
 348 indicates whether a VLV Result control was found and whether the parsing
 349 was successful.  LDAP_SUCCESS is returned if all goes well,
 350 LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does not include a
 351 VirtualListViewResponse control, and another LDAP error code that is
 352 defined in [CAPI] is returned if a parsing error or other problem
 353 occurs.
 354
 355 Expires: 18 April 2000                                          [Page 7]
 356
 357 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 358
 359 8.  Example Code
 360
 361 To be provided.
 362
 363 9.  Security Considerations
 364
 365 Most servers will be configured to restrict access to the Virtual List
 366 View feature since poorly-behaved or malicious clients may cause many
 367 resources to be consumed on the server, or allow users to retrieve too
 368 many entries, or allow users to get an accurate count of the number of
 369 entries present in a portion of the DIT.  Clients should take care to
 370 not abuse the VLV feature and should be prepared for servers to refuse
 371 to service a particular VLV request due to access control or other
 372 site-defined policies.
 373
 374 Please see the protocol extension document [VLV] for a discussion of
 375 related security considerations.
 376
 377 10.  Copyright
 378
 379 Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
 380
 381 This document and translations of it may be copied and furnished to oth-
 382 ers, and derivative works that comment on or otherwise explain it or
 383 assist in its implementation may be prepared, copied, published and dis-
 384 tributed, in whole or in part, without restriction of any kind, provided
 385 that the above copyright notice and this paragraph are included on all
 386 such copies and derivative works.  However, this document itself may not
 387 be modified in any way, such as by removing the copyright notice or
 388 references to the Internet Society or other Internet organizations,
 389 except as needed for the  purpose of developing Internet standards in
 390 which case the procedures for copyrights defined in the Internet Stan-
 391 dards process must be followed, or as required to translate it into
 392 languages other than English.
 393
 394 The limited permissions granted above are perpetual and will not be
 395 revoked by the Internet Society or its successors or assigns.
 396
 397 This document and the information contained herein is provided on an "AS
 398 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
 399 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 400 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
 401 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
 402 NESS FOR A PARTICULAR PURPOSE.
 403
 404 Expires: 18 April 2000                                          [Page 8]
 405
 406 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 407
 408 11.  Bibliography
 409
 410 [CAPI]      M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C
 411             LDAP Application Program Interface", INTERNET-DRAFT,
 412             <draft-ietf-ldapext-ldap-c-api-04.txt>, 8 October 1999.
 413
 414 [KEYWORDS]  S. Bradner, "Key words for use in RFCs to Indicate Require-
 415             ment Levels", RFC 2119, March 1997.
 416
 417 [LDAP]      M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
 418             Protocol (v3)", RFC 2251, December 1997.
 419
 420 [SSS]       A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control
 421             Extension for Server Side Sorting of Search Results",
 422             INTERNET-DRAFT, April 1999.
 423
 424 [SSSAPI]    C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API
 425             Extensions for Sort and Simple Paged Results", INTERNET-
 426             DRAFT, <draft-ietf-asid-ldapv3-api-ext-00.txt>, July 1997.
 427
 428 [VLV]       D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP
 429             Extensions for Scrolling View Browsing of Search Results",
 430             INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-vlv-03.txt>, 11
 431             June 1999.
 432
 433 12.  Author's Address
 434
 435    Mark Smith
 436    Netscape Communications Corp.
 437    501 E. Middlefield Rd., Mailstop MV068
 438    Mountain View, CA 94043
 439    USA
 440    +1 650 937-3477
 441    mcs@netscape.com
 442
 443 13.  Appendix A - Summary of Additions to the C LDAP API
 444
 445 This extension introduces the following macros:
 446
 447    LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
 448    LDAP_VLVINFO_VERSION
 449    LDAP_CONTROL_VLVREQUEST
 450    LDAP_CONTROL_VLVRESPONSE
 451    LDAP_SORT_CONTROL_MISSING
 452    LDAP_INDEX_RANGE_ERROR
 453
 454 Expires: 18 April 2000                                          [Page 9]
 455
 456 INTERNET-DRAFT   LDAP C API Virtual List View Extension  18 October 1999
 457
 458 This extension introduces the following structures and typedefs:
 459
 460    ldapvlvinfo
 461    LDAPVLVInfo
 462
 463 This extension introduces the following functions:
 464
 465    ldap_create_vlv_control()
 466    ldap_parse_vlv_control()
 467
 468 Expires: 18 April 2000                                         [Page 10]