2.2.1.18 Settings

Artykuł
11/16/2021

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

2.2.1.18 Settings

Dodatkowe zasoby