Lists.GetListItemChangesSinceToken Method

Article
07/14/2010

Returns changes made to the list since the date and time specified in the token.

Web Service: ListsWeb Reference: http://<Site>/_vti_bin/Lists.asmx

Syntax

<SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/soap/GetListItemChangesSinceToken", RequestNamespace:="http://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace:="http://schemas.microsoft.com/sharepoint/soap/", Use:=SoapBindingUse.Literal, ParameterStyle:=SoapParameterStyle.Wrapped)> _
Public Function GetListItemChangesSinceToken ( _
    listName As String, _
    viewName As String, _
    query As XmlNode, _
    viewFields As XmlNode, _
    rowLimit As String, _
    queryOptions As XmlNode, _
    changeToken As String, _
    contains As XmlNode _
) As XmlNode

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 changeToken As String
Dim contains As XmlNode
Dim returnValue As XmlNode

returnValue = instance.GetListItemChangesSinceToken(listName, viewName, query, viewFields, rowLimit, queryOptions, changeToken, contains)

[SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/soap/GetListItemChangesSinceToken", RequestNamespace="http://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace="http://schemas.microsoft.com/sharepoint/soap/", Use=SoapBindingUse.Literal, ParameterStyle=SoapParameterStyle.Wrapped)] 
public XmlNode GetListItemChangesSinceToken (
    string listName,
    string viewName,
    XmlNode query,
    XmlNode viewFields,
    string rowLimit,
    XmlNode queryOptions,
    string changeToken,
    XmlNode contains
)

Parameters

listName
A string that contains either the title or the GUID for the list. When querying the UserInfo table, the string contains UserInfo. Using the GUID results in better performance.

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 are 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.

Note

The query parameter is not intended to be used with the contains parameter.

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. If this value is null, the query returns all fields for each item returned.

Note

The GetListItemChangesSinceToken method fails for lists with unique item permissions if the PermMask field is not explicitly requested: <FieldRef Name="PermMask"/>

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.
ExpandUserField	Special rendering for the user field values that makes them include the login name, email, SipAddress, and the title when present. This causes a user field to behave as a multi lookup field. The lookup fields used in the expansion are "Name", "EMail", "SipAddress" and "Title". The values are separated by ,#. Any commas in the lookup field name are encoded as ,,. These values occur in the normal field data for each item. <ExpandUserField>FALSE</ExpandUserField> looks like: ows_Author="1;#Admin AdminName" <ExpandUserField>TRUE</ExpandUserField> Looks like: ows_Author="1;#Admin AdminName,#login\name,#emailaddress,#sipaddress,#Admin AdminName "
ExtraIds	Request extra items to be included on the returned set regardless of whether they changed or not. The common use of ExtraIds is to specify the IDs of the folders you're syncronizing if you were in a doclib and chose "Connect to…" on a folder rather than on the entire doclib. This way you get the folder name and can tell when it is renamed. Note: This should only be used with a change token. This allows a client to sync to one or more folders and detect if any folder above the hierarchy was deleted or renamed. Folder names are not returned unless some changes are done to the list and the query to fetch changed items also uses IDs. Example <ExtraIds>1,4,23</ExtraIds>
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. Like the changeToken, this should never be parsed or constructed.
IncludeAttachmentUrls	Changes the value returned for the Attachments field from a Boolean to a list of full urls separated by ;#.
IncludeAttachmentVersion	Used in conjunction with IncludeAttachmentUrls, IncludeAttachmentVersion also returns the GUID and version number used for conflict detection on update.
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.
IncludePermissions	TRUE to request individual item permissions.
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.
OptimizeFor	The two values supported are: ItemIds FolderUrls ItemIds is the default as long as a query or recurrence order is not requested. Optimizes the SQL query with an ID order. FolderUrls optimizes a sync filtered to the flat contents of one or more folders by optimizing the SQL query with a DirName, LeafName order. <OptimizeFor>ItemIds</OptimizeFor>
RecurrenceOrderBy	A requirement for some calendar programs. For each recurring series, the master item is returned first and then all exceptions. This is a special internal ordering that is applied ahead of any other ordering. Note: RecurrenceOrderBy should not be used unless your program explicitly requires it. If the view has a field of type Recurrence, the list will be ordered by fields of reference type UID, EventType and StartDate in the definition of the recurrence field.
RecurrencePatternXMLVersion	Used to maintain backwards compatibility, RecurrencePatternXMLVersion changes the value of a RecurrenceData field to NOT return <V3RecurrencePattern /> when it contains elements only present in version. Note: Without this tag, recurrence patterns that were not present in Windows SharePoint Services version 2 are sent as <V3RecurrencePattern />. Including this tag means that recurrence patterns new to Windows SharePoint Services 3.0 are sent correctly.
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 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=
      "http://schemas.microsoft.com/sharepoint/soap/" >
   <QueryOptions/>
</queryOptions>

changeToken
A string that contains the change token for the request. For a description of the format that is used in this string, see Overview: Change Tokens, Object Types, and Change Types. If null is passed, all items in the list are returned.

contains
A Contains element that defines custom filtering for the query and that can be assigned to a System.Xml.XmlNode object, as in the following example.
```
<Contains>
   <FieldRef Name="Status"/>
   <Value Type="Text">Complete</Value>
</Contains>
```
This parameter can contain null.

Return Value

An XML fragment in the following form that returns the last change token and item changes and that can be assigned to a System.Xml.XmlNode object:

<listitems MinTimeBetweenSyncs="0" RecommendedTimeBetweenSyncs="180" MaxBulkDocumentSyncSize="500" 
   AlternateUrls="http://MyServer/,http://zinzinzin/" EffectivePermMask="FullMask" 
   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/">
   <Changes LastChangeToken="1;3;b0c07dce-e4c7-45a9-8b7f-0d5339f69633;633247934080930000;70853">
   </Changes>
   <rs:data ItemCount="2">
      <z:row ows_Attachments="0" ows_LinkTitle="MyItem1" ows_MetaInfo="3;#" ows__ModerationStatus="0" 
         ows__Level="1" ows_Title="MyItem1" ows_ID="3" ows_owshiddenversion="2" 
         ows_UniqueId="3;#{9153FDD3-7C00-47E9-9194-956BB20AAA8D}" ows_FSObjType="3;#0" 
         ows_Created_x0020_Date="3;#2007-08-31T21:34:59Z" ows_Created="2007-08-31T21:34:59Z" 
         ows_FileLeafRef="3;#3_.000" ows_FileRef="3;#sites/MyWebSite/Lists/MyList/3_.000" 
         ows_ServerRedirected="0" />
      <z:row ows_Attachments="0" ows_LinkTitle="MyItem2" ows_MetaInfo="5;#" ows__ModerationStatus="0" 
         ows__Level="1" ows_Title="MyItem2" ows_ID="5" ows_owshiddenversion="3" 
         ows_UniqueId="5;#{5BDBB1C0-194D-4878-B716-E397B0C1318C}" ows_FSObjType="5;#0" 
         ows_Created_x0020_Date="5;#2007-08-31T21:43:23Z" ows_Created="2007-08-31T21:43:23Z" 
         ows_FileLeafRef="5;#5_.000" ows_FileRef="5;#sites/MyWebSite/Lists/MyList/5_.000" 
         ows_ServerRedirected="0" />
         ...
   </rs:data>
</listitems>

Remarks

The following table describes the return parameters.

Property	Definition
MinTimeBetweenSyncs	Represents the minimum amount of time between user-initiated or automatic synchronization. The value represents a time in minutes. Note: Clients should respect this value even if the user initiates synchronization manually. That is, if this is set to 5 minutes, clients should only send one request per 5 minutes even if the user repeatedly clicks "send/receive".
RecommendedTimeBetweenSyncs	Represents the recommended minimum amount of time between synchronizations. This should specifically be respected for automatic syncs. Clients should never automatically synchronize more often than this. User-initiated synchronizations can override this interval.
MaxBulkDocumentSyncSize	The total size of content to be synchronized to the client. The default is 500 MB. You get the URL and metadata for each document when you call GetListItemChangesSinceToken, but you then need to do an HTTP GET to retrieve the actual document contents. Setting this value to high may degrade performance.
AlternateUrls	Alternate URLs are listed in the following zone order, delimited by commas: Intranet,Default,Extranet,Internet,Custom
EffectiveBasePermissions	The permissions on the list as returned by SPList.EffectiveBasePermissions.ToString().

Example

The following code example uses the GetListItemChangesSinceToken method to display the current change token that results each time after subsequent updates to a list.

Dim listService As New Web_Reference_Folder.Lists()
listService.Credentials = System.Net.CredentialCache.DefaultCredentials
listService.Url = "http://MyServer/MyWebSite/_vti_bin/Lists.asmx"

Dim getListName As XmlNode = listService.GetList("MyCalendar")
Dim listName As String = getListName.Attributes("Name").Value

Dim getFirstToken As XmlNode = listService.GetListItemChangesSinceToken(listName, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing)
Dim currentToken As String = getFirstToken.ChildNodes(1).Attributes("LastChangeToken").Value

label1.Text = currentToken + ControlChars.Lf

Dim strEditItemTitle As String = "My New Title"
Dim strBatchEdit As String = "<Batch OnError='Continue'><Method ID='0' Cmd='Update'>" + 
    "<Field Name='Title'>" + strEditItemTitle + "</Field>" + 
    "<Field Name='ID'>2</Field>" + 
    "<Field Name='EventDate'>2007-10-11T14:00:00Z</Field>" + 
    "<Field Name='EndDate'>2007-10-12T14:00:00Z</Field>" + 
    "</Method></Batch>"

Dim doc = New System.Xml.XmlDocument()
doc.LoadXml(strBatchEdit)
Dim editUpdates As XmlNode = doc.DocumentElement

Try
    listService.UpdateListItems(listName, editUpdates)
    Catch ex1 As System.Web.Services.Protocols.SoapException
        MessageBox.Show((ex1.Message + ControlChars.Lf + ex1.Detail.InnerText + ControlChars.Lf + ex1.StackTrace))
End Try

Dim getSecondToken As XmlNode = listService.GetListItemChangesSinceToken(listName, Nothing, Nothing, Nothing, Nothing, Nothing, currentToken, Nothing)

currentToken = getSecondToken.ChildNodes(1).Attributes("LastChangeToken").Value
label1.Text += currentToken + ControlChars.Lf

Dim strNewItemTitle As String = "My New Item"

Dim strBatchNew As String = "<Batch OnError='Continue'><Method ID='0' Cmd='New'>" + 
    "<Field Name='ID'>New</Field>" + 
    "<Field Name='Title'>" + strNewItemTitle + "</Field>" + 
    "<Field Name='EventDate'>2007-10-2T14:00:00Z</Field>" + 
    "<Field Name='EndDate'>2007-10-3T14:00:00Z</Field>" + 
    "</Method></Batch>"

doc = New System.Xml.XmlDocument()
doc.LoadXml(strBatchNew)
Dim addUpdates As XmlNode = doc.DocumentElement

Try
    listService.UpdateListItems(listName, addUpdates)
    Catch ex2 As System.Web.Services.Protocols.SoapException
        MessageBox.Show((ex2.Message + ControlChars.Lf + ex2.Detail.InnerText + ControlChars.Lf + ex2.StackTrace))
End Try

Dim getThirdToken As XmlNode = listService.GetListItemChangesSinceToken(listName, Nothing, Nothing, Nothing, Nothing, Nothing, currentToken, Nothing)

currentToken = getThirdToken.ChildNodes(1).Attributes("LastChangeToken").Value
label1.Text += currentToken

Web_Reference_Folder.Lists listService = new Web_Reference_Folder.Lists();
listService.Credentials = System.Net.CredentialCache.DefaultCredentials;
listService.Url = "http://MyServer/MyWebSite/_vti_bin/Lists.asmx";

XmlNode getListName = listService.GetList("MyCalendar");
string listName = getListName.Attributes["Name"].Value;

XmlNode getFirstToken = listService.GetListItemChangesSinceToken(listName, null, null, null, null, null, null, null);
string currentToken = getFirstToken.ChildNodes[1].Attributes["LastChangeToken"].Value;

label1.Text = currentToken + "\n";

string strEditItemTitle = "My New Title";
string strBatchEdit = "<Batch OnError='Continue'><Method ID='0' Cmd='Update'>" +
    "<Field Name='Title'>" + strEditItemTitle + "</Field>" +
    "<Field Name='ID'>2</Field>" +
    "<Field Name='EventDate'>2007-10-11T14:00:00Z</Field>" +
    "<Field Name='EndDate'>2007-10-12T14:00:00Z</Field>" +
    "</Method></Batch>";

XmlDocument doc = new System.Xml.XmlDocument();
doc.LoadXml(strBatchEdit);
XmlNode editUpdates = doc.DocumentElement;

try
{
    listService.UpdateListItems(listName, editUpdates);
}
catch (System.Web.Services.Protocols.SoapException ex1)
{
    MessageBox.Show(ex1.Message + "\n" + ex1.Detail.InnerText + "\n" + ex1.StackTrace);
}

XmlNode getSecondToken = listService.GetListItemChangesSinceToken(listName, null, null, null, null, null, currentToken, null);

currentToken = getSecondToken.ChildNodes[1].Attributes["LastChangeToken"].Value;
label1.Text += currentToken + "\n";

string strNewItemTitle = "My New Item";

string strBatchNew = "<Batch OnError='Continue'><Method ID='0' Cmd='New'>" +
    "<Field Name='ID'>New</Field>" +
    "<Field Name='Title'>" + strNewItemTitle + "</Field>" +
    "<Field Name='EventDate'>2007-10-2T14:00:00Z</Field>" +
    "<Field Name='EndDate'>2007-10-3T14:00:00Z</Field>" +
    "</Method></Batch>";

doc = new System.Xml.XmlDocument();
doc.LoadXml(strBatchNew);
XmlNode addUpdates = doc.DocumentElement;

try
{
    listService.UpdateListItems(listName, addUpdates);
}
catch (System.Web.Services.Protocols.SoapException ex2)
{
    MessageBox.Show(ex2.Message + "\n" + ex2.Detail.InnerText + "\n" + ex2.StackTrace);
}

XmlNode getThirdToken = listService.GetListItemChangesSinceToken(listName, null, null, null, null, null, currentToken, null);

currentToken = getThirdToken.ChildNodes[1].Attributes["LastChangeToken"].Value;
label1.Text += currentToken;

Lists.GetListItemChangesSinceToken Method

Syntax

Parameters

Return Value

Remarks

Example

See Also

Reference

Additional resources