Lists.GetListItems Method
Returns information about items in the list based on the specified query.
Namespace: [Lists Web service]
Web service reference: http://Site/_vti_bin/Lists.asmx
Syntax
'Declaration
<SoapDocumentMethodAttribute("https://schemas.microsoft.com/sharepoint/soap/GetListItems", RequestNamespace := "https://schemas.microsoft.com/sharepoint/soap/", _
ResponseNamespace := "https://schemas.microsoft.com/sharepoint/soap/", _
Use := SoapBindingUse.Literal, ParameterStyle := SoapParameterStyle.Wrapped)> _
Public Function GetListItems ( _
listName As String, _
viewName As String, _
query As XmlNode, _
viewFields As XmlNode, _
rowLimit As String, _
queryOptions As XmlNode, _
webID As String _
) As XmlNode
'Usage
Dim instance As Lists
Dim listName As String
Dim viewName As String
Dim query As XmlNode
Dim viewFields As XmlNode
Dim rowLimit As String
Dim queryOptions As XmlNode
Dim webID As String
Dim returnValue As XmlNode
returnValue = instance.GetListItems(listName, _
viewName, query, viewFields, rowLimit, _
queryOptions, webID)
[SoapDocumentMethodAttribute("https://schemas.microsoft.com/sharepoint/soap/GetListItems", RequestNamespace = "https://schemas.microsoft.com/sharepoint/soap/",
ResponseNamespace = "https://schemas.microsoft.com/sharepoint/soap/",
Use = SoapBindingUse.Literal, ParameterStyle = SoapParameterStyle.Wrapped)]
public XmlNode GetListItems(
string listName,
string viewName,
XmlNode query,
XmlNode viewFields,
string rowLimit,
XmlNode queryOptions,
string webID
)
Parameters
listName
Type: System.StringA string that contains either the display name or the GUID for the list. It is recommended that you use the GUID, which must be surrounded by curly braces ({}). When querying the UserInfo table, the string contains "UserInfo".
viewName
Type: System.StringA string that contains the GUID for the view surrounded by curly braces ({}), which determines the view to use for the default view attributes represented by the query, viewFields, and rowLimit parameters. If this parameter contains an empty string, the default view is used. If the view GUID 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 are returned in the response.
query
Type: System.Xml.XmlNodeA 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
Type: System.Xml.XmlNodeA 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
Type: System.StringA 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
Type: System.Xml.XmlNodeAn 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. Note, however, that if you do not specify QueryOptions when using the GetListItems method, the date is returned in ISO format.
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 start from the beginning of the list. Client applications should supply the value of a server-supplied bookmark. The server returns 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 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 are 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 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= "https://schemas.microsoft.com/sharepoint/soap/" > <QueryOptions/> </queryOptions>
webID
Type: System.StringOptional. A string containing the GUID of the parent Web site for the list surrounded by curly braces ({}). Setting this parameter to a null reference (Nothing in Visual Basic) means the Web site specified by the Url property of the service will be used, and if the Url property of the service is not specified, the root Web site will be used.
Return Value
Type: System.Xml.XmlNode
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="https://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. You should consider this string internal and not to be modified; modifying it can 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>
Examples
The following code example displays items where a Number field contains a value greater than 5,000 and a DateTime field 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 (Visual C#) or Imports (Visual Basic) directive be included for the System.Xml namespace.
Dim listService As New Web_Reference_Folder.Lists()
listService.Credentials = System.Net.CredentialCache.DefaultCredentials
Dim xmlDoc = New System.Xml.XmlDocument()
Dim ndQuery As XmlNode =
xmlDoc.CreateNode(XmlNodeType.Element, "Query", "")
Dim ndViewFields As XmlNode =
xmlDoc.CreateNode(XmlNodeType.Element, "ViewFields", "")
Dim ndQueryOptions As XmlNode =
xmlDoc.CreateNode(XmlNodeType.Element, "QueryOptions", "")
ndQueryOptions.InnerXml =
"<IncludeMandatoryColumns>FALSE</IncludeMandatoryColumns>" + _
"<DateInUtc>TRUE</DateInUtc>"
ndViewFields.InnerXml =
"<FieldRef Name='Field1'/><FieldRef Name='Field2'/>"
ndQuery.InnerXml =
"<Where><And><Gt><FieldRef Name='Field1'/>" + _
"<Value Type='Number'>5000</Value></Gt><Gt>
<FieldRef Name='Field2'/>" + _
"<Value Type='DateTime'>2003-07-03T00:00:00</Value></Gt></And></Where>"
Try
Dim ndListItems As XmlNode =
listService.GetListItems("List_Name", Nothing, ndQuery, _
ndViewFields, Nothing, ndQueryOptions, Nothing)
MessageBox.Show(ndListItems.OuterXml)
Catch ex As System.Web.Services.Protocols.SoapException
MessageBox.Show("Message:" + ControlChars.Lf + ex.Message +
ControlChars.Lf +
"Detail:" + ControlChars.Lf + ex.Detail.InnerText +
ControlChars.Lf +
"StackTrace:" + ControlChars.Lf + ex.StackTrace)
End Try
Web_Reference_Folder.Lists listService = new Web_Reference_Folder.Lists();
listService.Credentials= System.Net.CredentialCache.DefaultCredentials;
XmlDocument xmlDoc = new System.Xml.XmlDocument();
XmlNode ndQuery = xmlDoc.CreateNode(XmlNodeType.Element,"Query","");
XmlNode ndViewFields =
xmlDoc.CreateNode(XmlNodeType.Element,"ViewFields","");
XmlNode ndQueryOptions =
xmlDoc.CreateNode(XmlNodeType.Element,"QueryOptions","");
ndQueryOptions.InnerXml =
"<IncludeMandatoryColumns>FALSE</IncludeMandatoryColumns>" +
"<DateInUtc>TRUE</DateInUtc>";
ndViewFields.InnerXml = "<FieldRef Name='Field1' />
<FieldRef Name='Field2'/>";
ndQuery.InnerXml = "<Where><And><Gt><FieldRef Name='Field1'/>" +
"<Value Type='Number'>5000</Value></Gt><Gt><FieldRef Name='Field2'/>" +
"<Value Type=
'DateTime'>2003-07-03T00:00:00</Value></Gt></And></Where>";
try
{
XmlNode ndListItems =
listService.GetListItems("List_Name", null, ndQuery,
ndViewFields, null, ndQueryOptions, null);
MessageBox.Show(ndListItems.OuterXml);
}
catch (System.Web.Services.Protocols.SoapException ex)
{
MessageBox.Show("Message:\n" + ex.Message + "\nDetail:\n" +
ex.Detail.InnerText +
"\nStackTrace:\n" + ex.StackTrace);
}