3.1.4.24.2.1 GetListItems

  • Article

The GetListItems element specifies details for the request of the GetListItems operation that the protocol client sends as a request to this protocol server.

 <s:element name="GetListItems">
   <s:complexType>
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="1" name="listName" type="s:string" />
       <s:element name="viewName" type="s:string" minOccurs="0"/>
       <s:element minOccurs="0" maxOccurs="1" name="query">
         <s:complexType mixed="true">
           <s:sequence>
             <s:element name="Query" type="core:CamlQueryRoot"/>
           </s:sequence>
         </s:complexType>
       </s:element>
       <s:element name="viewFields" type="tns:CamlViewFields" minOccurs="0"/>
       <s:element name="rowLimit" type="s:string" minOccurs="0"/>
       <s:element name="queryOptions" type="tns:CamlQueryOptions" minOccurs="0" />
       <s:element name="webID" type="s:string" minOccurs="0"/>
     </s:sequence>
   </s:complexType>
 </s:element>

listName: The GUID, or the list title, of the list from which to retrieve list items. If the specified list is the user information list, the string is set to "UserInfo" or "User Information List".

viewName: The GUID of the view of the list from which to return list items (see [MS-VIEWSS]). If not specified, the default list view is used. The viewFields, rowLimit, and queryOptions parameters, if any are specified, MUST override corresponding attributes of the view used.

query: The query to determine which records from the list are to be returned and the order in which they will be returned. See section 2.2 in [MS-WSSCAML].

viewFields: Specifies which fields of the list item SHOULD be returned. If this is not specified, whether by excluding the element or by including an empty element, the fields defined for the viewName parameter will be used. If a field referenced in a FieldRef element of viewFields has no value filled, this field SHOULD NOT be returned. If the Properties attribute of the ViewFields structure is set to TRUE and the MetaInfo field is referenced in a FieldRef element, the metadata properties related to the list item MUST be returned with the prefix "ows_MetaInfo_".

Example snippet of request for properties:

 <ViewFields Properties="True"><FieldRef Name="MetaInfo" />…</ViewFields>

Example snippet of response:

    <z:row ows_ID='1' ows_MetaInfo_vti_versionhistory='e074e60a01264446a751a5be7a55ed81:2' />

The preceding example shows that a vti_versionhistory property is set on the list item.

Alternatively, specific properties MAY be requested by using the following format, where the name of the specified property is substituted for "PropertyName":

  <ViewFields Properties="True"><FieldRef Name="MetaInfo" Property="PropertyName" />…</ViewFields>

rowLimit: Specifies the maximum number of rows of data to return in the response. If this is not specified, whether by passing an empty element or by excluding the element, the default row limit for the view specified by the viewName parameter is used. Otherwise, this MUST be a 32-bit unsigned integer. The protocol server MUST NOT return more list items than this parameter specifies.

queryOptions: Specifies various options for modifying the query.

webID: The GUID of the site that contains the list. If not specified, the default Web site based on the SOAP request is used. The protocol client SHOULD exclude this parameter from the request.

The following is a sample request that retrieves list items from the list "TestItem" by using the default view, ordered by the identification field. In addition to the service fields that are always returned, the example returns the ID, Attachments, LinkTitle, Num, Text, and FileDirRef fields. The example returns a maximum of 10 rows, dates in UTC format, and a flat view of the list (that is not scoped to a specific folder).

 Content-Type: text/xml; charset=utf-8
 SOAPAction: "http://schemas.microsoft.com/sharepoint/soap/GetListItems"
  
 <?xml version="1.0" encoding="utf-8"?>
 <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body> 
 <GetListItems xmlns="http://schemas.microsoft.com/sharepoint/soap/"> 
 <listName>TestItem</listName>
 <viewName></viewName>
 <query><Query><OrderBy><FieldRef Name="ID"/></OrderBy></Query></query>
                                 <viewFields><ViewFields><FieldRef Name="ID" /><FieldRef Name="Attachments"/><FieldRef Name="LinkTitle"/><FieldRef Name="Num"/><FieldRef Name="Text"/><FieldRef Name="FileDirRef" /></ViewFields></viewFields>
 <rowLimit>10</rowLimit>
 <queryOptions><QueryOptions><DateInUtc>True</DateInUtc><IncludeMandatoryColumns>False</IncludeMandatoryColumns><ViewAttributes Scope="RecursiveAll"/></QueryOptions></queryOptions>
 </GetListItems> 
 </soap:Body>
 </soap:Envelope>