mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2024-11-21 01:04:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

Not needed in re20

Browse Source
This commit is contained in:
Kurt Zeilenga 2001-01-03 22:17:14 +00:00
parent 65de94781a
commit a9d4a03638
2 changed files with 0 additions and 1123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

655
doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt
View File

@ -1,655 +0,0 @@
INTERNET-DRAFT David Boreham, Netscape
Jim Sermersheim, Novell
Anoop Anantha, Microsoft
Michael Armijo, Microsoft
ldapext Working Group 6 April, 2000
LDAP Extensions for Scrolling View Browsing of Search Results
draft-ietf-ldapext-ldapv3-vlv-04.txt
This document expires on 5 October 2000
1. Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026. 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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
2. Abstract
This document describes a Virtual List View control extension for the
LDAP Search operation. This control is designed to allow the "virtual
list box" feature, common in existing commercial e-mail address book
applications, to be supported efficiently by LDAP servers. LDAP servers'
inability to support this client feature is a significant impediment to
LDAP replacing proprietary protocols in commercial e-mail systems.
The control allows a client to specify that the server return, for a
given LDAP search with associated sort keys, a contiguous subset of the
search result set. This subset is specified in terms of offsets into the
ordered list, or in terms of a greater than or equal comparison value.
3. Background
A Virtual List is a graphical user interface technique employed where
Boreham et al [Page 1]
RFC DRAFT April 2000
ordered lists containing a large number of entries need to be displayed.
A window containing a small number of visible list entries is drawn. The
visible portion of the list may be relocated to different points within
the list by means of user input. This input can be to a scroll bar
slider; from cursor keys; from page up/down keys; from alphanumeric keys
for "typedown". The user is given the impression that they may browse
the complete list at will, even though it may contain millions of
entries. It is the fact that the complete list contents are never
required at any one time that characterizes Virtual List View. Rather
than fetch the complete list from wherever it is stored (typically from
disk or a remote server), only that information which is required to
display the part of the list currently in view is fetched. The subject
of this document is the interaction between client and server required
to implement this functionality in the context of the results from a
sorted LDAP search request.
For example, suppose an e-mail address book application displays a list
view onto the list containing the names of all the holders of e-mail
accounts at a large university. The list is sorted alphabetically.
While there may be tens of thousands of entries in this list, the
address book list view displays only 20 such accounts at any one time.
The list has an accompanying scroll bar and text input window for type-
down. When first displayed, the list view shows the first 20 entries in
the list, and the scroll bar slider is positioned at the top of its
range. Should the user drag the slider to the bottom of its range, the
displayed contents of the list view should be updated to show the last
20 entries in the list. Similarly, if the slider is positioned somewhere
in the middle of its travel, the displayed contents of the list view
should be updated to contain the 20 entries located at that relative
position within the complete list. Starting from any display point, if
the user uses the cursor keys or clicks on the scroll bar to request
that the list be scrolled up or down by one entry, the displayed con-
tents should be updated to reflect this. Similarly the list should be
displayed correctly when the user requests a page scroll up or down.
Finally, when the user types characters in the type-down window, the
displayed contents of the list should "jump" or "seek" to the appropri-
ate point within the list. For example, if the user types "B", the
displayed list could center around the first user with a name beginning
with the letter "B". When this happens, the scroll bar slider should
also be updated to reflect the new relative location within the list.
This document defines a request control which extends the LDAP search
operation. Always used in conjunction with the server side sorting
control[SSS], this allows a client to retrieve selected portions of
large search result set in a fashion suitable for the implementation of
a virtual list view.
The key words "MUST", "SHOULD", and "MAY" used in this document are to
Boreham et al [Page 2]
RFC DRAFT April 2000
be interpreted as described in [Bradner97].
4. Client-Server Interaction
The Virtual List View control extends a regular LDAP Search operation
which must also include a server-side sorting control[SSS]. Rather than
returning the complete set of appropriate SearchResultEntry messages,
the server is instructed to return a contiguous subset of those entries,
taken from the sorted result set, centered around a particular target
entry. Henceforth, in the interests of brevity, the sorted search result
set will be referred to as "the list".
The sort control MAY contain any sort specification valid for the
server. The attributeType field in the first SortKeyList sequence ele-
ment has special significance for "typedown".
The desired target entry, and the number of entries to be returned both
before, and after, that target entry in the list, are determined by the
client's VirtualListViewRequest control.
When the server returns the set of entries to the client, it attaches a
VirtualListViewResponse control to the SearchResultDone message. The
server returns in this control: its current estimate for the list con-
tent count, the location within the list corresponding to the target
entry, and any error codes.
The target entry is specified in the VirtualListViewRequest control by
one of two methods. The first method is for the client to indicate the
target entry's offset within the list. The second way is for the client
to supply an attribute assertion value. The value is compared against
the values of the attribute specified as the primary sort key in the
sort control attached to the search operation. The first sort key in
the SortKeyList is the primary sort key. The target entry is the first
entry in the list with value greater than or equal to (in the primary
sort order), the presented value. The order is determined by rules
defined in [SSS]. Selection of the target entry by this means is
designed to implement "typedown". Note that it is possible that no
entry satisfies these conditions, in which case there is no target
entry. This condition is indicated by the server returning the special
value contentCount + 1 in the target position field.
Because the server may not have an accurate estimate of the number of
entries in the list, and to take account of cases where the list size is
changing during the time the user browses the list, and because the
client needs a way to indicate specific list targets "beginning" and
"end", offsets within the list are transmitted between client and server
as ratios---offset to content count. The server sends its latest esti-
mate as to the number of entries in the list (content count) to the
Boreham et al [Page 3]
RFC DRAFT April 2000
client in every response control. The client sends its assumed value
for the content count in every request control. The server examines the
content count and offsets presented by the client and computes the
corresponding offsets within the list, based on its own idea of the con-
tent count.
Si = Sc * (Ci / Cc)
Where:
Si is the actual list offset used by the server
Sc is the server's estimate for content count
Ci is the client's submitted offset
Cc is the client's submitted content count
The result is rounded to the nearest integer.
If the content count is stable, and the client returns to the server the
content count most recently received, Cc = Sc and the offsets transmit-
ted become the actual server list offsets.
The following special cases are allowed: a client sending a content
count of zero (Cc = 0) means "client has no idea what the content count
is, server MUST use its own content count estimate in place of the
client's". An offset value of one (Ci = 1) always means that the target
is the first entry in the list. Client specifying an offset which equals
the content count specified in the same request control (Ci = Cc) means
that the target is the last entry in the list. Ci may only equal zero
when Cc is also zero. This signifies the last entry in the list.
Because the server always returns contentCount and targetPosition, the
client can always determine which of the returned entries is the target
entry. Where the number of entries returned is the same as the number
requested, the client is able to identify the target by simple arith-
metic. Where the number of entries returned is not the same as the
number requested (because the requested range crosses the beginning or
end of the list, or both), the client must use the target position and
content count values returned by the server to identify the target
entry. For example, suppose that 10 entries before and 10 after the tar-
get were requested, but the server returns 13 entries, a content count
of 100 and a target position of 3. The client can determine that the
first entry must be entry number 1 in the list, therefore the 13 entries
returned are the first 13 entries in the list, and the target is the
third one.
A server-generated context identifier MAY be returned to clients. A
client receiving a context identifier SHOULD return it unchanged in a
subsequent request which relates to the same list. The purpose of this
interaction is to enhance the performance and effectiveness of servers
which employ approximate positioning.
Boreham et al [Page 4]
RFC DRAFT April 2000
5. The Controls
Support for the virtual list view control extension is indicated by the
presence of the OID "2.16.840.1.113730.3.4.9" in the supportedControl
attribute of a server's root DSE.
5.1. Request Control
This control is included in the SearchRequest message as part of the
controls field of the LDAPMessage, as defined in Section 4.1.12 of
[LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri-
ticality SHOULD be set to TRUE. If this control is included in a Sear-
chRequest message, a Server Side Sorting request control [SSS] MUST also
be present in the message. The controlValue is an OCTET STRING whose
value is the BER-encoding of the following SEQUENCE:
VirtualListViewRequest ::= SEQUENCE {
beforeCount INTEGER (0..maxInt),
afterCount INTEGER (0..maxInt),
CHOICE {
byoffset [0] SEQUENCE {
offset INTEGER (0 .. maxInt),
contentCount INTEGER (0 .. maxInt) },
greaterThanOrEqual [1] AssertionValue },
contextID OCTET STRING OPTIONAL }
beforeCount indicates how many entries before the target entry the
client wants the server to send. afterCount indicates the number of
entries after the target entry the client wants the server to send.
offset and contentCount identify the target entry as detailed in section
4. greaterThanOrEqual is an attribute assertion value defined in
[LDAPv3]. If present, the value supplied in greaterThanOrEqual is used
to determine the target entry by comparison with the values of the
attribute specified as the primary sort key. The first list entry who's
value is no less than (less than or equal to when the sort order is
reversed) the supplied value is the target entry. If present, the con-
textID field contains the value of the most recently received contextID
field from a VirtualListViewResponse control. The type AssertionValue
and value maxInt are defined in [LDAPv3]. contextID values have no
validity outwith the connection on which they were received. That is, a
client should not submit a contextID which it received from another con-
nection, a connection now closed, or a different server.
5.2. Response Control
This control is included in the SearchResultDone message as part of the
controls field of the LDAPMessage, as defined in Section 4.1.12 of
Boreham et al [Page 5]
RFC DRAFT April 2000
[LDAPv3].
The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is
FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value
is the BER encoding of a value of the following SEQUENCE:
VirtualListViewResponse ::= SEQUENCE {
targetPosition INTEGER (0 .. maxInt),
contentCount INTEGER (0 .. maxInt),
virtualListViewResult ENUMERATED {
success (0),
operationsError (1),
unwillingToPerform (53),
insufficientAccessRights (50),
busy (51),
timeLimitExceeded (3),
adminLimitExceeded (11),
sortControlMissing (60),
offsetRangeError (61),
other (80) },
contextID OCTET STRING OPTIONAL }
targetPosition gives the list offset for the target entry. contentCount
gives the server's estimate of the current number of entries in the
list. Together these give sufficient information for the client to
update a list box slider position to match the newly retrieved entries
and identify the target entry. The contentCount value returned SHOULD be
used in a subsequent VirtualListViewRequest control. contextID is a
server-defined octet string. If present, the contents of the contextID
field SHOULD be returned to the server by a client in a subsequent Vir-
tualListViewRequest control.
The virtualListViewResult codes which are common to the LDAP sear-
chResponse (adminLimitExceeded, timeLimitExceeded, busy, operationsEr-
ror, unwillingToPerform, insufficientAccessRights) have the same mean-
ings as defined in [LDAPv3], but they pertain specifically to the VLV
operation. For example, the server could exceed an administration limit
processing a SearchRequest with a VirtualListViewRequest control. How-
ever, the same administration limit would not be exceeded should the
same SearchRequest be submitted by the client without the VirtualList-
ViewRequest control. In this case, the client can determine that an
administration limit has been exceeded in servicing the VLV request, and
can if it chooses resubmit the SearchRequest without the VirtualList-
ViewRequest control.
insufficientAccessRights means that the server denied the client permis-
sion to perform the VLV operation.
Boreham et al [Page 6]
RFC DRAFT April 2000
If the server determines that the results of the search presented exceed
the range provided by the 32-bit offset values, it MUST return
offsetRangeError.
6. Protocol Example
Here we walk through the client-server interaction for a specific vir-
tual list view example: The task is to display a list of all 78564 peo-
ple in the US company "Ace Industry". This will be done by creating a
graphical user interface object to display the list contents, and by
repeatedly sending different versions of the same virtual list view
search request to the server. The list view displays 20 entries on the
screen at a time.
We form a search with baseDN "o=Ace Industry, c=us"; search scope sub-
tree; filter "objectClass=inetOrgPerson". We attach a server sort order
control to the search, specifying ascending sort on attribute "cn". To
this base search, we attach a virtual list view request control with
contents determined by the user activity and send the search to the
server. We display the results from each search in the list window and
update the slider position.
When the list view is first displayed, we want to initialize the con-
tents showing the beginning of the list. Therefore, we set beforeCount =
0, afterCount = 19, contentCount = 0, offset = 1 and send the request to
the server. The server duly returns the first 20 entries in the list,
plus the content count = 78564 and targetPosition = 1. We therefore
leave the scroll bar slider at its current location (the top of its
range).
Say that next the user drags the scroll bar slider down to the bottom of
its range. We now wish to display the last 20 entries in the list, so
we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset =
78564 and send the request to the server. The server returns the last 20
entries in the list, plus the content count = 78564 and targetPosition =
78564.
Next the user presses a page up key. Our page size is 20, so we set
beforeCount = 0, afterCount = 19, contentCount = 78564, offset =
78564-19-20 and send the request to the server. The server returns the
preceding 20 entries in the list, plus the content count = 78564 and
targetPosition = 78525.
Now the user grabs the scroll bar slider and drags it to 68% of the way
down its travel. 68% of 78564 is 53424 so we set beforeCount = 9, after-
Count = 10, contentCount = 78564, offset = 53424 and send the request to
the server. The server returns the preceding 20 entries in the list,
plus the content count = 78564 and targetPosition = 53424.
Boreham et al [Page 7]
RFC DRAFT April 2000
Lastly, the user types the letter "B". We set beforeCount = 9, after-
Count = 10 and greaterThanOrEqual = "B". The server finds the first
entry in the list not less than "B", let's say "Babs Jensen", and
returns the nine preceding entries, the target entry, and the proceeding
10 entries. The server returns content count = 78564 and targetPosition
= 5234 and so the client updates its scroll bar slider to 6.7% of full
scale.
7. Notes for Implementers
While the feature is expected to be generally useful for arbitrary
search and sort specifications, it is specifically designed for those
cases where the result set is very large. The intention is that this
feature be implemented efficiently by means of pre-computed indices per-
taining to a set of specific cases. For example, an offset relating to
"all the employees in the local organization, sorted by surname" would
be a common case.
The intention for client software is that the feature should fit easily
with the host platform's graphical user interface facilities for the
display of scrolling lists. Thus the task of the client implementers
should be one of reformatting up the requests for information received
from the list view code to match the format of the virtual list view
request and response controls.
Client implementers should note that any offset value returned by the
server may be approximate. Do not design clients > which only operate
correctly when offsets are exact.
Server implementers using indexing technology which features approximate
positioning should consider returning context identifiers to clients.
The use of a context identifier will allow the server to distinguish
between client requests which relate to different displayed lists on the
client. Consequently the server can decide more intelligently whether to
reposition an existing database cursor accurately to within a short dis-
tance of its current position, or to reposition to an approximate posi-
tion. Thus the client will see precise offsets for "short" repositioning
(e.g. paging up or down), but approximate offsets for a "long" reposi-
tion (e.g. a slider movement).
Server implementers are free to return status code unwillingToPerform
should their server be unable to service any particular VLV search.
This might be because the resolution of the search is computationally
infeasible, or because excessive server resources would be required to
service the search.
Client implementers should note that this control is only defined on a
client interaction with a single server. If a server returns referrals
Boreham et al [Page 8]
RFC DRAFT April 2000
as a part of its response to the search request, the client is responsi-
ble for deciding when and how to apply this control to the referred-to
servers, and how to collate the results from multiple servers.
8. Relationship to "Simple Paged Results"
These controls are designed to support the virtual list view, which has
proved hard to implement with the Simple Paged Results mechanism
[SPaged]. However, the controls described here support any operation
possible with the Simple Paged Results mechanism. The two mechanisms are
not complementary, rather one has a superset of the other's features.
One area where the mechanism presented here is not a strict superset of
the Simple Paged Results scheme is that here we require a sort order to
be specified. No such requirement is made for paged results.
9. Security Considerations
Server implementers may wish to consider whether clients are able to
consume excessive server resources in requesting virtual list opera-
tions. Access control to the feature itself; configuration options lim-
iting the feature's use to certain predetermined search base DNs and
filters; throttling mechanisms designed to limit the ability for one
client to soak up server resources, may be appropriate.
Consideration should be given as to whether a client will be able to
retrieve the complete contents, or a significant subset of the complete
contents of the directory using this feature. This may be undesirable in
some circumstances and consequently it may be necessary to enforce some
access control.
Clients can, using this control, determine how many entries are con-
tained within a portion of the DIT. This may constitute a security
hazard. Again, access controls may be appropriate.
Server implementers SHOULD exercise caution concerning the content of
the contextID. Should the contextID contain internal server state, it
may be possible for a malicious client to use that information to gain
unauthorized access to information.
10. Acknowledgements
Chris Weider of Microsoft co-authored a previous version of this docu-
ment.
Boreham et al [Page 9]
RFC DRAFT April 2000
11. References
[LDAPv3]
Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro-
tocol (v3)", Internet Standard, December, 1997. RFC2251.
[SPaged]
Weider, C, A. Herron, A. Anantha, and T. Howes, "LDAP Control
Extension for Simple Paged Results Manipulation", September
1999. RFC2696
[SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
Side Sorting of Search Results", Internet Draft, April, 1999.
Available as draft-ietf-asid-ldapv3-sorting-02.txt.
[Bradner97]
Bradner, S., "Key Words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
12. Authors' Addresses
David Boreham
iPlanet e-commerce solutions
501 E. Middlefield Road
Mountain View, CA 94043, USA
+1 650 937-5206
dboreham@netscape.com
Jim Sermersheim
Novell
122 East 1700 South
Provo, Utah 84606, USA
jimse@novell.com
Anoop Anantha
Microsoft Corp.
1 Microsoft Way
Redmond, WA 98052, USA
+1 425 882-8080
anoopa@microsoft.com
Michael Armijo
Microsoft Corp.
1 Microsoft Way
Redmond, WA 98052, USA
+1 425 882-8080
micharm@microsoft.com
This document expires on 5 October 2000
Boreham et al [Page 10]
RFC DRAFT April 2000
Boreham et al [Page 11]

468
doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt
View File

@ -1,468 +0,0 @@
Network Working Group M. Smith
INTERNET-DRAFT Netscape Communications Corp.
Intended Category: Standards Track
Expires: 18 April 2000
18 October 1999
LDAP C API Virtual List View Extension
<draft-smith-ldap-c-api-ext-vlv-00.txt>
1. Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026. 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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
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>.
Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
Please see the Copyright section near the end of this document for more
information.
Expires: 18 April 2000 [Page 1]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
2. Introduction
This document defines a virtual list view extension for the LDAP C API
to support the LDAP protocol extensions for scrolling view browsing of
search results. More specifically, 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. Table of Contents
1. Status of this Memo............................................1
2. Introduction...................................................2
3. Table of Contents..............................................2
4. Background and Intended Usage..................................2
5. Advertising the Virtual List View C LDAP API Extension.........3
6. Creating a Virtual List View Request Control...................3
7. Parsing a Virtual List View Response Control...................6
8. Example Code...................................................8
9. Security Considerations........................................8
10. Copyright......................................................8
11. Bibliography...................................................9
12. Author's Address...............................................9
13. Appendix A - Summary of Additions to the C LDAP API............9
4. 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 an extension to that API to support an optional
LDAP protocol 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
Expires: 18 April 2000 [Page 2]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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_vlv_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_vlv_control() function described in this
document.
5. Advertising the Virtual List View C LDAP API Extension
To conform with the requirements defined in the C LDAP API specification
[CAPI], implementations that support this extension SHOULD advertise the
existence of this extension as follows:
Define the macro LDAP_API_FEATURE_VIRTUAL_LIST_VIEW as a value that
corresponds to the "level" or revision of this specification. When
this document is published as an RFC, the value to use for
LDAP_API_FEATURE_VIRTUAL_LIST_VIEW is the RFC number itself. While
this document is an Internet Draft, the value to use is 1000 plus the
revision number of this draft, i.e., 1000 for the -00 revision of
this draft, 1001 for the -01 version, and so on.
Return the text string VIRTUAL_LIST_VIEW in the ldapai_extensions
array of the LDAPAPIInfo structure following a successful call to
ldap_get_option() with an option parameter value of
LDAP_OPT_API_INFO.
Return information about the extension when the ldapaif_name field in
the LDAPAPIFeatureInfo structure is set to the text string
VIRTUAL_LIST_VIEW and a call to ldap_get_option() with an option
parameter value of LDAP_OPT_API_FEATURE_INFO is made.
6. Creating a Virtual List View Request Control
The LDAPVLVInfo structure describes a Virtual List View Request control
and is passed to the ldap_create_vlv_control() function to create a Vir-
tualListViewRequest control. The resulting control SHOULD be passed to
Expires: 18 April 2000 [Page 3]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
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 is
be passed to the server along with the VirtualListViewRequest control.
The LDAPVLVInfo structure MAY also be used by applications to manage the
state information associated with a series of virtual list view
client/server interactions.
/* LDAPVLVInfo structure: */
typedef struct ldapvlvinfo {
int ldvlv_version; /* version of this struct (1) */
unsigned long ldvlv_before_count;
unsigned long ldvlv_after_count;
unsigned long ldvlv_offset; /* used if ldvlv_attrvalue is NULL
*/
unsigned long ldvlv_count; /* used if ldvlv_attrvalue is NULL
*
struct berval *ldvlv_attrvalue;
struct berval *ldvlv_context;
void *ldvlv_extradata; /* for use by application */
} LDAPVLVInfo;
/* value for the ldvlv_version field of the LDAPVLVInfo structure: */
#define LDAP_VLVINFO_VERSION 1
/* function used to create a VirtualListViewRequest control: */
int ldap_create_vlv_control(
LDAP *ld,
LDAPVLVInfo *vlvinfop,
LDAPControl **ctrlp
);
/* OID of the VirtualListViewRequest control: */
#define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
The parameters to the ldap_create_vlv_control() function are:
ld An LDAP session handle, as obtained from a call to
ldap_init().
vlvinfop The address of an LDAPVLVInfo structure whose con-
tents 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 Virtu-
alListViewRequest control created by this function.
The memory occupied by the LDAPControl structure
SHOULD be freed when it is no longer in use by
Expires: 18 April 2000 [Page 4]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
calling ldap_control_free().
The ldap_create_vlv_control() function returns a C LDAP API error code
to indicate success or failure (LDAP_SUCCESS if all goes well).
The members of the LDAPVLVInfo structure are:
ldvlv_version A number that identifies the version of the
LDAPVLVInfo structure. This SHOULD always be set to
the value LDAP_VLVINFO_VERSION (1).
ldvlv_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.
ldvlv_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.
ldvlv_offset This field is only used if ldvlv_attrvalue is NULL,
i.e, if the byoffset choice within the VirtualList-
ViewRequest control is to be used. ldvlv_offset is
used along with the ldvlv_count value by the server
to determine the target entry. This field
corresponds to the offset element within the BER-
encoded VirtualListViewRequest control value itself.
ldvlv_count This field is only used if ldvlv_attrvalue is NULL,
i.e., if the byIndex choice within the VirtualList-
ViewRequest control is to be used. ldvlv_count is
used along with the ldvlv_offset value by the server
to determine the target entry. This field
corresponds to the contentCount element within the
BER-encoded VirtualListViewRequest control value
itself.
ldvlv_attrvalue If this is not NULL, it indicates that the
greaterThanOrEqual choice within the VirtualList-
ViewRequest is to be used. ldvlv_attrvalue
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.
Expires: 18 April 2000 [Page 5]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
ldvlv_context If this is not NULL, it is included as the context
identifier in the VirtualListViewRequest control;
ldvlv_context corresponds to the contextID element
within the BER-encoded VirtualListViewRequest con-
trol value itself. If ldvlv_context is NULL, no
context identifier is included in the VirtualList-
ViewRequest control.
ldvlv_extradata This field is reserved for application-specific use
and is not used by the ldap_create_vlv_control()
function; it has no effect on the control that is
created.
7. Parsing a Virtual List View Response Control
When an application receives the result from a VLV search, it SHOULD use
the ldap_parse_vlv_control() function to look for and parse the Virtual
List View Response control returned by the server.
/* function used to look for and parse a VirtualListViewResponse
control: */
int ldap_parse_vlv_control(
LDAP *ld,
LDAPControl **ctrls,
unsigned long *target_posp,
unsigned long *list_countp,
struct berval **contextp,
int *errcodep
);
/* OID of the VirtualListViewResponse control: */
#define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
/* new error codes: */
#define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */
#define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */
The parameters to the ldap_parse_vlv_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
Expires: 18 April 2000 [Page 6]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
value for this result parameter is pulled from the
targetPosition element of the BER-encoded Virtual-
ListViewResponse control value itself.
list_countp 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 con-
tentCount element of the BER-encoded VirtualList-
ViewResponse control value itself.
contextp This result parameter is filled in with the address
of a struct berval that contains the server-
generated context identifier if one was returned by
the server. If the server did not return a context
identifier, this parameter will be set to NULL. The
struct berval returned SHOULD be disposed of by cal-
ling ber_bvfree() when it is no longer needed. If
NULL is passed for contextp, the context identifier
is not returned.
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. As specified in the VLV pro-
tocol extension [VLV], it will have one of the fol-
lowing 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 (80); defined in [CAPI]
The ldap_parse_vlv_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
VirtualListViewResponse control, and another LDAP error code that is
defined in [CAPI] is returned if a parsing error or other problem
occurs.
Expires: 18 April 2000 [Page 7]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
8. Example Code
To be provided.
9. 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.
10. Copyright
Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
This document and translations of it may be copied and furnished to oth-
ers, 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,
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.
Expires: 18 April 2000 [Page 8]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
11. Bibliography
[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C
LDAP Application Program Interface", INTERNET-DRAFT,
<draft-ietf-ldapext-ldap-c-api-04.txt>, 8 October 1999.
[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, A. Anantha, "LDAP Control
Extension for Server Side Sorting of Search Results",
INTERNET-DRAFT, April 1999.
[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] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP
Extensions for Scrolling View Browsing of Search Results",
INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-vlv-03.txt>, 11
June 1999.
12. Author's Address
Mark Smith
Netscape Communications Corp.
501 E. Middlefield Rd., Mailstop MV068
Mountain View, CA 94043
USA
+1 650 937-3477
mcs@netscape.com
13. Appendix A - Summary of Additions to the C LDAP API
This extension introduces the following macros:
LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
LDAP_VLVINFO_VERSION
LDAP_CONTROL_VLVREQUEST
LDAP_CONTROL_VLVRESPONSE
LDAP_SORT_CONTROL_MISSING
LDAP_INDEX_RANGE_ERROR
Expires: 18 April 2000 [Page 9]
INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
This extension introduces the following structures and typedefs:
ldapvlvinfo
LDAPVLVInfo
This extension introduces the following functions:
ldap_create_vlv_control()
ldap_parse_vlv_control()
Expires: 18 April 2000 [Page 10]