SharePoint Document Library Synchronization
Applies to: SharePoint Foundation 2010
The Microsoft Sync Framework can be used to synchronize items in a SharePoint Foundation document library. The synchronization process is similar to that described in SharePoint List Synchronization, although document library synchronization includes passing of the document streams themselves. Enumeration of changes to a document library is obtained in two steps. First, changes to document library list items are enumerated, and then the document streams of changed documents are downloaded. Because of the potential for synchronization collisions when using a two-step process, the Etag property is used to keep the list item and its document stream in sync.
Enumerating List Item Changes
Enumerating list item changes requires using the Etag, which is passed as a parameter of WebDAV get/put requests. Each time a document stream is updated on the server, the document Etag is updated to reflect the change. The value is then passed as a list item property during read and write operations. The server compares the Etag value in the list item to the Etag value on the document on update; alternately, the client makes the comparison on read operations. This ensures that the list item and the document stream belong to the same read/write operation.
The document library list item change enumeration is acquired by using the same GetListItemChangesWithKnowledge(String, String, XmlNode, XmlNode, String, XmlNode, String, XmlNode, XmlNode) method that is used for regular lists. This method call provides client applications with two things – a list of changed list items in the document library as well as current server knowledge. Then, in the next step, the parameters representing the file path and Etag are used to access the file stream by using the WebDAV APIs or the APIs that support File Synchronization via SOAP of HTTP (FSSHTTP, or "Cobalt").
Retrieving the Changed Document Stream
After the list item changes are enumerated, the next step is retrieving the document streams of changed documents.
Use the WebDAV get method to retrieve the document stream together with the value of the document's Etag property. For more information about retrieving an item's stream, see Getting an Item's Stream (WebDAV). If the value of the Etag property that is retrieved differs from the value of the Etag property in the list item property bag, then the document has changed since the time the list item was retrieved. Logic in the client application determines whether the item is skipped and other items in the result set are retrieved, or instead the application synchronizes again immediately.
List items are returned in the order they appear in the change log. Therefore, after downloading a document stream for the list item, the client can update its knowledge by setting the last known server version to the version of the processed item. In cases where synchronization has been interrupted, this allows the client to continue synchronization from the last synchronized document.
Updating Documents on the Server
SharePoint Foundation supports the promotion and demotion of document metadata. If a parser for a specified document type is installed on the server, the parser is called for every document when it is uploaded to extract properties from the document stream. The properties are then promoted to the MetaInfo columns. If a document type has no parser, then property promotion/demotion is not performed.
Documents are updated in two stages:
The protocol client uses WebDAV to send the document stream to the server along with the document Etag that is known to the client. If the Etag on client and server are the same, then the server copy was not changed since the client last retrieved changes, and the new document version is accepted by the server. After writing the document stream, the server promotes properties of the document into list item columns. Then, it updates the version of the associated list item and Etag of the document, then sends the new Etag to the client in a response message.
After receiving the new document Etag, the client requests the updated document list item. This is returned with updated ows_hiddenversion field and the new Etag. The client checks that the Etag in list item matches the Etag on the document. If it is different, then document was updated after completion of step 1, above, and synchronization should be started from the change enumeration. If the Etags are the same then the client updates its client version of the list item with new value of ows_hiddenversion field.
Document updates can trigger different calls to server-side logic, ranging from virus scanners to workflows. This server-side logic may lead to document content updates that may be of interest to the client. The client will rely on the change enumeration procedure to determine whether it needs to download an updated document. The client has to download changes to the document that updated the content version of the document. However, the client may not synchronize changes that modified only server version.