idnits 2.17.1 draft-zeilenga-ldapext-vlv-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 771 has weird spacing: '...for the purpo...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (1 October 2002) is 7876 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'SUBENTRY' is mentioned on line 520, but not defined == Missing Reference: 'RFC2696' is mentioned on line 95, but not defined -- Looks like a reference, but probably isn't: '0' on line 173 -- Looks like a reference, but probably isn't: '1' on line 174 -- Looks like a reference, but probably isn't: '2' on line 179 -- Looks like a reference, but probably isn't: '3' on line 180 == Missing Reference: 'RFC2798' is mentioned on line 673, but not defined == Unused Reference: 'RFC2830' is defined on line 610, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2253 (Obsoleted by RFC 4510, RFC 4514) ** Obsolete normative reference: RFC 2830 (Obsoleted by RFC 4510, RFC 4511, RFC 4513) ** Obsolete normative reference: RFC 3377 (Obsoleted by RFC 4510) -- No information found for draft-ietf-ldapext-ldapv3-dupent-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'DUPENT' -- No information found for draft-ietf-ldapext-matchedval-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'MATCHED' -- Obsolete informational reference (is this intentional?): RFC 3383 (Obsoleted by RFC 4520) == Outdated reference: A later version (-09) exists of draft-ietf-ldapext-ldapv3-vlv-08 Summary: 9 errors (**), 0 flaws (~~), 8 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Kurt D. Zeilenga 3 OpenLDAP Foundation 4 Expires in six months 1 October 2002 6 LDAP (Alternative) Virtual List View Operation 7 9 1. Status of this Memo 11 This document is an Internet-Draft and is in full conformance with all 12 provisions of Section 10 of RFC2026. 14 This document is offered to IETF LDAPEXT WG as an alternative to 15 draft-ietf-ldapext-ldapv3-vlv-xx.txt. 17 This document is intended to be, after appropriate review and 18 revision, submitted to the RFC Editor as a Standard Track document. 19 Distribution of this memo is unlimited. Technical discussion of this 20 document will take place on the IETF LDAPEXT Working Group mailing 21 list . Please send editorial comments directly to 22 the author . 24 Internet-Drafts are working documents of the Internet Engineering Task 25 Force (IETF), its areas, and its working groups. Note that other 26 groups may also distribute working documents as Internet-Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as ``work in progress.'' 32 The list of current Internet-Drafts can be accessed at 33 . The list of 34 Internet-Draft Shadow Directories can be accessed at 35 . 37 Copyright 2002, The Internet Society. All Rights Reserved. 39 Please see the Copyright section near the end of this document for 40 more information. 42 Abstract 44 This document describes an LDAP (Lightweight Directory Access 45 Protocol) Virtual List View (VLV) operation. The operation allows the 46 client to obtain portion (the view) of an ordered set (the list) of 47 entries visible through a virtual window. The client can reissue the 48 operation with different criteria to obtain a different view of the 49 list. Clients may use this operation to page, scroll, or browse 50 directory content. 52 The VLV operation is defined as a set of LDAP controls which extend 53 the Search operation. The VLV controls may be used in conjunction 54 with a number of other search controls, such as the Server Side 55 Sorting of Search Results (RFC 2891) control. 57 1. Overview 59 A "virtual list" is a graphical user interface (GUI) technique 60 employed where a list containing a large number of entries need to be 61 displayed. A window containing a small number of list entries are 62 visible. This window can be relocated such that another set of list 63 entries are visible. The set of entries visible through the window is 64 the view. 66 The Lightweight Directory Access Protocol (LDAP) [RFC3377] Virtual 67 List View (VLV) operation allows a client to obtain the set of entries 68 of an ordered list visible through a window from a server. The set of 69 entries are selected based on search criteria. In absence of a 70 control specifying a particular order, the order is determined by the 71 server. The position and size of the window is determined by 72 parameters of the VLV request control. 74 The VLV operation is defined as an extended Search operation. The VLV 75 operation is state-less. 77 Appendix A. discusses how a client can use VLV operations to provide a 78 GUI to page, scroll, and browse directory content. 80 1.1. Relationship to other LDAP extensions 82 The VLV operation may be used with 84 - Duplicate Entry Control [DUPENT], 85 - ManageDsaIT Control [RFC3296], 86 - Matched Values Control [MATCHED], 87 - Server-Side Sorting Control [RFC2891], and 88 - Subentries Control [SUBENTRY]. 90 as described in Section 5. The VLV operation may be used with other 91 LDAP extensions as detailed in other documents. 93 This document provides a standardized mechanism for scrolling, paging, 94 and browsing DIT content. It is intended to replace Scrolling View 95 Browsing [SVB] and the the Simple Paged Results Manipulation [RFC2696] 96 control extensions. 98 1.2. Comparison to Scrolling View Browsing 100 This document was originally offered as an alternative to the 101 Scrolling View Browsing (SVB) [SVB] approach. While both SVB and VLV 102 are upon a Virtual View List metaphor, they differ in many ways. This 103 section highlights a few of the differences. 105 SVB was designed to work in static environments. Small DIT changes 106 between related SVB operations can yield astonishing results. For 107 example, an SVB operation intended to page the view down, may jump 108 over entries or an SVB operation intended to scroll a view up can 109 actually return entries which are below the current view. This is 110 because SVB relies on the ordinal position of entries in the list to 111 be stable. 113 VLV addresses this problem by selecting the target entry which the 114 view is centered about by DN. An VLV intended to page down the view, 115 selects the next page based upon the position of a particular entry. 116 Likewise for scrolling. Even where the target entry is modified (and 117 hence now appears next to other entries in the list), the client can, 118 by requesting overlapping entries, determine whether the returned view 119 is adjacent to the previous view or not. Based upon intended result, 120 the client can choose to display this view to the user or request 121 another view centered about other entries in the previous view. 123 SVB provides a mechanism allowing selection of the target entry by its 124 offset from the head of the list, but not the tail of the list. VLV 125 provides selection by offsets from the head or the tail. 127 SVB provides a "type down" selection mechanism limited to the list 128 primary sort key. VLV provides a "type down" selection mechanism 129 which allows selection by all of the sort keys. 131 SVB requires that entries be sorted using the Server-Side Sorting 132 Control [RFC2891]. VLV only requires that the list be ordered by a 133 deterministic algorithm. VLV allows, but does not require, a 134 particular ordering algorithm to be requested. 136 1.3. Terminology and Conventions 138 The term "list" (of entries) refers to an ordered set of entries by a 139 deterministic algorithm. The list may contain both returnable and 140 non-returnable entries. 142 The term "returnable entry" refers to an entry which the server is 143 willing and able to return. A "non-returnable entry" refers to an 144 entry which the server is unwilling or unable to return. 146 The term "target" refers to the entry used to position the window. 148 The term "view" refers to the portion of a list of entries visible 149 through a window. 151 The term "window" refers to the criteria for selecting the portion of 152 the list to be viewed. 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in BCP 14 [RFC2119]. 158 2. Protocol Elements 160 Protocol elements are described using ASN.1 [X.680]. The term 161 "BER-encoded" means the element is to be encoded using the Basic 162 Encoding Rules [X.690] per Section 5.1 of [RFC2251]. 164 2.1. VLV Request Control 166 The VLV Request Control is an LDAPControl [RFC2251] whose controlType 167 is the "IANA-ASSIGNED-OID.1", criticality is True or False (the 168 DEFAULT), and the controlValue, an OCTET STRING, contains a 169 BER-encoded value of the vlvRequestValue data type: 171 target ::= SEQUENCE { 172 tSelect CHOICE { 173 tName [0] LDAPDN, 174 tFraction [1] SEQUENCE { 175 tNumerator INTEGER, 176 -- constrained to (0..tDenominator)) 177 tDenominator INTEGER (1..maxint) 178 }, 179 tOffset [2] INTEGER (0..maxint), 180 tTypeDown [3] SEQUENCE OF AssertionValue 181 -- contains at least one AssertionValue 183 ... 184 }, 185 tReverse BOOLEAN DEFAULT False 186 -- for tTypeDown, tReverse is constrained to False 187 } 189 window ::= SEQUENCE { 190 wOffset INTEGER, 191 wCount INTEGER (0..maxInt) 192 wReverse BOOLEAN DEFAULT False 193 } 195 vlvRequestValue ::= SEQUENCE { 196 COMPONENTS OF target 197 COMPONENTS OF window 198 } 200 The VLV Request Control is applicable to the SearchRequest message. 202 2.2. VLV Target Response Control 204 The VLV Target Response Control is an LDAPControl [RFC2251] whose 205 controlType is the "IANA-ASSIGNED-OID.2", criticality is False (the 206 DEFAULT), and the controlValue is absent. 208 The VLV Target Response Control is applicable to the SearchResultEntry 209 message. 211 2.3. VLV Done Response Control 213 The VLV Done Response Control is an LDAPControl [RFC2251] whose 214 controlType is the "IANA-ASSIGNED-OID.3", criticality is False (the 215 DEFAULT), and the controlValue is absent. 217 The VLV Done Response Control is applicable to the SearchResultDone 218 message. 220 2.4. VLV Result Codes 222 Implementations of this specification SHALL recognize the following 223 additional resultCode [RFC2251] values: 225 vlvTargetInvalid (IANA-ASSIGNED-1) 226 vlvTargetNotFound (IANA-ASSIGNED-2) 227 vlvWindowInvalid (IANA-ASSIGNED-3) 229 3. The VLV Operation 231 The VLV operation is defined as an extension to the Search operation. 232 The operation is initiated by the client sending a VLV request 233 message, a SearchRequest which includes a VLV Request Control. In 234 response to this request, the server returns zero or more 235 SearchResultEntry messages, one of which may include the VLV Target 236 Control. The operation is completed by the server returning a VLV 237 done response message, a SearchResultDone message which includes VLV 238 Response Done Control. 240 No searchResultReference messages are returned in response to a VLV 241 Request. Continuation references are discussed further in Section 242 4.1. 244 In the VLV request message, fields of searchRequest structure specify 245 the list of entries. The searchRequest fields have the same semantics 246 as defined in Section 4.5.1 of [RFC2251]. The fields of the VLV 247 Request Control specify the desired target as well as the window. 249 3.1. Target Selection 251 The target may be select from the list by multiple means. 253 3.1.1. Target Selection by DN 255 The target tName choice allows selection of the target by 256 distinguished name (DN). If the provided LDAPDN is not a valid string 257 representation [RFC2253] of a DN, vlvTargetInvalid is returned. If 258 the entry named cannot be found, is not in the list, or is not 259 returnable, vlvTargetNotFound is returned. 261 When the request is accompanied by a Duplicate Entry control [DUPENT], 262 tReverse=False indicates that first duplicate of the entry in the list 263 is the target and tReverse=True indicates that last duplicate of the 264 entry in the list is the target. If a Duplicate Entry control was not 265 provided, tReverse is ignored. 267 3.1.2. Target Selection by Offset 269 The target tOffset choice selects the target based on ordinal position 270 in the list. When tReverse is False (DEFAULT), a tOffset value of N 271 selects the first returnable entry whose ordinal position is greater 272 than N. When tReverse is True, a tOffset value of N selects the last 273 returnable entry in a list of size M whose ordinal position is less 274 than or equal to the value M-N. For example, in a list of 100 275 entries: 277 selects the first returnable entry; 279 selects the first returnable entry; 281 selects the first returnable entry 282 whose ordinal position is greater than 10; 284 selects the last returnable entry whose 285 ordinal position is less than or equal to 95 (100-5). 287 If the value of tOffset is greater than or equal to the size of the 288 list, vlvTargetInvalid is returned. If no entry meets the criteria, 289 vlvTargetNotFound is returned. 291 3.1.2. Target Selection by Fraction 293 The target tFraction choice selects the target based on proportional 294 position of entries on the list. The target is the first returnable 295 entry whose ordinal position is closest to quantity 0.5 plus product 296 of the size of the list, less one, and the quotient of the value 297 tNumerator divided by the value of tDenominator. That is, the target 298 is the returnable entry of whose ordinal position in a list of N 299 entries is closest to 301 (0.5 + (N - 1) * (tNumerator / tDenominator))). 303 Where the two closest returnable entries are equally close, the entry 304 which appears later in the list is targeted. 306 For a list of any size: 308 selects the first returnable entry; 309 and 310 selects the last returnable entry; 312 For a list of size 100: 313 selects the returnable entry closest 314 to 51 (e.g., the returnable entry closest to the middle); 315 selects the returnable entry closest 316 to 65.49. 318 For a list of size 101: 319 selects the returnable entry closest 320 to 50.5 (e.g., the returnable entry closest to the middle); 321 selects the returnable entry closest 322 to 67.2. 324 If the list is empty or contains no returnable entries, 325 vlvTargetNotFound is returned. If tReverse is True, protocolError is 326 returned. 328 3.1.3. Target Selection by Type Down 330 The target tTypeDown choice selects the target whose based upon "type 331 down" criteria. 333 The first tTypeDown AssertionValue is associated with the first sort 334 key. The second AssertionValue is associated with the second key. 335 And so on. 337 If there are more AssertionValues than keys, protocolError is 338 returned. If there are more keys than AssertionValues, only the keys 339 which have associated AssertionValues are used. 341 If tReverse is True, protocolError is returned. 343 To select the target, the set of returnable entries whose least 344 attribute value for the first key is equal to the first AssertionValue 345 is determined. If the set contains one entry, that entry is the 346 target. If this set is empty, the first returnable greater than the 347 AssertionValue is the target. If none, vlvTargetNotFound is returned. 348 If the set contains multiple entries, additional key and 349 AssertionValue pairs are used in turn as detailed in the next 350 paragraph. If there are no additional pairs, the target is the first 351 entry in the set. 353 Using the next key and AssertionValue, a subset of the set (from the 354 preceding step) whose least attribute value for the key is equal to 355 the AssertionValue is determined. If the set contains one entry, that 356 entry is the target. If this subset is empty, first entry in the set 357 greater than the AssertionValue is the target. If none, the first 358 returnable entry entry greater than the first AssertionValue is the 359 target. In none, vlvTargetNotFound is returned. If the set contains 360 multiple entries, then this step is repeated with the next key and 361 AssertionValue pair. If there are no additional pairs, the target is 362 the first entry in the subset. 364 For example, consider a list sorted by list sorted first by 'sn', then 365 by 'givenName', and then by 'initials' and a target criteria of 366 . First, the set of returnable entries 367 whose least value of 'sn' is "James" is determined. Second, assuming 368 the set is non-empty, the subset of this set whose least value of 369 'givenName' is "J" is determined. If the subset is non-empty, the 370 first entry of the subset is the target (as there are no further key / 371 AssertionValue pairs). If this subset is empty then, the target is 372 the first entry in the set which has a 'givenName' greater than "J". 373 If none, then the target is the first entry in the list which contains 374 a 'sn' value greater than 'James'. 376 3.2. View Selection and Return 378 If wCount is 0, the view is empty and no entries are returned. 379 Otherwise, the window is positioned relative to the target entry to 380 determine the view. 382 The positioning index is the value of wOffset plus the ordinal 383 position of the target entry. If this index is less than 1, the first 384 entry of the list is first entry of the view. If the index is greater 385 than the size of the list, the last entry in the list is the first 386 entry in the view. Otherwise, the entry whose ordinal position in the 387 list is equal to this index is the first entry of the view. 389 If the entry at the positioning index is returnable, it is returned 390 first and wCount is reduced by one. 392 If wReverse=False, the next wCount returnable entries from the 393 position index towards the tail of the list are in the view and are 394 returned in increase ordinal order. 396 If wReverse=True, the next wCount returnable entries from the position 397 index towards the head of the list are in the view and are returned in 398 decreasing ordinal order. 400 If the target entry is within view, it is returned with a Virtual 401 Target Response control. 403 3.3. Done Response Message 405 The VLV Done Response message is returned on completion of the VLV 406 operation. 408 4. Other considerations 410 4.1. Continuation References 412 As indicated above, no searchResultReference messages are returned in 413 response to a VLV Request. 415 Where the content contains references to other servers, the server MAY 416 obtain entries from these others in order to fulfill the VLV request. 417 Otherwise, the server SHALL ignore these references. 419 4.2. Changes to content between VLV operations 421 While individual entries tend to change infrequently, changes to a 422 list of entries is likely change frequently. For example, if the 423 average entry changes once per (8 hour) work day, a list of 28,800 424 entries will change approximately once per second during the work day. 426 The client SHOULD NOT assume the directory content is static. 428 4.3. Changes to content during a VLV operation 430 Server implementations which allows directory content to change (due 431 to other operations) during processing of the VLV operation, need to 432 take special care to ensure the operation behaves in a consistent 433 manner. 435 During the processing of the VLV operation, an entry is modified in a 436 manner which changes in a manner which affects it position in the 437 list. If only the old position is in the view, the server MUST either 438 return the old entry in the old position or not return the entry. If 439 only the new position is in the view, the server MUST either return 440 new entry in the new position or not return the entry. If both 441 positions are in the view, the server MUST either return the old entry 442 in the old position, the new entry in the new position, or not return 443 the entry. 445 If the target entry is modified, then the server MUST select all 446 returned entries based upon the old position of the target entry or 447 select all returned entries based upon the new entry. 449 5. Interaction with Other Controls 451 The VLV operation may be used with 453 - Duplicate Entry Control [DUPENT], 454 - ManageDsaIT Control [RFC3296], 455 - Matched Values Control [MATCHED], 456 - Server-Side Sorting Control [RFC2891], and 457 - Subentries Control [SUBENTRY]. 459 as described below. The VLV operation may be used with other LDAP 460 extensions as detailed in other documents. 462 5.1. Server-Side Sorting Control 464 VLV operations provide a view into an ordered list. When the Server- 465 Side Sorting Control (SSS) [RFC2891] indicates the particular sorting 466 algorithm to be used to determining the order of entries in the list. 467 Where the sorting algorithm allows for two or more entries to be 468 presented in any order, the server MUST choose the order which these 469 entries appear in the list by a deterministic algorithm. 471 That is, if the Sort Control indicates the list is to sorted by their 472 CN values and two or more entries have the same CN value, the server 473 is not free to return the entries in randomly selected order. 475 5.2. Duplicate Entry Control 477 It is often desirable to include an entry which has multiple values 478 for the sort key(s) in the list multiple times, once for each value of 479 a sort key. For example, when constructing a list of entries by 480 ordered by common name (CN), it is often desirable for the entry to 481 appear in the list under each CN value. The Duplicate Entry Control 482 provides a mechanism by which the "client requests that the server 483 return separate entries for each value held in the specified 484 attribute(s)" [DUPENT]. 486 When used with the VLV Operation, the Duplicate Entry Control 487 logically applies to entries before list ordering. That is, each 488 duplicate entry is ordered independently in respect to other entries 489 (duplicates or not) in the list. 491 A particular ordering algorithm may be specified by use of a sorting 492 control. 494 5.3. Matched Values Control 496 The Matched Values control is "used to return a subset of attribute 497 values from an entry, specifically, only those values that match a 498 "values return" filter" [MATCHED]. 500 When used with the VLV Operation, the Matched Values control logically 501 applies to entries before list ordering. That is, entries are to 502 ordered based only upon a subset of attribute values selected by the 503 Matched Values control. Other values are eliminated. 505 Matched Values control SHOULD precede other controls are specified 506 which affect the number and ordering entries in the list. 508 5.4. ManageDsaIT control 510 As when used with other operations, the ManageDsaIT control [RFC3296] 511 causes referral and other special objects to be treated as normal 512 objects with respect to the VLV Operation and other controls. That 513 is, the referral and other special objects appear in the list if they 514 were normal objects. 516 5.5. Subentries control 518 The Subentries control is used with the search operation "to control 519 the visibility of entries and subentries which are within scope" 520 [SUBENTRY]. When used with the VLV Operation, the subentries control 521 and other factors (search scope, filter, etc.) is used to determining 522 whether an entry or subentry in the list is returnable or not. 524 6. Security Considerations 526 Significant resources (CPU, memory, etc.) may be required at the 527 server to process a VLV Operation, especially where the VLV Operation 528 has been extended by Server-Side Sorting, Duplicate Entry, and other 529 controls. Servers SHOULD provide administrative controls to limit the 530 rate and/or kinds of VLV operations which can be submitted by 531 authorized users. 533 A single VLV operation does not directly disclose the size of the 534 list. However, by issuing multiple VLV operations, an authorized 535 client can determine the size of the list. 537 7. IANA Considerations 539 Registration of the following values is requested [RFC3383]. 541 7.1. Object Identifiers 543 It is requested that IANA register upon Standards Action an LDAP 544 Object Identifier in identifying the protocol elements defined in this 545 technical specification. The following registration template is 546 suggested: 548 Subject: Request for LDAP OID Registration 549 Person & email address to contact for further information: 550 Kurt Zeilenga 551 Specification: RFCXXXX 552 Author/Change Controller: IESG 553 Comments: 554 Three delegations will be made under the assigned OID: 556 IANA-ASSIGNED-OID.1 VLV Request Control 557 IANA-ASSIGNED-OID.2 VLV Target Response Control 558 IANA-ASSIGNED-OID.3 VLV Done Response Control 560 7.2. LDAP Protocol Mechanism 562 It is requested that IANA register upon Standards Action the LDAP 563 protocol mechanism described in this document. The following 564 registration template is suggested: 566 Subject: Request for LDAP Protocol Mechanism Registration 567 Object Identifier: IANA-ASSIGNED-OID.1 568 Description: VLV Request Control 569 Person & email address to contact for further information: 570 Kurt Zeilenga 571 Usage: Control 572 Specification: RFCxxxx 573 Author/Change Controller: IESG 574 Comments: none 575 in 2 577 7.3. LDAP Result Codes 579 It is requested that IANA register upon Standards Action the LDAP 580 result codes: 582 vlvTargetInvalid (IANA-ASSIGNED-1) 583 vlvTargetNotFound (IANA-ASSIGNED-2) 584 vlvWindowInvalid (IANA-ASSIGNED-3) 586 The following registration template is suggested: 588 Subject: LDAP Result Code Registration 589 Person & email address to contact for further information: 590 Kurt Zeilenga 591 Result Code Name: vlvTargetInvalid 592 Result Code Name: vlvTargetNotFound 593 Result Code Name: vlvWindowInvalid 594 Specification: RFCXXXX 595 Author/Change Controller: IESG 596 Comments: request consecutive result codes be assigned 598 8. Normative References 600 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 601 Requirement Levels", BCP 14 (also RFC 2119), March 1997. 603 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 604 Protocol (v3)", RFC 2251, December 1997. 606 [RFC2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access 607 Protocol (v3): UTF-8 String Representation of Distinguished 608 Names", RFC 2253, December 1997. 610 [RFC2830] J. Hodges, R. Morgan, and M. Wahl, "Lightweight Directory 611 Access Protocol (v3): Extension for Transport Layer 612 Security", RFC 2830, May 2000. 614 [RFC2891] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for 615 Server Side Sorting of Search Results", RFC 2891, August 616 2000 618 [RFC3296] K. Zeilenga, "Named Subordinate References in Lightweight 619 Directory Access Protocol (LDAP) Directories", RFC 3296, 620 July 2002. 622 [RFC3377] J. Hodges, R. Morgan, "Lightweight Directory Access Protocol 623 (v3): Technical Specification", RFC 3377, September 2002. 625 [DUPENT] J. Sermersheim. "LDAP Control for a Duplicate Entry 626 Representation of Search Results", 627 draft-ietf-ldapext-ldapv3-dupent-xx.txt (a work in 628 progress). 630 [MATCHED] D. Chadwick, "Returning Matched Values with LDAPv3", 631 draft-ietf-ldapext-matchedval-xx.txt (a work in progress). 633 [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) - Specification 634 of Basic Notation", X.680, 1994. 636 [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic, 637 Canonical, and Distinguished Encoding Rules", X.690, 1994. 639 9. Informative References 641 [RFC3383] K. Zeilenga, "IANA Considerations for LDAP", BCP 64 (also 642 RFC 3383), September 2002. 644 [SVB] D. Bozeman, J. Sermersheim, A. Kashi, "LDAP Extensions for 645 Scrolling View Browsing of Search Results", draft-ietf- 646 ldapext-ldapv3-vlv-08.txt (a work in progress). 648 10. Acknowledgment 650 This work benefited from prior work in this area, especially the 651 paging and scrolling work done in IETF ASID and LDAPEXT working 652 groups. 654 This borrows significantly (both concepts and text) from the "LDAP 655 Extensions for Scrolling View Browsing of Search Results" [SVB] 656 Internet-Draft written by Dave Boreham, Jim Sermersheim, and Asaf 657 Kashi. 659 11. Author's Address 661 Kurt D. Zeilenga 662 OpenLDAP Foundation 663 665 Appendix A. Using the VLV Operation 667 This informative appendix discusses how the VLV operation can be used 668 to page, scroll, and browse directory content. 670 For the purposes of this discussion, let's assume we want to implement 671 an address book application which allows the user to page, scroll, and 672 browse address information held in an LDAP-accessible directory system 673 using inetOrgPerson [RFC2798] schema. 675 Say this application has a widget which is capable of displaying 10 676 rows of information. In each row, we'll display the values of 677 'displayName' and 'mail' attributes of an entry. 679 Aside from the usual search parameters (baseObject, scope, filter), we 680 likely also want to sort the entries. So, initially, we'll provide a 681 sort control which requests values be sorted by displayName. 683 A.1. Widget Initialization 685 There are multiple VLV operations which might be used to initialize 686 the widget. To initialize the widget with the first 10 entries of the 687 list, the VLV request can be used. To initialize the widget with 689 the middle 10 entries, the VLV request can be used. 691 To initialize the widget to the last 10 entries, the VLV request 692 can be used. 695 However, as the last 10 entries of in the list may not be returnable, 696 it may be more appropriate to request instead. Note 698 that since wReverse is selected, the last entry is returned first. 700 The widget can also be initialized to the entries surrounding a known 701 DN by sending the request . 704 The widget can also be initialized based upon "typedown" criteria. 705 Typedown is discussed in A.4. 707 A.2. Slider navigation 709 Most list widgets allow based upon proportional positioning of a 710 slider. Our widget reports the slider's position as the percentage 711 the area above the slider position to the total slider area. When it 712 is repositioned, the application can request when percent is less than or equal to 50 and 715 when percent is less than or equal to 50. 717 Because the list may contain non-returnable entries, we reverse the 718 window as we approach the tail of the list. When wReverse is True, 719 the last entry is returned first. 721 A.3. Page navigation 723 Most list widgets provide page up/down controls. 725 When page down is selected, the application can request where last is 727 the name of the entry presently at the bottom of the current widget 728 view. The server will then return a new view in forward order. When 729 inserted into the widget, the target will appear at the top of the 730 current widget view. 732 When page up is selected, the application can request where first is 734 the name of the entry presently at the top of the current view. The 735 server will then return a new view in reverse order with the named 736 entry returned first. When inserted into the widget, the target will 737 appear at the bottom the current widget view. 739 If the page up/down VLV operation returns vlvTargetNotFound, the 740 application can reissue the page up/down VLV operation with the name 741 of the entry nearest the top/bottom of the present widget view. 743 It is noted that when named entry is modified prior to issuing of the 744 VLV operation in a manner which affects its position in the list, the 745 view will follow the named entry. 747 A.4. Type down navigation 749 Type down navigation can be used to navigate the list. 751 The list is sorted by 'displayName'. When the user types in a partial 752 or complete value, the application can use this value to present the 753 10 values at are below the value. 755 So, for example, the user inputs "K", the application can request 756 . 757 Desiring further typedown, the user inputs "Kurt" and the application 758 requests . Etc. 761 Copyright 2002, The Internet Society. All Rights Reserved. 763 This document and translations of it may be copied and furnished to 764 others, and derivative works that comment on or otherwise explain it 765 or assist in its implementation may be prepared, copied, published and 766 distributed, in whole or in part, without restriction of any kind, 767 provided that the above copyright notice and this paragraph are 768 included on all such copies and derivative works. However, this 769 document itself may not be modified in any way, such as by removing 770 the copyright notice or references to the Internet Society or other 771 Internet organizations, except as needed for the purpose of 772 developing Internet standards in which case the procedures for 773 copyrights defined in the Internet Standards process must be followed, 774 or as required to translate it into languages other than English. 776 The limited permissions granted above are perpetual and will not be 777 revoked by the Internet Society or its successors or assigns. 779 This document and the information contained herein is provided on an 780 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET 781 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 782 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 783 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 784 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.