22.214.171.124 Cell Subrequest
This operation is used to retrieve or upload the binary or metadata contents of a file. The contents are uploaded or downloaded fully or partially. The download or upload of the contents is accomplished by indicating the partition identifier whose contents are to be uploaded or downloaded. The cell subrequest acts as a wrapper around the actual file synchronization processing logic as specified in [MS-FSSHTTPB].
The protocol client sends a cell SubRequest message, which is of type CellSubRequestType as specified in section 126.96.36.199. The protocol server responds with a cell SubResponse message, which is of type CellSubResponseType as specified in section 188.8.131.52. This is done as follows:
The protocol client prepares a request containing a URL for the file, a unique Request token, and one or more SubRequest elements, as defined in section 184.108.40.206 and section 220.127.116.11. The SubRequest element is of type "Cell", and the SubRequestData element contains attributes that are input parameters used by the server when processing the cell subrequest. The SubRequestData element is of type CellSubRequestDataType and is defined in section 18.104.22.168.
The binary data sent in the SubRequestData element indicates if this is a file content upload or download. The meaning of the data is as specified in [MS-FSSHTTPB] section 22.214.171.124.3. The cell subrequest for an upload of the file contents is processed as specified in [MS-FSSHTTPB] section 126.96.36.199. The cell subrequest for a download of the file contents is processed as specified in [MS-FSSHTTPB] section 188.8.131.52. The schema lock identifier MUST be specified in a cell subrequest if the current client already shared the lock on the file and is in a coauthoring session. The schema lock identifier is defined in section 184.108.40.206. When the schema lock identifier is specified in the cell subrequest, the protocol server returns a success error code if the file currently has a shared lock with the specified schema lock identifier.
The bypass lock identifier MUST be present when uploading the binary or metadata contents of a file. It MUST NOT be present when retrieving the binary or metadata contents of a file. The bypass lock identifier is defined in section 220.127.116.11. When the bypass lock identifier is specified in a cell subrequest, exactly one of the following is true:
The file is schema locked. In this case, the bypass lock identifier MUST be the same as the schema lock identifier. They have the same semantics, in this case.
The file is exclusive locked. In this case, the bypass lock identifier MUST be the same as the exclusive lock identifier. They have the same semantics, in this case. The exclusive lock identifier is defined in section 18.104.22.168.
If the ExpectNoFileExists attribute is set to true in a file content upload cell subrequest, the Etag attribute MUST be an empty string. In this case, the protocol server MUST cause the cell subrequest to fail with a coherency error if and only if the file already exists on the server. The ExpectNoFileExists attribute is defined in section 22.214.171.124. The Etag attribute is defined in section 126.96.36.199. Coherency failure error codes are as specified in [MS-FSSHTTPB].
If the Coalesce attribute is set to true in a cell subrequest, the protocol server persists all changes to the file in the underlying store. The Coalesce attribute is defined in section 188.8.131.52. For all first-time saves of the file’s binary file contents in a partition, the following MUST be specified:
The ExclusiveLockID attribute (section 184.108.40.206) is set to a unique lock identifier.
When the protocol server receives the ExclusiveLockID in a cell subrequest, the server performs the following steps as an atomic operation:
Get an exclusive lock on the file.
Commit the file’s binary contents, as specified in [MS-FSSHTTPB] section 220.127.116.11. (Note that for updates to other partitions that do not contain binary file contents, the Coalesce attribute is set to false in the cell subrequest.)
The protocol server receives the request and parses the logic to send the information to the underlying store. If the request is a download request, the encoded file contents are sent back to the protocol client. If file properties–specific information is requested, the file properties are prepared as a response and sent back to the protocol client.
The Response element is defined in section 18.104.22.168, and the SubResponse element is defined in section 22.214.171.124. The CellSubResponseDataType specifies the type of the SubResponseData element inside the cell SubResponse element. The CellSubResponseDataType is defined in section 126.96.36.199. In the case where the protocol server finishes performing the request but in the middle of generating the SubResponseData data, another request changes the file content or metadata, the protocol server returns an additional SubResponseStreamInvalid element to indicate that the binary data in the SubResponseData is not valid. The protocol client can resend the request to get the data. The SubResponseStreamInvalid element is defined in 188.8.131.52.
The protocol server returns results based on the following conditions:
If the protocol server was unable to find the URL for the file specified in the Url attribute, the protocol server reports a failure by returning an error code value set to "CellRequestFail" in the ErrorCode attribute sent back in the SubResponse element, and the binary data in the returned SubRequestData element indicates an HRESULT Error as described in [MS-FSSHTTPB] section 184.108.40.206.4. But for Put Changes subrequest, as described in [MS-FSSHTTPB] section 220.127.116.11.4, the protocol server creates a new file using the specified Url.
Depending on the type of error, the ErrorCode returned as an attribute of the SubResponse element is updated with a specific error code as specified in section 18.104.22.168.
ErrorCode includes "Success" to indicate success in processing the file upload or download request.