1 Network Working Group M. Smith
2 INTERNET-DRAFT Netscape Communications Corp.
3 Intended Category: Standards Track
8 LDAP C API Virtual List View Extension
9 <draft-smith-ldap-c-api-ext-vlv-00.txt>
11 1. Status of this Memo
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.
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."
24 The list of current Internet-Drafts can be accessed at
25 http://www.ietf.org/ietf/1id-abstracts.txt.
27 The list of Internet-Draft Shadow Directories can be accessed at
28 http://www.ietf.org/shadow.html.
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>.
36 Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
38 Please see the Copyright section near the end of this document for more
41 Expires: 18 April 2000 [Page 1]
43 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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
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].
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
73 4. Background and Intended Usage
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].
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.
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
92 Expires: 18 April 2000 [Page 2]
94 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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.
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
111 5. Advertising the Virtual List View C LDAP API Extension
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:
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.
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
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.
135 6. Creating a Virtual List View Request Control
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
141 Expires: 18 April 2000 [Page 3]
143 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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.
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.
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
161 unsigned long ldvlv_count; /* used if ldvlv_attrvalue is NULL
163 struct berval *ldvlv_attrvalue;
164 struct berval *ldvlv_context;
165 void *ldvlv_extradata; /* for use by application */
168 /* value for the ldvlv_version field of the LDAPVLVInfo structure: */
169 #define LDAP_VLVINFO_VERSION 1
171 /* function used to create a VirtualListViewRequest control: */
172 int ldap_create_vlv_control(
174 LDAPVLVInfo *vlvinfop,
178 /* OID of the VirtualListViewRequest control: */
179 #define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
181 The parameters to the ldap_create_vlv_control() function are:
183 ld An LDAP session handle, as obtained from a call to
186 vlvinfop The address of an LDAPVLVInfo structure whose con-
187 tents are used to construct the value of the control
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
196 Expires: 18 April 2000 [Page 4]
198 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
200 calling ldap_control_free().
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).
205 The members of the LDAPVLVInfo structure are:
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).
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
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
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.
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
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.
249 Expires: 18 April 2000 [Page 5]
251 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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-
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
266 7. Parsing a Virtual List View Response Control
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.
272 /* function used to look for and parse a VirtualListViewResponse
274 int ldap_parse_vlv_control(
277 unsigned long *target_posp,
278 unsigned long *list_countp,
279 struct berval **contextp,
283 /* OID of the VirtualListViewResponse control: */
284 #define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
286 /* new error codes: */
287 #define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */
288 #define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */
290 The parameters to the ldap_parse_vlv_control() function are:
292 ld An LDAP session handle.
294 ctrls The address of a NULL-terminated array of LDAPCon-
295 trol structures, typically obtained by a call to
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
302 Expires: 18 April 2000 [Page 6]
304 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
306 value for this result parameter is pulled from the
307 targetPosition element of the BER-encoded Virtual-
308 ListViewResponse control value itself.
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.
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
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-
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]
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
355 Expires: 18 April 2000 [Page 7]
357 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
363 9. Security Considerations
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.
374 Please see the protocol extension document [VLV] for a discussion of
375 related security considerations.
379 Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
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.
394 The limited permissions granted above are perpetual and will not be
395 revoked by the Internet Society or its successors or assigns.
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.
404 Expires: 18 April 2000 [Page 8]
406 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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.
414 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
415 ment Levels", RFC 2119, March 1997.
417 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
418 Protocol (v3)", RFC 2251, December 1997.
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.
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.
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
436 Netscape Communications Corp.
437 501 E. Middlefield Rd., Mailstop MV068
438 Mountain View, CA 94043
443 13. Appendix A - Summary of Additions to the C LDAP API
445 This extension introduces the following macros:
447 LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
449 LDAP_CONTROL_VLVREQUEST
450 LDAP_CONTROL_VLVRESPONSE
451 LDAP_SORT_CONTROL_MISSING
452 LDAP_INDEX_RANGE_ERROR
454 Expires: 18 April 2000 [Page 9]
456 INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
458 This extension introduces the following structures and typedefs:
463 This extension introduces the following functions:
465 ldap_create_vlv_control()
466 ldap_parse_vlv_control()
468 Expires: 18 April 2000 [Page 10]