GetListItems Method

  • Article

The GetListItems method of the Lists service returns information about items in the list based on the specified query.

Parameters

listName   A string that contains either the title or the GUID for the list. When querying the UserInfo table, the string contains "UserInfo".

viewName   A string that contains the GUID for the view, which determines the view to use for the default view attributes represented by the query, viewFields, and rowLimit parameters. If this argument is not supplied, the default view is assumed. If it is supplied, the value of the query, viewFields, or rowLimit parameter overrides the equivalent setting within the view. For example, if the view specified by the viewFields parameter has a row limit of 100 rows but the rowLimit parameter contains 1000, then 1,000 rows will be returned in the response.

query   A Query element containing the query that determines which records are returned and in what order and that can be assigned to a System.Xml.XmlNode object, as in the following example:

<Query>
   <Where>
      <Lt>
         <FieldRef Name="ID" />
         <Value Type="Counter">3</Value>
      </Lt>
   </Where>
</Query>

If supplied, the value of this parameter overrides either the query within the view specified by the viewName parameter or the query within the default view for the list.

viewFields   A ViewFields element that specifies which fields to return in the query and in what order, and that can be assigned to a System.Xml.XmlNode object, as in the following example:

<ViewFields>
   <FieldRef Name="ID" />
   <FieldRef Name="Title" />
</ViewFields>

If supplied, the value of this parameter overrides the view fields within the view specified by the viewName parameter or the view fields in the default view for the list.

rowLimit   A string that specifies the number of items, or rows, to display on a page before paging begins. If supplied, the value of this parameter overrides the row limit set in the view specified by the viewName parameter or the row limit set in the default view for the list.

queryOptions   An XML fragment in the following form that contains separate nodes for the various properties of the SPQuery object and that can be assigned to a System.Xml.XmlNode object:

<QueryOptions>
   <IncludeMandatoryColumns>FALSE</IncludeMandatoryColumns>
   <DateInUtc>TRUE</DateInUtc>
</QueryOptions>

The following table shows the elements that can be used in the Collaborative Application Markup Language (CAML) fragment passed through the queryOptions parameter.

Element Description
DateInUtc TRUE to return dates in Coordinated Universal Time (UTC) format. FALSE to return dates in ISO format. This element is optional, and its default value is TRUE.
Folder Specifies a URL used to filter document library items for items in the specified folder. This element is optional, and its default value is an empty string.
Paging A string that contains data needed to support paging, including a ListItemCollectionPositionNext attribute. If left empty, the list items returned will start from the beginning of the list. Client applications should supply the value of a server-supplied bookmark. The server will return the next page of data based on the bookmark supplied. This element is optional, and its default value is an empty string.
IncludeMandatoryColumns TRUE to specify that mandatory system columns be returned in addition to the fields specified by the viewFields parameter (for example, owsHiddenVersion, dependent fields, and required fields). This element is optional, and its default value is TRUE.
MeetingInstanceID An integer value where a positive number represents a specific meeting instance. Negative numbers have the following meanings: -3 = UnSpecified, -2 = AllWithSeries, -1 = AllButSeries, 0 = Series. This element is optional, and its default value is -1. Negative values correspond to values of the Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance enumeration.
ViewAttributes A string representing all the attributes returned as part of the View element when retrieving a view through the GetView method. This element is optional, and its default value is empty. If a viewName parameter is supplied, the view attributes from the persisted view will be used. When this argument is supplied, it overrides any view attributes that can be retrieved from the persisted view specified by the viewName parameter. This element is optional and its default value is an empty string. To return all the documents in a library, the ViewAttributes element is used as follows: <ViewAttributes Scope="Recursive" />.

To pass an empty value for this parameter, include an empty QueryOptions element as follows:

<queryOptions xmlns:SOAPSDK9="http://schemas.microsoft.com/sharepoint/soap/" >
   <QueryOptions/>
</queryOptions>

Return Value

An XML fragment in the following form that contains information about the list items and that can be assigned to a System.Xml.XmlNode object:

<listitems xmlns:s="uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882"
   xmlns:dt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882"
   xmlns:rs="urn:schemas-microsoft-com:rowset" xmlns:z="#RowsetSchema"
   xmlns="http://schemas.microsoft.com/sharepoint/soap/">
   <rs:data ItemCount="4">
      <z:row ows_Number_Field="6555.00000000000" ows_Created="2003-06-18T03:41:09Z"
         ows_ID="3" ows_owshiddenversion="3" />
      <z:row ows_Number_Field="78905456.0000000" ows_Created="2003-06-18T17:15:58Z"
         ows_ID="4" ows_owshiddenversion="2" />
         .
         .
         .
   </rs:data>
</listitems>

Remarks

The GetListItems method supports server-side paging. The XML data returned by this method includes a ListItemCollectionPositionNext attribute inside the rs:Data element that contains the information to support paging. This string contains data for the fields in the sort and for other items needed for paging. This string should be considered internal, and modifying it may produce unexpected results. The following example shows the form of this return value when paging is supported:

<rs:Data ListItemCollectionPositionNext=" Paged=TRUE&p_ID=100&View=%7bC68F4A6A%2d9AFD%2d406C%2dB624%2d2CF8D729901E%7d&PageFirstRow=101" Count=1000 >
   <z:row ows_FirstName="Nancy" ows_LastName="Name" ….. />
   .
   .
   .
</rs:Data>

To get the next page of data, the queryOption parameter is used, as shown in the following example:

<QueryOptions>
  <Paging ListItemCollectionPositionNext=" Paged=TRUE&p_ID=100&View=%7bC68F4A6A%2d9AFD%2d406C%2dB624%2d2CF8D729901E%7d&PageFirstRow=101" />
</QueryOptions>

Example

The following code example displays items where a Number field contains a value greater than 5,000 and a DateTime contains a value greater than a specified date. The example uses an XmlDocument object to create XmlNode objects for parameters.

This example requires that a using (C#) or Imports (Visual Basic .NET) directive be included for the System.Xml namespace.

Requirements

Platforms: Microsoft Windows Server 2003

Web Reference: http://Server_Name/[sites/][Site_Name/]_vti_bin/Lists.asmx