home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldapv3-simplepaged-01.txt < prev    next >
Text File  |  1997-03-27  |  9KB  |  233 lines
  1.  
  2. Network Working Group                   Chris Weider, Microsoft
  3. INTERNET DRAFT                                  Andy Herron, Microsoft
  4.                                                    Tim Howes, Netscape
  5.                                                         March, 1997
  6.  
  7. LDAP Control Extension for Simple Paged Results Manipulation
  8.  
  9. draft-ietf-asid-ldapv3-simple-paged-01.txt
  10.  
  11. 0. Status of this Memo
  12.  
  13. This document is an Internet-Draft.  Internet-Drafts are working
  14. documents of the Internet Engineering Task Force (IETF), its
  15. areas, and its working groups.  Note that other groups may also
  16. distribute working documents as Internet-Drafts.
  17.  
  18. Internet-Drafts are draft documents valid for a maximum of six
  19. months and may be updated, replaced, or obsoleted by other
  20. documents at any time.  It is inappropriate to use Internet-
  21. Drafts as reference material or to cite them other than as
  22. ``work in progress.''
  23.  
  24. To learn the current status of any Internet-Draft, please check
  25. the ``1id-abstracts.txt'' listing contained in the Internet-
  26. Drafts Shadow Directories on ds.internic.net (US East Coast),
  27. nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or
  28. munnari.oz.au (Pacific Rim).
  29.  
  30. This draft expires September 26, 1997.
  31.  
  32. 1. Abstract
  33.  
  34. This document describes an LDAPv3 control extension for simple paging
  35. of search results. This control extension allows a client to control
  36. the rate at which an LDAP server returns the results of an LDAP search
  37. operation. This control may be useful when the LDAP client has limited
  38. resources and may not be able to process the entire result set from a
  39. given LDAP query, or when the LDAP client is connected over a
  40. low-bandwidth connection. Other operations on the result set are not
  41. defined in this extension. This extension is not designed to provide
  42. more sophisticated result set management.
  43.  
  44. The key words "MUST", "SHOULD", and "MAY" used in this document are to
  45. be interpreted as described in [bradner97].
  46.  
  47. 2. The Control
  48.  
  49. This control is included in the searchRequest and searchResultDone
  50. messages as part of the controls field of the LDAPMessage, as defined
  51. in Section 4.1.12 of [LDAPv3]. The structure of this control is as
  52. follows:
  53.  
  54. pagedResultsControl ::= SEQUENCE {
  55.         controlType     1.2.840.113556.1.4.319,
  56.         criticality     BOOLEAN DEFAULT FALSE,
  57.         controlValue    searchControlValue
  58. }
  59.  
  60. The searchControlValue is an OCTET STRING wrapping the BER-encoded
  61. version of the following SEQUENCE:
  62.  
  63. realSearchControlValue ::= SEQUENCE {
  64.         size            INTEGER (0..maxInt),
  65.                 -- requested page size from client
  66.                 -- result set size estimate from server
  67.         cookie          OCTET STRING
  68. }
  69.  
  70. 3. Client-Server Interaction
  71.  
  72. An LDAP client application that needs to control the rate at which
  73. results are returned MAY specify on the searchRequest a
  74. pagedResultsControl with size set to the desired page size and cookie
  75. set to the zero-length string. The page size specified MAY be greater
  76. than zero and less than the sizeLimit value specified in the
  77. searchRequest.
  78.  
  79. If the page size is greater than or equal to the sizeLimit value,
  80. the server should ignore the control as the request can
  81. be satisfied in a single page. If the server does not support this
  82. control, the server MUST return an error of
  83. unsupportedCriticalExtension if the client requested it as critical,
  84. otherwise the server SHOULD ignore the control. The remainder of this
  85. section assumes the server does not ignore the client's
  86. pagedResultsControl.
  87.  
  88. Each time the server returns a set of results to the client when
  89. processing a search request containing the pagedResultsControl, the
  90. server includes the pagedResultsControl control in the searchResultDone
  91. message. In the control returned to the client, the size MAY be set to
  92. the server's estimate of the total number of entries in the entire
  93. result set. Servers that cannot provide such an estimate MAY set this
  94. size to zero (0).  The cookie MUST be set to an empty value if there
  95. are no more entries to return (i.e., the page of search results
  96. returned was the last), or, if there are more entries to return,
  97. to an octet string of the server's choosing,used to resume the search.
  98.  
  99. The client MUST consider the cookie to be an opaque structure and make
  100. no assumptions about its internal organization or value. When the
  101. client wants to retrieve more entries for the result set, it MUST send
  102. to the server a searchRequest with all values identical to the initial
  103. request with the exception of the messageID, the cookie, and optionally
  104. a modified pageSize. The cookie MUST be the octet string on the last
  105. searchResultDone response returned by the server. Returning cookies
  106. from previous searchResultDone responses besides the last one is
  107. undefined, as the server implementation may restrict cookies from being
  108. reused.
  109.  
  110. The server will then return the next set of results from the whole
  111. result set. This interaction will continue until the client has
  112. retrieved all the results, in which case the cookie in the
  113. searchResultDone field will be empty, or until the client abandons the
  114. search sequence as described below. Once the paged search sequence
  115. has been completed, the cookie is no longer valid and MUST NOT be
  116. used.
  117.  
  118. A sequence of paged search requests is abandoned by the client sending
  119. a search request containing a pagedResultsControl with the size set to
  120. zero (0) and the cookie set to the last cookie returned by the server.
  121. A client MAY use the LDAP Abandon operation to abandon one paged search
  122. request in progress, but this is discouraged as it MAY invalidate the
  123. client's cookie.
  124.  
  125. If, for any reason, the server cannot resume a paged search operation
  126. for a client, then it SHOULD return the appropriate error in a
  127. searchResultDone entry. If this occurs, both client and server should
  128. assume the paged result set is closed and no longer resumable.
  129.  
  130. A client may have any number of outstanding search requests pending,
  131. any of which may have used the pagedResultsControl.  A server
  132. implementation which requires a limit on the number of outstanding
  133. paged search requests from a given client MAY either return
  134. unwillingToPerform when the client attempts to create a new paged
  135. search request, or age out an older result set.  If the server
  136. implementation ages out an older paged search request, it SHOULD return
  137. "unwilling to perform" if the client attempts to resume the paged search
  138. that
  139. was aged out.
  140.  
  141. A client may safely assume that all entries that satisfy a given search
  142. query are returned once and only once during the set of paged search
  143. requests/responses necessary to enumerate the entire result set, unless
  144. the result set for that query has changed since the searchRequest
  145. starting the request/response sequence was processed. In that case, the
  146. client may receive a given entry multiple times and/or may not receive
  147. all entries matching the given search criteria.
  148.  
  149. 4. Example
  150.  
  151. The following example illustrates the client-server interaction between
  152. a client doing a search requesting a page size limit of 3.  The entire
  153. result set returned by the server contains 5 entries.
  154.  
  155. Lines beginning with "C:" indicate requests sent from client to
  156. server. Lines beginning with "S:" indicate responses sent from
  157. server to client. Lines beginning with "--" are comments to
  158. help explain the example.
  159.  
  160. -- Client sends a search request asking for paged results
  161. -- with a page size of 3.
  162. C: SearchRequest + pagedResultsControl(3,"")
  163. -- Server responds with three entries plus an indication
  164. -- of 5 total entries in the search result and an opaque
  165. -- cooking to be used by the client when retrieving subsequent
  166. -- pages.
  167. S: SearchResultEntry
  168. S: SearchResultEntry
  169. S: SearchResultEntry
  170. S: SearchResultDone + pagedResultsControl(5, "opaque")
  171. -- Client sends an identical search request (except for
  172. -- message id), returning the opaque cooking, asking for
  173. -- the next page.
  174. C: SearchRequest + PagedResultsControl(3, "opaque")
  175. -- Server responds with two entries plus an indication
  176. -- that there are no more entries (null cookie).
  177. S: SearchResultEntry
  178. S: SearchResultEntry
  179. S: SearchResultDone + pagedResultsControl(5,"")
  180.  
  181. 5. Relationship to X.500
  182.  
  183. For LDAP servers providing a front end to X.500 (93) directories,
  184. the paged results control defined in this document may be
  185. mapped directly onto the X.500 (93) PagedResultsRequest defined
  186. in X.511 [x500]. The size parameter may be mapped onto pageSize.
  187. The cookie parameter may be mapped onto queryReference.
  188. The sortKeys and reverse fields in the X.500 PagedResultsRequest
  189. are excluded.
  190.  
  191. 6. Security Considerations
  192.  
  193. Security considerations are not discussed in this document.
  194.  
  195. 7. References
  196.  [LDAPv3]
  197. Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Protocol
  198. (v3)", Internet Draft, February, 1997. Available as
  199. draft-ietf-asid-ldapv3-protocol-04.txt.
  200.  
  201.  [Bradner97]
  202. Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
  203. Levels",
  204. Internet Draft, January, 1997. Available as
  205. draft-bradner-key-words-03.txt.
  206.  
  207. 8. Author's Address
  208.  
  209. Chris Weider
  210. Microsoft Corp.
  211. 1 Microsoft Way
  212. Redmond, WA 98052
  213. USA
  214. cweider@microsoft.com
  215. +1 206 882-8080
  216.  
  217. Andy Herron
  218. Microsoft Corp.
  219. 1 Microsoft Way
  220. Redmond, WA 98052
  221. USA
  222. andyhe@microsoft.com
  223. +1 206 882-8080
  224.  
  225. Tim Howes
  226. Netscape Communications Corp.
  227. 501 E. Middlefield Road
  228. Mountain View, CA 94043
  229. USA
  230. howes@netscape.com
  231. +1 415 937-2600
  232.  
  233.