2.2.3.2 Request
Each Request element maps to a synchronization request for a specific file. Each file MUST be uniquely identified by a URL for the file. The synchronization request for a file or the file’s metadata is divided into subrequests. Each Request element MUST have one or more SubRequest elements.
-
<xs:element name="Request"> <xs:complexType> <xs:sequence> <xs:element name="GenericProperties" type="tns:GenericPropertiesType" minOccurs="0" /> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="SubRequest" type="tns:SubRequestElementGenericType" /> </xs:sequence> </xs:sequence> <xs:attribute name="Url" type="xs:string" use="required"/> <xs:attribute name="Interval" type="xs:nonNegativeInteger" use="optional"/> <xs:attribute name="MetaData" type="xs:integer" use="optional"/> <xs:attribute name="RequestToken" type="xs:nonNegativeInteger" use="required" /> <xs:attribute name="UserAgent" type="tns:guid" use="optional" /> <xs:attribute name="UserAgentClient" type="xs:string" use="optional" /> <xs:attribute name="UserAgentPlatform" type="xs:string" use="optional" /> <xs:attribute name="Build" type="xs:string" use="optional" /> <xs:attribute name="ParentFolderResourceID" type="xs:string" use="optional" /> <xs:attribute name="ShouldReturnDisambiguatedFileName" type="xs:boolean" use="optional" /> <xs:attribute name="ResourceID" type="xs:string" use="optional"/> <xs:attribute name="UseResourceID" type="tns:TRUEFALSE" use="optional"/> </xs:complexType> </xs:element>
GenericProperties: A GenericPropertiesType that specifies the generic properties of the request. The GenericPropertiesType is defined in section 2.2.4.1.
SubRequest: A SubRequestElementGenericType that specifies the type of subrequest for the URL for the file and input parameters needed by a protocol server for processing the subrequest. The SubRequest element is defined in section 2.2.3.8. The SubRequestElementGenericType is defined in section 2.2.4.4.
Url: A string that specifies the URL for the file that uniquely identifies the file whose contents or metadata contents are requested for uploading to the server or downloading from the server. The Url attribute MUST be specified for each Request element. The string specifying the file MUST NOT be an empty string.
Interval: A nonnegative integer that specifies the interval, in seconds, that the protocol client will repeat this request. This value is used by protocol servers when throttling requests.<1>
MetaData: A 32-bit value that specifies information about the scenario and urgency of the request. This value is used by protocol servers when throttling requests.<2>
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
Reserved |
||||||||||||||||||
A – Request Source (1-bit): A bit that specifies if the request was
triggered by a user action or an automated process.
|
Value |
Meaning |
|---|---|
|
0 |
Automatically generated request. |
|
1 |
User action–generated request. |
B – User Presence (1-bit): A bit that specifies if the request was triggered when the protocol client considered the user present or absent.
|
Value |
Meaning |
|---|---|
|
0 |
User absent. |
|
1 |
User present. |
C- Cache Status (1-bit): A bit that specifies if the protocol client has a local cache.
|
Value |
Meaning |
|---|---|
|
0 |
The protocol client has no local cache. |
|
1 |
The protocol client has a local cache. |
D- Coauthoring Presence (2-bits): A 2-bit unsigned integer that specifies the protocol client's awareness of other protocol clients' coauthoring.
|
Value |
Meaning |
|---|---|
|
0 |
No other authors. |
|
1 |
Other authors detected far from where the protocol client is working. |
|
2 |
Other authors detected in the same section where the protocol client is working. |
|
3 |
Other authors detected outside the same page where the protocol client is working. |
E – Response Data View (2-bits): A 2-bit unsigned integer that specifies when the protocol client will present the response data to the user.
|
Value |
Meaning |
|---|---|
|
0 |
Future user action in a new session. |
|
1 |
Future user action in the current session. |
|
2 |
Automatically after a short delay. |
|
3 |
Immediately. |
F – Time Since User View (2-bits): A 2-bit unsigned integer that specifies how long it has been since the user viewed data referenced by the Url.
|
Value |
Meaning |
|---|---|
|
0 |
Recently. |
|
1 |
Within one week. |
|
2 |
Within one month. |
|
3 |
More than one month. |
G – Document Active State (1-bit): A bit that specifies if the protocol client considered the URL an active or inactive session at the time the request was triggered.
|
Value |
Meaning |
|---|---|
|
0 |
Active. |
|
1 |
Inactive. |
H – Data Type (1-bit): A bit that specifies if the request data is recoverable by the protocol client.
|
Value |
Meaning |
|---|---|
|
0 |
The data is content and requires permanent reliable storage. |
|
1 |
The data is recoverable. Less reliable stores can be used. |
I – Network Cost Level (2-bits): A 2-bit unsigned integer that specifies the cost of the network used to make the request.
|
Value |
Meaning |
|---|---|
|
0 |
Unspecified or unknown. |
|
1 |
Low-cost network. |
|
2 |
Medium-cost network. |
|
3 |
High-cost network. |
J – Network Quota State (2-bits): A 2-bit unsigned integer that specifies the network quota state when a metered network is being used to make the request.
|
Value |
Meaning |
|---|---|
|
0 |
No quota system. |
|
1 |
The quota system is active; the quota consumed is one half or less. |
|
2 |
The quota system is active; the quota consumed is from one half through three quarters. |
|
3 |
The quota system is active; the quota consumed is near or over the limit. |
K – Power State (1-bit): A bit that specifies the protocol client hardware power state.
|
Value |
Meaning |
|---|---|
|
0 |
Powered by a continuous power source. |
|
1 |
Powered by battery. |
L – Application State (1-bit): A bit that specifies the protocol client sync state.
|
Value |
Meaning |
|---|---|
|
0 |
Protocol client is functioning normally. |
|
1 |
Protocol client is not functioning normally. |
M– License Type (2-bits): A 2-bit unsigned integer that specifies the client’s license type.
|
Value |
Meaning |
|---|---|
|
0 |
License type is unspecified or unknown. |
|
1 |
License type is full. |
|
2 |
License type is limited. |
|
3 |
License type is free. |
Reserved (13-bits): Reserved. MUST be zero.
RequestToken: A nonnegative integer that specifies the request token that uniquely identifies the Request element in a cell storage service request. The RequestToken MUST be set to a nonnegative integer value, with a minimum allowed value of zero, and a maximum allowed value of 4,294,967,295. For each new Request element in a cell storage service request that needs to be sent to the protocol server, RequestToken is incremented by the protocol client. RequestToken is reset to 1 by the protocol client for a new cell storage service request. The one-to-one mapping between the Response element and the Request element MUST be maintained by using RequestToken. A RequestToken value MUST be specified for each Request element.
UserAgent: A guid that specifies a unique identifier of a user agent.<3>
UserAgentClient: A string that specifies a user agent client.<4>
UserAgentPlatform: A string that specifies a user agent platform.<5>
Build: A string that specifies a user agent build number which represents as a four-part string with the following format: <major version>.<minor version>.<build number>.<revision>. For example, version 1.5.1254.0 indicates 1 as the major version, 5 as the minor version, 1254 as the build number, and 0 as the revision number.<6>
Errors that occur during the parsing of the Request element cause the error code value to be set to "InvalidArgument". The protocol server MUST send the error code as an error code attribute in the Response element. The ErrorCode attribute is defined in section 2.2.3.5. Depending on the other types of errors, the error code for that type MUST be returned by the protocol server. Generic error code types are defined in section 2.2.5.6.
ParentFolderResourceID: If UseResourceID is true, the server creates a file in the given folder ResourceID, regardless of the request Url value.<7> This attribute SHOULD only be used for the file content upload cell subrequest. If the folder with the specified ParentFolderResourceID does not exist, the server will fall back to use the Url value.
ShouldReturnDisambiguatedFileName: If an upload request fails with a coherency failure, this flag specifies whether the host will return a suggested/available file name that the client can try instead<8>.
ResourceID: A string that represents a GUID which specifies the invariant ResourceID for a file that uniquely identifies the file whose response is being generated.<9> A ResourceID MUST NOT change over the lifetime of a file, even if the URL of the file changes. Attribute SHOULD NOT be present when the UseResourceID attribute is set as false.
UseResourceID: A TRUEFALSE value that specifies if the protocol server will perform ResourceID specific behavior for the file whose contents or metadata contents are requested for uploading to the server or downloading from the server.<10> When true, the protocol server SHOULD set the ResourceID attribute on the corresponding Response element to the ResourceID of the file. Also when true and the ResourceID attribute is set on the Request element, the protocol server SHOULD use the value of the ResourceID attribute to identify the file instead of the Url attribute. In the case where the protocol server is using the ResourceID attribute but the ResourceID attribute does not identify a valid file the protocol server SHOULD set an error code in the ErrorCode attribute of the corresponding Response attribute.