2.2.1.18 Settings
The Settings command supports get and set operations on global properties and Out of Office (OOF) settings for the user. The Settings command also sends device information to the server, implements the device password/personal identification number (PIN) recovery, and retrieves a list of the user's email addresses.
The Get (section 2.2.3.83) and Set (section 2.2.3.167) operations act on named properties. In the context of the Get and Set operations, each named property can contain a set of property-specific data nodes.
The Settings command can contain multiple Get and Set requests and responses in any order. The implication of this batching mechanism is that commands are executed in the order in which they are received and that the ordering of Get and Set responses will match the order of those commands in the request.
The following is the generic form of the Settings request, where "PropertyName" is a named property (that is, the actual name of the property).
-
<Settings> <PropertyName> Data nodes </PropertyName> ... </Settings>
The Settings command can be used on the following named properties:
OOF (section 2.2.3.122)
DevicePassword (section 2.2.3.46)
DeviceInformation (section 2.2.3.45)
UserInformation (section 2.2.3.192)
RightsManagementInformation (section 2.2.3.156)
The argument or data nodes are Get or Set, which can also have their own arguments. It is up to the individual property handlers to parse and interpret them as necessary.
It is possible to have between 0 (zero) and 5 PropertyName elements in a Settings request (that is, each of the four named properties can appear zero or one time in a request). Each property MUST be processed in order. There can be cases in which one property call affects another property call. The server will return responses in the same order in which they were requested.
Each response message contains a Status element (section 2.2.3.177.15) value for the command, which addresses the success or failure of the Settings command, followed by Status values for each of the changes made to the Oof, DeviceInformation, DevicePassword or UserInformation elements.
The Status node MUST indicate success if the Settings response contains property responses. If the command was not successful, the processing of the request cannot begin, no property responses are returned, and the Status node MUST indicate a protocol error.
Any error other than a protocol error is returned in the Status elements of the individual property responses. All property responses, regardless of the property, MUST contain a Status element to indicate success or failure. This Status node MUST be the first node in the property response.
The Settings namespace is the primary namespace for this section. Elements referenced in this section that are not defined in the Settings namespace use the namespace prefixes defined in section 2.2.4.
The following table lists the elements that are used in Settings command requests and responses.
|
Element name |
Scope |
Reference |
|---|---|---|
|
Settings |
Request and Response |
section 2.2.3.168.2 |
|
RightsManagementInformation |
Request and Response |
section 2.2.3.156 |
|
Get |
Request and Response |
section 2.2.3.83 |
|
Oof |
Request and Response |
section 2.2.3.122 |
|
BodyType |
Request and Response |
section 2.2.3.17 |
|
Set |
Request |
section 2.2.3.167 |
|
OofState |
Request and Response |
section 2.2.3.124 |
|
StartTime |
Request and Response |
section 2.2.3.176.2 |
|
EndTime |
Request and Response |
section 2.2.3.61.2 |
|
OofMessage |
Request and Response |
section 2.2.3.123 |
|
AppliesToInternal |
Request and Response |
section 2.2.3.14 |
|
AppliesToExternalKnown |
Request and Response |
section 2.2.3.12 |
|
AppliesToExternalUnknown |
Request and Response |
section 2.2.3.13 |
|
Enabled |
Request and Response |
section 2.2.3.59 |
|
ReplyMessage |
Request and Response |
section 2.2.3.149 |
|
DevicePassword |
Request and Response |
section 2.2.3.46 |
|
Password |
Request |
section 2.2.3.132.3 |
|
DeviceInformation |
Request and Response |
section 2.2.3.45 |
|
Model |
Request |
section 2.2.3.115 |
|
IMEI |
Request |
section 2.2.3.91 |
|
FriendlyName |
Request |
section 2.2.3.81 |
|
OS |
Request |
section 2.2.3.127 |
|
OSLanguage |
Request |
section 2.2.3.128 |
|
PhoneNumber |
Request |
section 2.2.3.134 |
|
UserAgent |
Request |
section 2.2.3.190 |
|
EnableOutboundSMS |
Request |
section 2.2.3.60 |
|
MobileOperator |
Request |
section 2.2.3.113 |
|
UserInformation |
Request and Response |
section 2.2.3.192 |
|
Status |
Response |
section 2.2.3.177.15 |
|
Accounts |
Response |
section 2.2.3.5 |
|
Account |
Response |
section 2.2.3.2 |
|
AccountId |
Response |
section 2.2.3.3.2 |
|
AccountName |
Response |
section 2.2.3.4 |
|
UserDisplayName |
Response |
section 2.2.3.191 |
|
SendDisabled |
Response |
section 2.2.3.161 |
|
EmailAddresses |
Response |
section 2.2.3.57 |
|
SMTPAddress |
Response |
section 2.2.3.171 |
|
PrimarySmtpAddress |
Response |
section 2.2.3.138 |
The XML schema for the Settings command request is described in section 6.39. The XML schema for the Settings command response is described in section 6.40.
Protocol Versions
The following table specifies the protocol versions that support this command. 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 |
Command support |
|---|---|
|
2.5 |
|
|
12.0 |
Yes |
|
12.1 |
Yes |
|
14.0 |
Yes |
|
14.1 |
Yes |
|
16.0 |
Yes |
|
16.1 |
Yes |