1.3 Overview
This protocol enables a protocol client to call a request that allows for the upload or download of file changes, along with related metadata changes, to or from a single protocol server. In addition, the protocol server processes different types of locking operation requests sent by a client that allow for uploads to be done while preventing merge conflicts on the shared resource. For more details about the different types of locking operations, see sections 3.1.4.3, 3.1.4.4, and 3.1.4.5. The protocol is a request/response stateless message exchange protocol based on SOAP that uses HTTP 1.1 for its transport and SOAP Message Transmission Optimization Mechanism (MTOM) encoding.
The protocol involves two active entities: the protocol client and the protocol server.
The protocol assumes that the protocol server stores files addressable by URLs. Each file has one or more partitions associated with it. These partitions can be empty or contain binary file contents, information related to file coauthoring, or contents that are specific to a file format. The data in each partition can be synchronized independently by using this protocol. For more information about the abstract data model used for synchronization, see [MS-FSSHTTPB] section 3.1.1.
A user on the protocol client or an administrator on the protocol server first creates a document. For a download file request, the protocol client sends a download request to the protocol server for all the contents of a specific partition of a file specified by a URL. If the file exists on the protocol server, the protocol server responds with the requested content or partition data. If the file does not exist, it returns a FileNotExistsOrCannotBeCreated error code as part of the response. For more details about the FileNotExistsOrCannotBeCreated error code and other error codes, see section 2.2.5.6.
For an upload file request, the protocol client sends an upload request to the protocol server indicating the data that has changed that needs to be uploaded. The protocol client can also send an upload request for changes done in the partitions associated with a file at a given URL. The server responds with success or failure for that update.
In an upload or download request, the protocol allows for locking operations to be requested by the protocol client to the protocol server. The locking operations can be for an exclusive lock or a shared lock on a file. In the case of an exclusive lock, the protocol server ensures that only one client is allowed to edit the file and responds with success in locking the file for edit. For more details about the exclusive lock operation, see section 3.1.4.5. In the case of a shared lock, the protocol server allows multiple clients to edit the coauthorable file and responds with success in sharing the lock on the coauthorable file. Depending on the type of shared lock operation, the protocol server also keeps tracks of the clients editing the file and lets the protocol client know of the coauthoring status. For more details about the coauthoring status, see section 2.2.5.1. For more details about the shared lock operations, see section 3.1.4.3 and section 3.1.4.4.
In case of failure in an exclusive lock request or shared lock request, the protocol server responds with an error code value indicating the type of error. For more details about error code types, see section 2.2.5.4.
The following diagram illustrates file upload, download, and lock requests and responses.
Figure 1: File upload and download to and from a server as well as lock requests to a server
The protocol provides a means to upload or download files from the protocol server without the need to retrieve the entire content or metadata for a given file every time. This is achieved by the protocol client working with the protocol as described in [MS-FSSHTTPB], which allows for incremental file synching, and the client local cache.
Because multiple clients can coauthor a file, if two or more clients sent an upload request simultaneously, all requests except the first one fail with a coherency error. Coherency failure error codes are as described in [MS-FSSHTTPB]. If the upload request fails with a coherency error, the protocol client sends a download request to get the latest changes to the file from the protocol server. The protocol client automatically merges the latest changes with its local version of the file. If the protocol client is unable to do an automatic merge, it exposes the merge conflict to the user and lets the user do a manual merge. The protocol client then sends another upload request to upload the merged version of the file to the server. The upload request succeeds if the file has not been updated by another client since the last download request made by the current client.
A typical scenario for using this protocol involves a word processing application that enables coauthoring and the multiuser editing of files that are stored on a single protocol server.