3.3.4.3.3 Uploading Changes Using ICS
The client uploads the initial ICS state and downloads the final/checkpoint ICS state when performing a synchronization upload. Clients can perform a synchronization upload without uploading the initial ICS state properties into a synchronization upload context, because the behavior of the RopSynchronizationImport* ROPs do not depend on the initial ICS state. In that case, a server can download the changes uploaded in this session during the subsequent ICS downloads.
The following figure shows the primary processes taking place during an upload operation. The sections that follow describe the details within the Send Data process.
Figure 4: Upload operation
The following steps elaborate on the steps in the figure and MUST be taken by a client when uploading mailbox differences to a server:
Obtain a handle to the Folder object, as specified in [MS-OXCFOLD], that will be synchronized.
Send a RopSynchronizationOpenCollector ROP request (section 2.2.3.2.4.1) to create a synchronization upload context on the server and to define parameters and the scope of an operation.
The client SHOULD send the RopSynchronizationUploadStateStreamBegin ROP (section 2.2.3.2.2.1), the RopSynchronizationUploadStateStreamContinue ROP (section 2.2.3.2.2.2), and the RopSynchronizationUploadStateStreamEnd ROP (section 2.2.3.2.2.3) request to upload the initial ICS state information to the synchronization context.
Upload changes, moves, and deletes of individual objects within the synchronized Folder object through RopSynchronizationImport* ROPs, while passing the synchronization upload context obtained in step 2. Uploading hierarchy changes is specified in section 3.3.4.3.3.1. Uploading content changes is specified in section 3.3.4.3.3.2.
The client SHOULD obtain the final ICS state by doing the following:
Acquire a separate FastTransfer download context for a checkpoint ICS state by using the RopSynchronizationGetTransferState ROP (section 2.2.3.2.3.1) and passing the synchronization upload context obtained in step 2 in the request buffer.
Perform FastTransfer download step 4, as specified in section 2.2.3.1.1, on the FastTransfer download context acquired in the first bullet point.
Release the FastTransfer download context obtained in the first bullet point.
Persist the ICS state.
Send the RopRelease ROP ([MS-OXCROPS] section 2.2.15.3) request to release the Folder object and the synchronization upload context obtained in steps 1 and 2.
The client can elect not to upload/download the ICS states in steps 3 and 5. For details on how that would affect responsibilities of the protocol roles, see section 3.3.4.3.3.
The following table lists the common return values from the RopSynchronizationImport* ROPs that clients SHOULD have special processing for.
|
Value |
Description |
|---|---|
|
Success |
No error occurred, or a conflict has been resolved. |
|
NoParentFolder |
An attempt is being made to upload a hierarchy change for a folder whose parent folder does not yet exist. |
|
ObjectDeleted |
An attempt is being made to import a message change to a message that has been deleted. The client SHOULD subsequently ignore the failure because it is just a warning. |
|
IgnoreFailure |
An attempt is being made to import a change that the server already has. For example, if the client calls the RopSynchronizationImportMessageChange ROP, as specified in section 2.2.3.2.4.2, and uploads a change and then issues the exact same RopSynchronizationImportMessageChange ROP request to the server with the exact same message with the exact same change, the server returns this value because it either already has the change or has a version of the message that supersedes that change, so it does not need the change. |
The complete list of error codes is specified in [MS-OXCDATA] section 2.4.