| |
Request Control |
|
|
Subject: Request Control
Author: SteveHB
In response to: Client-Server Interaction
Posted on: 03/04/2009 07:57:49 PM
This control is included in the SearchRequest message as part of the controls field of the LDAPMessage. The controlType is set to "2.16.840.1.113730.3.4.9". If this control is included in a SearchRequest message, a Server Side Sorting request control [SSS] MUST also be present in the message.
The controlValue, an OCTET STRING, is the BER-encoding of the following SEQUENCE:
VirtualListViewRequest ::= SEQUENCE {
beforeCount INTEGER (0..maxInt),
afterCount INTEGER (0..maxInt),
target CHOICE {
byOffset [0] SEQUENCE {
offset INTEGER (1 .. 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. greaterThanOrEqual is a matching rule assertion value defined in [LDAPPROT]. The assertion value is encoded according to the ORDERING matching rule for the attributeDescription in the sort control [SSS]. 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. contextID contains the value of the most recently received contextID field from a VirtualListViewResponse control for the same list view. If the contextID is not known because no contextID has been sent by the server in a VirtualListViewResponse control, it SHALL be omitted. If the server receives a contextID that is invalid, it SHALL fail the search operation and indicate the failure with a protocolError (3) value in the virtualListViewResult field of the VirtualListViewResponse. The contextID provides state information between the client and server. This state information is used by the server to ensure continuity contiguous virtual list requests. When a server receives a VirtualListViewRequest control that includes a contextID, it SHALL determine whether the client has sent a contiguous virtual list request and SHALL provide contiguous entries if possible. If a valid contextID is sent, and the server is unable to determine whether contiguous data is requested, or is unable to provide requested contiguous data, it SHALL fail the search operation and indicate the failure with an unwillingToPerform (53) value in the virtualListViewResult field of the VirtualListViewResponse. contextID values have no validity outside the connection and query with which they were received. A client MUST NOT submit a contextID which it received from a different connection, a different query, or a different server.
>
> On 03/04/2009 07:49:09 PM SteveHB wrote:
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 ordered result set, centered around a particular target entry. Henceforth, in the interests of brevity, the ordered 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 element has special significance for "typedown". The Virtual List View control acts upon a set of ordered entries and this order must be repeatable for all subsequent virtual list requests. The server-side sorting control is intended to aid in this ordering, but other mechanisms may need to be employed to produce a repeatable order -- especially for entries that don't have a value of the sort key.
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 content count, the location within the list corresponding to the target entry, any error codes, and optionally a context identifier.
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 estimate as to the number of entries in the list (content count) to the 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 content 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 transmitted become the actual server list offsets. The following special cases exist when the client is specifying the offset and content count:
- an offset of one and a content count of non-one (Ci = 1, Cc != 1)
indicates that the target is the first entry in the list.
- equivalent values (Ci = Cc) indicate that the target is the last
entry in the list.
- a content count of zero (Cc = 0, Ci != 0) means the client has no
idea what the content count is, the server MUST use its own
content count estimate in place of the client's.
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 arithmetic. 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 target 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 contextID MAY be returned to clients. A client receiving a contextID MUST return it unchanged or not return it at all, in a subsequent request which relates to the same list. The purpose of this interaction is to maintain state information between the client and server.
References:
|
|
|
|
