3.1.4.9 GetListItems

  • Article

The GetListItems operation is used to retrieve details of all list items satisfying certain criteria.

The WSDL schema for the GetListItems operation is as follows.

 <wsdl:operation name="GetListItems">
     <wsdl:input message="GetListItemsSoapIn" />
     <wsdl:output message="GetListItemsSoapOut" />
 </wsdl:operation>

The protocol client sends a GetListItemsSoapIn request message, and the protocol server responds with a GetListItemsSoapOut response message, as follows.

The protocol client specifies the following inputs in the GetListItems element of the GetListItemsSoapIn message:

  • The list identifier.

  • The query, which defines the selection criteria and the ordering of list items in the result.

  • The maximum number of list items to be included into the result.

The protocol server responds by sending a GetListItemsSoapOut message, which consists of a single GetListItemsResponse element. This GetListItemsResponse element contains a single GetListItemsResult element. The value of this GetListItemsResult element MUST be a well-formed XML string in ADO Persistence format, as defined in [MS-PRSTFR], (see also section 8 with one row for each list item that matches the selection criteria).

The protocol client limits the number of list items to be returned by the uRowLimit parameter of the GetListItems element. This uRowLimit parameter has the same meaning as the ANSI-SQL top clause.

To achieve pagination, that is, to be able to sequentially retrieve a large number of list Items by fixed-size chunks, the protocol client MUST include the Greater Than (Gt) predicate on some field (see section 3.1.4.9.3.1). The protocol client can optionally include that field in the OrderBy clause (see section 3.1.4.9.3.2), and modify the Gt criterion in each subsequent call using the maximum field value returned by the previous call. The ID field is a good candidate for pagination because it has well-known minimum value of 1, hence the protocol client can specify the criterion ID is greater than zero to start the pagination.

In the response, row attribute names are not the same as field names prescribed by the schema returned by GetList. To relate row attributes to field names, the protocol client has to look up XDR schema of the response, and then look up the schema returned by GetList, as specified in section 3.1.4.7.

The following example shows how the protocol client can look up the field names using the XDR schema of the response.

Assume that the protocol client performed the GetListItems operation and has obtained a response row with attribute, ows_ContentTypeId.

 <z:row  
     ows_ContentTypeId='0x010007CCE586A00F8F408754CA2BA1A39C02'
 <!-- other attributes … -->

The XDR schema associates ows_ContentTypeId with the underlying rs:name Content Type ID. This is actually the title, rather than the name:

             <s:AttributeType  name='ows_ContentTypeId'
                               rs:name='Content Type ID'
                               rs:number='1'>
                 <s:datatype  dt:type='int'
                              dt:maxLength='512'>
                 </s:datatype>
             </s:AttributeType>

To get the valid name of the field, the protocol client has to look up the schema returned by GetList, seeking for the title "Content Type ID".

                 <_sProperty >
                     <Name >ContentTypeId</Name>
                     <Title >Content Type ID</Title>
                     <Type >ContentTypeId</Type>
                 </_sProperty>

The Name ContentTypeId is indeed the name to be used in Where and OrderBy clauses, and to be used for answer interpretation.