Share via

3.1.4.22.2.1 GetListItemChangesSinceToken

  • Article

The GetListItemChangesSinceToken element specifies details for the request that the protocol client sends to the protocol server to return list items matching certain criteria.

 <s:element name="GetListItemChangesSinceToken">
   <s:complexType>
     <s:sequence>
       <s:element minOccurs="0" maxOccurs="1" name="listName" type="s:string" />
       <s:element name="viewName" type="s:string" minOccurs="0" maxOccurs="1"/>
       <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" maxOccurs="1"/>
       <s:element name="rowLimit" type="s:string" minOccurs="0" maxOccurs="1"/>
       <s:element name="queryOptions" type="tns:CamlQueryOptions" 
                  minOccurs="0" maxOccurs="1" />
       <s:element name="changeToken" type="s:string" minOccurs="0" maxOccurs="1" />
       <s:element name="contains" type="tns:CamlContains" minOccurs="0" maxOccurs="1" />
     </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: Protocol clients SHOULD NOT include this parameter. If specified, the protocol server MUST ignore this parameter if the viewFields parameter is also specified; otherwise, the server MUST only validate that this parameter is both a valid GUID and that the parameter refers to a view of the list.

query: See the description of the query element in section 3.1.4.24.

viewFields: See the description of the viewFields element in section 3.1.4.24.

rowLimit: SHOULD be specified to indicate the maximum number of rows of data to return in the response. If specified, the parameter MUST contain the string representation of an unsigned 32-bit integer. Not specifying a value or specifying a value of zero indicates that all rows SHOULD be retrieved, unless the changeToken parameter is specified. (See description of changeToken parameter for limitations of the rowLimit). The protocol server MUST NOT return more inserted or updated list items than this parameter specifies. Deleted items are not subject to this limitation  because they are returned in the Changes element.

queryOptions: See the description of the queryOptions element in section 3.1.4.24.

If the queryOptions parameter is excluded, the default values that the protocol server MUST use are the following:

  • RecurrenceOrderBy – True

  • ViewAttributes – Scope="RecursiveAll"

  • DateInUtc –True

  • IncludePermissions – True

  • IncludeAttachmentUrls – True

  • IncludeAttachmentVersion – True

  • RecurrencePatternXMLVersion – v3

  • ExpandUserField – True

  • MeetingInstanceID – -1

The default values for RecurrenceOrderBy and RecurrencePatternXMLVersion MUST NOT affect the response if the RecurrenceData field is not part of the list item. Additionally, even when RecurrenceData is part of the list item, the protocol client MUST specify the following viewFields parameter to see the effect of the default values: <ViewFields /> or MUST contain <FieldRef Name="RecurrenceData/> in viewFields.

changeToken: If excluded by the protocol client, all items in the list MUST be returned, subject to the default row limit of the view or the overriding rowLimit parameter. If specified, it MUST be a Changes element with a LastChangeToken attribute that is assigned a string comprising a token returned by a previous call to GetListItemChangesSinceToken (section 3.1.4.22). The response will include changes made to list items after the change token was retrieved, subject to the row limit restrictions just described.

An example of the type of token that MAY be returned by a call to GetListItemChangesSinceToken is as follows:

 <Changes LastChangeToken="1;3;b0c07dce-e4c7-45a9-8b7f-0d5339f69633;633247934080930000;70853"></Changes>

When the change token is excluded, protocol clients MAY page data from the protocol server. In this case, protocol clients MUST exclude the changeToken parameter for each request until the data is fully fetched by using the paging mechanism specified in the ListItemCollectionPositionNext attribute (see section 2.2.4.4).

If the changeToken parameter is specified and the total number of list items that have been inserted or updated is greater than 40, only the first 40 items that changed are returned<69>. The Changes element in the response MUST include the attribute MoreChanges set to "TRUE" to indicate that protocol clients MAY make another call to the GetListItemChangesSinceToken by using the new change token from the most recent response to retrieve subsequent changes.

contains: Specifies a value to search for. This SHOULD NOT be specified when the query parameter is used. If both parameters are specified, contains MUST be ignored by the protocol server.

The following example shows a request that uses the change token extracted from a previous GetListItemChangesSinceTokenResponse (section 3.1.4.22.2.2):

 <?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> 
 <GetListItemChangesSinceToken xmlns="http://schemas.microsoft.com/sharepoint/soap/"> 
 <listName>TestListItem</listName>
 <query><Query><OrderBy><FieldRef Name="ID"/></OrderBy></Query></query>
                                  <viewFields><ViewFields><FieldRef Name="ID" /><FieldRef Name="Title" /></ViewFields></viewFields>
 <rowLimit>10</rowLimit>
 <changeToken> 1;3;e074e60a-0126-4446-a751-a5be7a55ed81;633374187828130000;243</changeToken>
 </GetListItemChangesSinceToken> 
 </soap:Body>
 </soap:Envelope>