GetListItemChangesSinceToken Request and Response

Applies to: SharePoint Foundation 2010

The most efficient way to synchronize third-party clients with Microsoft SharePoint Foundation 2010 is to download only those items that have changed since the last synchronization occurred. You can do this in SharePoint Foundation 2010 by calling the GetListItemChangesSinceToken Web method.

GetListItem returns all of the items from a list. GetListItem does not include any method to get only those items that have changed. Refer to How to: Return List Items for an example of returning items from a list.

The GetListItemChangesSinceToken method allows clients to track changes on a list. Changes, including deleted items, are returned along with a token that represents the moment in time when those changes were requested. By including this token when you call GetListItemChangesSinceToken, the server looks for only those changes that have occurred since the token was generated. Sending a GetListItemChangesSinceToken request without including a token returns the list schema, the full list contents and a token.

Request and Response Objects

Request and response objects represent information coming into the Web server from the browser and information going out from the server to the browser. The request object is called the input object and the response object is called the output object.

Request Objects

GetListItemChangesSinceToken takes the following parameters:

Table 1: Request Parameters

Element	Description
changeToken	A token used to discover changes that have occurred since the last call. This token should never be parsed or constructed, as its format may change in the future.
contains	A CAML filter that is applied to the query results. This is the "Where" clause in a SPQuery. Note Do not use with the query element.
listName	A string that contains either the display name of the list or the list identifier (ID), which is expressed as a GUID. For better performance, it is recommended that you use the GUID, which must be surrounded by curly braces ({}).
query	A query element containing the query that determines which records are returned and in what order. Collaborative Application Markup Language (CAML) query similar to the CAML query used in GetListItems and SPQuery. For more information, see GetListItems and SPQuery in the SharePoint Foundation SDK. Note Not intended to be used with the contains parameter.
queryOptions	An XML fragment that contains separate nodes for the various properties of the SPQuery object.
rowLimit	A string that specifies the number of items, or rows, to display on a page. 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. The rowLimit is the maximum number of values that will be returned. This tag is used for paging.
viewFields	Specifies which fields to return in the query and in what order. <ViewFields /> returns all fields in the list. A Properties=TRUE attribute separates the MetaInfo field into its separate, decoded properties.
viewName	A string that contains the GUID for the view, which determines the default view for attributes that are 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 1,000, then 1,000 rows are returned in the response.

Query Options Parameter

The queryOptions element can contain a variety of tags which modify the query. For Boolean options the default is FALSE. You must enter a value of TRUE (in all capital letters) to enable a Boolean option.

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

Table 2: Available Query Option Tags

Element	Description
< DateInUtc>	Date fields are returned in Coordinated Universal Time (UTC) format and zone. UTC is the internationally recognized name for Greenwich Mean Time (GMT) and is expressed in a format specified by the International Organization for Standardization (ISO), specifically ISO6801, as follows: 2006-10-04T10:00:00Z Standard format is expressed in local (server) time zone, as shown above, but with the T and the Z replaced by spaces.
<ExpandUserField>	Special rendering for the user field values that makes them include the login name, e-mail, SipAddress, and the title, when present. This causes a user field to behave as a multilookup 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,,. The following values occur in the normal field data for each item. <ExpandUserField>FALSE</ExpandUserField> looks like: ows_Author="1;#Admin AdminName" and <ExpandUserField>TRUE</ExpandUserField> Looks like: ows_Author="1;#Admin AdminName,#login\name,#email@address,#sip@address,#Admin AdminName "
<ExtraIds>1,4,23</ExtraIds>	Used to include extra items on the returned set, regardless of whether they have changed or not. ExtraIds are commonly used to specify the IDs of the folders that you are synchronizing to when you are in a document library and chose "connect to…" and then select a particular folder. Rather than returning the entire document library, you get the specific folder name. The client can detect when any folder in the hierarchy has been deleted or renamed. Note This tag should only be used with a change token. Folder names are not returned unless some changes to the list have been completed and the query to fetch changed items also uses IDs.
<Folder>	Set the root folder scope of the view. This is a server-relative URL. <Folder>Shared Documents/foldername</Folder>
<IncludeAttachmentUrls>	Changes the value that is returned for the Attachments field from a Boolean value to a list of full URLs, separated by ;#
<IncludeAttachmentVersion>	Used in conjunction with IncludeAttachmentUrls, this tag returns the GUID and version number used for conflict detection when an update is verified.
<IncludeMandatoryColumns>	Ensures that fields defined as required are included, even if not specified in the viewFields. This option may be misleading because SharePoint Foundation actually has a separate set of mandatory fields that are always returned independently of this option.
<IncludePermissions>	One method that a client can use to request individual item permissions. 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>	Supported values include: ItemIds FolderUrls ItemIds is the default value as long as a query or recurrence order is not requested. This tag optimizes your SQL Server query with an ID order. FolderUrls optimizes a synchronization that is filtered to the flat contents of one or more folders, by optimizing the SQL Server query with a DirName, LeafName order. <OptimizeFor>ItemIds</OptimizeFor>
<Paging ListItemCollectionPositionNext="X" />	X is a token that is used to determine the page of items to return. Like the changeToken value, this token should never be parsed or constructed.
<RecurrenceOrderBy>	This is 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 before any other ordering. Note This option should not be used unless your program explicitly requires it. If the view has a field of type Recurrence, the list is ordered by fields of reference type unique identifiers (UID), and includes EventType and StartDate in the definition of the recurrence field.
<RecurrencePatternXMLVersion>	Used to maintain backward-compatibility. RecurrencePatternXMLVersion changes the value of a RecurrenceData field to not return <V3RecurrencePattern /> Including this tag means that recurrence patterns in SharePoint Foundation are sent correctly.
<ViewAttributes >	A string that represents 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. To return all documents in a library, the ViewAttributes element is used as follows: <ViewAttributes Scope="Recursive" />.

