2.7.2 Range Specifiers for Requests

The range option for an attribute query is represented using the following XML attributes in the request:


where RANGELOW is the zero-based index of the first attribute value to retrieve, and RANGEHIGH is the zero-based index of the last attribute value to retrieve.

When querying for an attribute, a request can specify a RangeLow XML attribute in addition to a RangeHigh XML attribute to retrieve values between the lower and higher range, inclusively. A SOAP request to retrieve multivalued attributes containing a RangeHigh XML attribute must also contain a RangeLow XML attribute. A SOAP request to retrieve multivalued attributes not containing a RangeHigh attribute specifies a request to retrieve all the values beyond RANGELOW (this is subject to the limit imposed by the server on the maximum number of values that can be returned).

In search queries and results, zero is used for RANGELOW to specify the first entry and the wildcard character (*) is used for RANGEHIGH to specify all remaining entries. If specified, RANGELOW MUST be of type positive integer. If specified, RANGEHIGH MUST be either a positive integer or the wildcard character (*).

Both RangeLow and RangeHigh can be absent if the range retrieval extensions as illustrated in and are not used. Both RangeLow and RangeHigh attributes being absent from a request specifies a request for all values to be returned in that single call. For example, if a distribution list contains 1,000 member values, and if this number is less than the directory service-imposed limit on the maximum values that can be retrieved in a single query (1,500 for instance), all 1,000 values must be returned.

If the list of values is larger than the maximum limit of values the server can return, for example 2,000 member values, the first response contains the member attribute with RangeLow and RangeHigh XML attributes specifying the lower and higher range, respectively, and containing all the member values in this range.

To retrieve the next group of member values in the previous example, the search query can be repeated with a range specification that begins at the attribute number that is one past the RANGEHIGH value that was returned in the previous call. This process can be repeated until the last group of values is retrieved. In the above example, the first call would return member values in the range RangeLow as "0" and RangeHigh as "1,499". To retrieve the remaining values, the search query would request member values with RangeLow = 1,500 and RangeHigh = *, and would be given member values in the range RangeLow as "1,500" and RangeHigh as "2000".

The ADWS protocol set shares these range specifiers as common XML attributes that are used to extend WS-Transfer [WXFR] Get and WS-Enumeration [WSENUM] Enumerate requests, which are described in subsequent sections.

The following table lists examples of how to implement range specifiers.



RangeLow="0" RangeHigh="*"

Retrieve all attribute values.*

RangeLow="0" RangeHigh="500"

Retrieve the 1st to 501st values, inclusive.

RangeLow="2" RangeHigh="3"

Retrieve the 3rd and 4th values.

RangeLow="501" RangeHigh="*"

Retrieve the 502nd and all remaining values.*

(*) This is subject to the limits imposed by the server.<11>

The following sections illustrate extensions to the WS-Transfer [WXFR] and WS-Enumeration [WSENUM] protocols by specifying how requestors could retrieve only a portion of the attribute values through an Enumerate or Get request using the range specifiers defined previously.