Network Working Group C. Weider
Request for Comments: 2696 A. Herron
Category: Informational A. Anantha
Microsoft
T. Howes
Netscape
September 1999
Network Working Group C. Weider
Request for Comments: 2696 A. Herron
Category: Informational A. Anantha
Microsoft
T. Howes
Netscape
September 1999
LDAP Control Extension for Simple Paged Results Manipulation
用于简单分页结果操作的LDAP控件扩展
Status of this Memo
本备忘录的状况
This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.
本备忘录为互联网社区提供信息。它没有规定任何类型的互联网标准。本备忘录的分发不受限制。
Copyright Notice
版权公告
Copyright (C) The Internet Society (1999). All Rights Reserved.
版权所有（C）互联网协会（1999年）。版权所有。
This document describes an LDAPv3 control extension for simple paging of search results. This control extension allows a client to control the rate at which an LDAP server returns the results of an LDAP search operation. This control may be useful when the LDAP client has limited resources and may not be able to process the entire result set from a given LDAP query, or when the LDAP client is connected over a low-bandwidth connection. Other operations on the result set are not defined in this extension. This extension is not designed to provide more sophisticated result set management.
本文档描述了用于搜索结果简单分页的LDAPv3控件扩展。此控制扩展允许客户端控制LDAP服务器返回LDAP搜索操作结果的速率。当LDAP客户端资源有限且无法处理给定LDAP查询的整个结果集时，或者当LDAP客户端通过低带宽连接连接时，此控件可能很有用。此扩展中未定义结果集上的其他操作。此扩展的目的不是提供更复杂的结果集管理。
The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [bradner97].
本文件中使用的关键词“必须”、“应该”和“可能”应按照[bradner97]中所述进行解释。
This control is included in the searchRequest and searchResultDone messages as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The structure of this control is as follows:
此控件包含在searchRequest和SearchResultOne消息中，作为LDAPMessage控件字段的一部分，如[LDAPv3]第4.1.12节所定义。此控件的结构如下所示：
pagedResultsControl ::= SEQUENCE {
controlType 1.2.840.113556.1.4.319,
criticality BOOLEAN DEFAULT FALSE,
controlValue searchControlValue
}
pagedResultsControl ::= SEQUENCE {
controlType 1.2.840.113556.1.4.319,
criticality BOOLEAN DEFAULT FALSE,
controlValue searchControlValue
}
The searchControlValue is an OCTET STRING wrapping the BER-encoded version of the following SEQUENCE:
searchControlValue是一个八位字节字符串，包含以下序列的BER编码版本：
realSearchControlValue ::= SEQUENCE {
size INTEGER (0..maxInt),
-- requested page size from client
-- result set size estimate from server
cookie OCTET STRING
}
realSearchControlValue ::= SEQUENCE {
size INTEGER (0..maxInt),
-- requested page size from client
-- result set size estimate from server
cookie OCTET STRING
}
An LDAP client application that needs to control the rate at which results are returned MAY specify on the searchRequest a pagedResultsControl with size set to the desired page size and cookie set to the zero-length string. The page size specified MAY be greater than zero and less than the sizeLimit value specified in the searchRequest.
需要控制结果返回速率的LDAP客户端应用程序可以在searchRequest上指定pagedResultsControl，其大小设置为所需的页面大小，cookie设置为零长度字符串。指定的页面大小可能大于零且小于searchRequest中指定的sizeLimit值。
If the page size is greater than or equal to the sizeLimit value, the server should ignore the control as the request can be satisfied in a single page. If the server does not support this control, the server MUST return an error of unsupportedCriticalExtension if the client requested it as critical, otherwise the server SHOULD ignore the control. The remainder of this section assumes the server does not ignore the client's pagedResultsControl.
如果页面大小大于或等于sizeLimit值，服务器应该忽略该控件，因为请求可以在单个页面中得到满足。如果服务器不支持此控件，则如果客户端将其请求为关键，则服务器必须返回unsupportedCriticalExtension错误，否则服务器应忽略此控件。本节的其余部分假定服务器不会忽略客户端的pagedResultsControl。
Each time the server returns a set of results to the client when processing a search request containing the pagedResultsControl, the server includes the pagedResultsControl control in the searchResultDone message. In the control returned to the client, the size MAY be set to the server's estimate of the total number of entries in the entire result set. Servers that cannot provide such an estimate MAY set this size to zero (0). The cookie MUST be set to an empty value if there are no more entries to return (i.e., the page of search results returned was the last), or, if there are more entries to return, to an octet string of the server's choosing,used to resume the search.
每当服务器在处理包含pagedResultsControl的搜索请求时向客户端返回一组结果时，服务器都会在SearchResultOne消息中包含pagedResultsControl控件。在返回给客户端的控件中，可以将大小设置为服务器对整个结果集中条目数的估计。无法提供此类估计的服务器可能会将此大小设置为零（0）。如果没有更多的条目要返回（即返回的搜索结果页面是最后一个），或者如果有更多的条目要返回，则必须将cookie设置为空值，设置为服务器选择的用于恢复搜索的八位字节字符串。
The client MUST consider the cookie to be an opaque structure and make no assumptions about its internal organization or value. When the client wants to retrieve more entries for the result set, it MUST
客户端必须考虑Cookie是不透明结构，并且不假设其内部组织或价值。当客户端想要检索结果集的更多条目时，它必须
send to the server a searchRequest with all values identical to the initial request with the exception of the messageID, the cookie, and optionally a modified pageSize. The cookie MUST be the octet string on the last searchResultDone response returned by the server. Returning cookies from previous searchResultDone responses besides the last one is undefined, as the server implementation may restrict cookies from being reused.
向服务器发送一个searchRequest，其所有值与初始请求相同，但messageID、cookie和可选的修改页面大小除外。cookie必须是服务器返回的最后一个SearchResultOne响应上的八位字符串。从以前的SearchResultOne响应返回Cookie（除了最后一个响应）是未定义的，因为服务器实现可能会限制Cookie的重用。
The server will then return the next set of results from the whole result set. This interaction will continue until the client has retrieved all the results, in which case the cookie in the searchResultDone field will be empty, or until the client abandons the search sequence as described below. Once the paged search sequence has been completed, the cookie is no longer valid and MUST NOT be used.
然后，服务器将从整个结果集中返回下一组结果。此交互将继续，直到客户端检索到所有结果，在这种情况下，SearchResultOne字段中的cookie将为空，或者直到客户端放弃搜索序列，如下所述。一旦分页搜索序列完成，cookie将不再有效，并且不得使用。
A sequence of paged search requests is abandoned by the client sending a search request containing a pagedResultsControl with the size set to zero (0) and the cookie set to the last cookie returned by the server. A client MAY use the LDAP Abandon operation to abandon one paged search request in progress, but this is discouraged as it MAY invalidate the client's cookie.
客户端发送包含pagedResultsControl（大小设置为零（0））且cookie设置为服务器返回的最后一个cookie的搜索请求时，会放弃一系列分页搜索请求。客户端可以使用LDAP放弃操作放弃正在进行的一个分页搜索请求，但不鼓励这样做，因为这可能会使客户端的cookie无效。
If, for any reason, the server cannot resume a paged search operation for a client, then it SHOULD return the appropriate error in a searchResultDone entry. If this occurs, both client and server should assume the paged result set is closed and no longer resumable.
如果出于任何原因，服务器无法恢复客户端的分页搜索操作，则应在SearchResultOne条目中返回相应的错误。如果发生这种情况，客户端和服务器都应假定分页结果集已关闭且不再可恢复。
A client may have any number of outstanding search requests pending, any of which may have used the pagedResultsControl. A server implementation which requires a limit on the number of outstanding paged search requests from a given client MAY either return unwillingToPerform when the client attempts to create a new paged search request, or age out an older result set. If the server implementation ages out an older paged search request, it SHOULD return "unwilling to perform" if the client attempts to resume the paged search that was aged out.
客户端可能有任意数量的未决搜索请求，其中任何一个都可能使用了pagedResultsControl。如果服务器实现要求限制来自给定客户端的未完成分页搜索请求的数量，则当客户端尝试创建新的分页搜索请求时，可能会返回不愿意的操作，或者会过时旧的结果集。如果服务器实现使较旧的分页搜索请求过期，则如果客户端尝试恢复已过期的分页搜索，则应返回“不愿意执行”。
A client may safely assume that all entries that satisfy a given search query are returned once and only once during the set of paged search requests/responses necessary to enumerate the entire result set, unless the result set for that query has changed since the searchRequest starting the request/response sequence was processed. In that case, the client may receive a given entry multiple times and/or may not receive all entries matching the given search criteria.
客户机可以安全地假设满足给定搜索查询的所有条目在枚举整个结果集所需的分页搜索请求/响应集期间返回一次且仅返回一次，除非自处理启动请求/响应序列的搜索请求以来，该查询的结果集已更改。在这种情况下，客户端可能多次收到给定条目和/或可能不会收到与给定搜索条件匹配的所有条目。
The following example illustrates the client-server interaction between a client doing a search requesting a page size limit of 3. The entire result set returned by the server contains 5 entries.
下面的示例演示了执行搜索请求页面大小限制为3的客户端之间的客户端-服务器交互。服务器返回的整个结果集包含5个条目。
Lines beginning with "C:" indicate requests sent from client to server. Lines beginning with "S:" indicate responses sent from server to client. Lines beginning with "--" are comments to help explain the example.
以“C：”开头的行表示从客户端发送到服务器的请求。以“S:”开头的行表示从服务器发送到客户端的响应。以“-”开头的行是有助于解释示例的注释。
-- Client sends a search request asking for paged results
-- with a page size of 3.
C: SearchRequest + pagedResultsControl(3,"")
-- Server responds with three entries plus an indication
-- of 5 total entries in the search result and an opaque
-- cooking to be used by the client when retrieving subsequent
-- pages.
S: SearchResultEntry
S: SearchResultEntry
S: SearchResultEntry
S: SearchResultDone + pagedResultsControl(5, "opaque")
-- Client sends an identical search request (except for
-- message id), returning the opaque cooking, asking for
-- the next page.
C: SearchRequest + PagedResultsControl(3, "opaque")
-- Server responds with two entries plus an indication
-- that there are no more entries (null cookie).
S: SearchResultEntry
S: SearchResultEntry
S: SearchResultDone + pagedResultsControl(5,"")
-- Client sends a search request asking for paged results
-- with a page size of 3.
C: SearchRequest + pagedResultsControl(3,"")
-- Server responds with three entries plus an indication
-- of 5 total entries in the search result and an opaque
-- cooking to be used by the client when retrieving subsequent
-- pages.
S: SearchResultEntry
S: SearchResultEntry
S: SearchResultEntry
S: SearchResultDone + pagedResultsControl(5, "opaque")
-- Client sends an identical search request (except for
-- message id), returning the opaque cooking, asking for
-- the next page.
C: SearchRequest + PagedResultsControl(3, "opaque")
-- Server responds with two entries plus an indication
-- that there are no more entries (null cookie).
S: SearchResultEntry
S: SearchResultEntry
S: SearchResultDone + pagedResultsControl(5,"")
For LDAP servers providing a front end to X.500 (93) directories, the paged results control defined in this document may be mapped directly onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The size parameter may be mapped onto pageSize. The cookie parameter may be mapped onto queryReference. The sortKeys and reverse fields in the X.500 PagedResultsRequest are excluded.
对于提供X.500（93）目录前端的LDAP服务器，本文档中定义的分页结果控件可以直接映射到X.511[x500]中定义的X.500（93）PagedResultsRequest。size参数可以映射到pageSize。cookie参数可以映射到queryReference。X.500 PagedResultsRequest中的SortKey和reverse字段被排除在外。
Server implementors should consider the resources used when clients send searches with the simple paged control, to ensure that a client's misuse of this control does not lock out other legitimate operations.
服务器实现者应该考虑当客户端用简单分页控件发送搜索时所使用的资源，以确保客户端对该控件的滥用不会锁定其他合法操作。
Servers implementations may enforce an overriding sizelimit, to prevent the retrieval of large portions of a publically-accessible directory.
服务器实现可以强制执行覆盖sizelimit，以防止检索公共可访问目录的大部分。
Clients can, using this control, determine how many entries match a particular filter, before the entries are returned to the client. This may require special processing in servers which perform access control checks on entries to determine whether the existence of the entry can be disclosed to the client.
客户机可以使用此控件，在将条目返回给客户机之前，确定有多少条目与特定筛选器匹配。这可能需要在服务器中进行特殊处理，这些服务器对条目执行访问控制检查，以确定是否可以向客户端披露条目的存在。
[LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
[LDAPv3]Wahl，M.，Howes，T.和S.Kille，“轻量级目录访问协议（v3）”，RFC 2251，1997年12月。
[Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[Bradner97]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，1997年3月。
Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
Chris Weider微软公司美国华盛顿州雷德蒙微软路1号，邮编：98052
Phone: +1 425 882-8080
EMail: cweider@microsoft.com
Phone: +1 425 882-8080
EMail: cweider@microsoft.com
Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
Andy Herron微软公司美国华盛顿州雷德蒙微软路1号，邮编：98052
Phone: +1 425 882-8080
EMail: andyhe@microsoft.com
Phone: +1 425 882-8080
EMail: andyhe@microsoft.com
Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
Anoop Anantha微软公司美国华盛顿州雷德蒙微软路1号，邮编：98052
Phone: +1 425 882-8080
EMail: anoopa@microsoft.com
Phone: +1 425 882-8080
EMail: anoopa@microsoft.com
Tim Howes Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA
Tim Howes Netscape Communications Corp.美国加利福尼亚州米德尔菲尔德东路山景城501号，邮编94043
Phone: +1 415 937-2600
EMail: howes@netscape.com
Phone: +1 415 937-2600
EMail: howes@netscape.com
Copyright (C) The Internet Society (1999). All Rights Reserved.
版权所有（C）互联网协会（1999年）。版权所有。
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, 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 Standards 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 FITNESS FOR A PARTICULAR PURPOSE.
本文件和其中包含的信息是按“原样”提供的，互联网协会和互联网工程任务组否认所有明示或暗示的保证，包括但不限于任何保证，即使用本文中的信息不会侵犯任何权利，或对适销性或特定用途适用性的任何默示保证。
Acknowledgement
确认
Funding for the RFC Editor function is currently provided by the Internet Society.
RFC编辑功能的资金目前由互联网协会提供。