Default Query Options

If the queryOptions element is not specified, the following default options are used.

• DateInUtc = TRUE

• ExpandUserField = TRUE

• IncludePermissions = TRUE

• IncludeAttachmentUrls = TRUE

• IncludeAttachmentVersion = TRUE

• MeetingInstanceID = -1

• RecurrenceOrderBy = TRUE

• RecurrencePatternXMLVersion = v3

• ViewAttributes Scope = 'Recursive'

  Note

  Clients should always specify a query option; failing to do so will negatively impact scale performance.

Response Objects

A GetListItemChangesSinceToken response is delivered in an XML format in the form shown below. This fragment contains all the changes and can be assigned to a System.Xml.Node 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>

List and global properties

The following table describes the return parameters.

Table 3: Return Parameters

Parameter	Definition
AlternateUrls	Alternate URLs are listed in the following zone order, delimited by commas: Intranet,Default,Extranet,Internet,Custom
EffectiveBasePermissions	The permissions on the list that is returned by the SPList.EffectiveBasePermissions.ToString(). property.
MaxBulkDocumentSyncSize	The total size of content, in megabytes (MB), that must 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 must do an HTTP GET to retrieve the actual document contents.
MinTimeBetweenSyncs	A server parameter that represents the minimum amount of time between user-initiated or automatic synchronization. The value represents a time in minutes. Note Clients use this value even if the user initiates a manual synchronization. That is, if this value is set to 5 minutes, clients will send only one request every 5 minutes, even if the user repeatedly clicks "send/receive."
RecommendedTimeBetweenSyncs	The recommended minimum time between synchronizations. Do not override for automatic synchronizations. Clients should never automatically synchronize more often than recommended.

Change Events

Changes consist of a list of change events that must be handled specifically by the client.

These change events are taken from the internal change log when a change token is supplied. For a full synchronization (no change token) the changes tag is still returned with the current change token.

The limit on the number of updates returned from a change token is 100. The MoreChanges attribute indicates that the last change token is not current. Additional changes have been made to the list and the client must now call this method again with the new change token.

Table 4: Change Events

In the first two cases above, the client should ignore other changes and do a full reconciliation of the list.

Table 5: Change Types

Data

The ItemCount attribute contains the number of items returned. Each item is returned as a <z:row> tag.

A ListItemCollectionPositionNext attribute is returned for a full synchronization (no change token) only when a rowLimit parameter has been used to limit the number of items returned in one call. This type of paging is blocked on an incremental synchronization by restricting the number of updates that are processed from the change log to the row limit, if that number is smaller than the internal maximum limit.

The contents of the items are returned as attributes with an "ows_" prefix and the internal name of the field. The values are encoded as valid XML attribute values. A set of fields is always returned.

Some fields are marked as required and are returned if the IncludeMandatoryColumns option is set. If <ViewFields /> is sent, all fields are returned.

When Properties="TRUE" is set in the ViewFields tag, the property bag (MetaInfo field) is separated into one attribute per property. These attributes have a prefix of "ows_MetaInfo_".

Most of the column values are simply converted from their internal representation, while others are constructed specifically for a client. Several attributes in the list schema are not represented by a field.

Table 6: Attributes that are not represented by a field in the list schema

See Also

Concepts

GetListItemChangesSinceToken and Synchronizing Applications

How to: Update List Items