2.2.3.24 Change
The Change element is an optional child element of the Commands element in Sync command requests that modifies properties of an existing object on the client device or the server. The Change element is an optional child element of the Commands element and the Responses element in Sync command responses that contains properties of an existing object on the client device or the server that were modified. The changed object is identified by its ServerId element.
Elements referenced in this section are defined in the AirSync namespace, except where otherwise indicated by the presence of a namespace prefix (as defined in section 2.2.4).
|
Command request/response |
Parent elements |
Child elements |
Data type |
Number allowed |
|---|---|---|---|---|
|
Sync command request (section 2.2.1.21) |
Commands (section 2.2.3.32) |
ServerId (section 2.2.3.166.8) ApplicationData (section 2.2.3.11) airsyncbase:InstanceId ([MS-ASAIRS] section 2.2.2.25) email2:Send ([MS-ASEMAIL] section 2.2.2.69) |
container ([MS-ASDTYPE] section 2.2) |
0...N (optional) |
|
Sync command response |
Commands |
ServerId ApplicationData Class (section 2.2.3.27.6) |
container |
0...N (optional) |
|
Sync command response |
Responses (section 2.2.3.154) |
ServerId airsyncbase:InstanceId Class ApplicationData Status (section 2.2.3.177.17) |
container |
0...N (optional) |
The server is not required to send an individual response for every operation that is sent by the client. The client only receives responses for successful additions, successful fetches, successful changes that include an attachment being added, and failed changes and deletions. When the client does not receive a response, the client MUST assume that the operation succeeded unless informed otherwise.
In a Sync command request or response, one or more Change elements can appear as a child element of the Commands element for a particular collection.
Certain in-schema properties remain untouched in the following cases:
§ If there is only an email:Flag ([MS-ASEMAIL] section 2.2.2.34), email:Read ([MS-ASEMAIL] section 2.2.2.58), or email:Categories ([MS-ASEMAIL] section 2.2.2.16) change (that is, if only an email:Flag, email:Categories, or email:Read element is present), all other properties will remain unchanged and the client SHOULD NOT send the other elements in the request. If all the other elements are sent, extra bandwidth is used, but no errors occur.
§ If a calendar:Exceptions ([MS-ASCAL] section 2.2.2.22) node is not specified in a client request, the properties for that calendar:Exceptions node will remain unchanged. If a calendar:Exception ([MS-ASCAL] section 2.2.2.21) node within the calendar:Exceptions node is not present in a client request, that particular exception will remain unchanged.
§ If the airsyncbase:Body, airsyncbase:Data, or contacts:Picture elements are not present, the corresponding properties will remain unchanged.
§ If an element specifying a calendar property is not present in the client request, the calendar property will remain unchanged on the calendar item. This case does not apply to protocol versions 2.5, 12.0, 12.1, 14.0, and 14.1.
§ If a property is not returned in an ApplicationData element that is contained in the Responses element (section 2.2.3.154) in a server response, it SHOULD be considered unchanged. This case does not apply to protocol versions 2.5, 12.0, 12.1, 14.0, and 14.1.
In all other cases, if an in-schema property is not specified in a change request, the property is actively deleted from the item on the server. A client MUST be aware of this when it is sending Sync requests; otherwise, data can be unintentionally removed.
Protocol Versions
The following table specifies the protocol versions that support this element. The client indicates the protocol version being used by setting either the MS-ASProtocolVersion header, as specified in [MS-ASHTTP] section 2.2.1.1.2.6, or the Protocol version field, as specified in [MS-ASHTTP] section 2.2.1.1.1.1, in the request.
|
Protocol version |
Element support |
|---|---|
|
2.5 |
Yes |
|
12.0 |
Yes |
|
12.1 |
Yes |
|
14.0 |
Yes |
|
14.1 |
Yes |
|
16.0 |
Yes |
|
16.1 |
Yes |
When protocol version 16.0 or 16.1 is used and the Change element is a child of the Responses element, the ApplicationData element is supported as a child of the Change element.
When protocol version 16.0 or 16.1 is used and the changed object is a calendar item, the object is identified by both the ServerId element of the master item as well as the airsyncbase:InstanceId element of the specific occurrence.
The airsyncbase:InstanceId and email2:Send elements are supported as child elements of the Change element only when protocol version 16.0 or 16.1 is used.