Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

When the OMA DM client communicates with an OMA DM server, the server can send alert messages to the device.

Windows Mobile supports the following user interactive alert messages:

These alerts and the codes associated with them are defined in OMA DM specification v1.2 and are valid only in OMA DM protocol. For more information about OMA DM user interactive alerts, see OMA Device Management Protocol (OMA-TS-DM_Protocol-V1_2-20060602-C) and OMA Device Management Representation Protocol (OMA-TS-DM_RepPro-V1_2-20060602-C), available from this OMA Web site .

The following behavior is common to all three supported user interactive alert messages.

The following two server-specified options are supported for these alerts:

Maximum Display Time (MAXDT)

The alert is displayed for this period of time. If there is no user interaction during this period, the DM client will execute the default action.

  • The units for maximum display time are seconds.

  • Windows Mobile limits server-specified maximum display time to 86400 (24 hours). Values larger than this will cause the DM client to halt with an error.

  • If no value is specified in the alert message, the default value of 300 (5 minutes) is used.

Default Response (DR)

This is the default response value for the single user choice alert.

  • If this option is specified by the server, the corresponding selection in the alert will be highlighted. If the user doesn’t respond, a status code indicating the DR selection is sent as the status for the alert.

  • If this option isn’t specified, there is no default selection and nothing should be highlighted. If the user doesn’t respond, a timeout is sent as the status for the alert.

If the user clicks buttons such as the Home, Back,or Callwhile an alert is displayed, the client will hide the full-screen alert dialog, but not delete it. After the alert dialog is hidden:

Note that, beginning with Windows Mobile 6.5.3, soft keys are replaced by touchable tiles on Windows Mobile Professional phones.

Display Alert (1100)

The display alert is an informational dialog and has an OKconfirmation button. The DM client reports a status to the server for each display alert. If the user doesn’t respond within the maximum display time, a timeout status is sent to the server, the dialog is discarded, and other commands are processed normally per OMA DM representation protocol.

Code Example for Display Alert

The following example shows how a display alert message (1100) is used in an OMA DM provisioning file sent to a Windows Mobile device.

Copy Code 
<Alert>
   <CmdID>2</CmdID>
   <Data>1100</Data>  <!-- alert code for Display
Alert -->
   <Item><Data>MINDT=10</Data></Item>
   <Item><Data>MAXDT=600</Data></Item> 
<!-- maximimum display time for alert -->
   <Item>
	 <Data>Your mobile operator is doing maintenance on your
device.</Data>  <!-- Body text -->
   </Item>
</Alert>

Confirmation Alert (1101)

The user can respond to a confirmation alert with either Yesor No.

If the user chooses No, the processing of the XML package will change according to the location of the confirmation alert in the package. The following table shows the possible processing.

Confirmation Alert Location in the Package Processing When the User Chooses No

The Confirmation Alert is inside Atomic

Atomic fails and all executed commands are rolled back.

The Confirmation Alert is inside Sequence

All commands in Sequence after the Confirmation Alert are bypassed. A status code 215 (Not Executed) is sent for all bypassed commands.

The Confirmation Alert is inside SyncBody, but not inside Atomic or Sequence

The user response has no effect on package processing.

If the user doesn’t response within the maximum display time, the action is cancelled and a timeout status is sent to the server. Status code 215 (Not Executed) is sent for all commands not processed.

Code Example for Confirmation Alert

The following example shows how a confirmation alert message (1101) is used in an OMA DM provisioning file sent to a Windows Mobile device.

Copy Code 
<Alert>
   <CmdID>2</CmdID>
   <Data>1101</Data>  <!-- alert code for
Confirmation Alert -->
   <Item>
	 <Data>Do you want your mobile operator to add a WiFi
access point for this location to your mobile device?</Data> 
<!-- Body text -->
   </Item>
</Alert>

Single User Choice Alert (1103)

The Single User Choice alert has at least two option buttons and supports up to 100 option buttons. If this limit is exceeded, the DM client stops with status code 400 (Bad Request). If the server-specified default response (DR) is one of the options, the corresponding option button is highlighted.

One of the option buttons is Cancel. If the user selects the Canceloption, processing stops, status codes for executed commands are reported normally, and status code 215 (Not Executed) is sent for commands not processed.

The maximum length of the text description for each choice is the number of characters in a single row of the device display. Longer text is truncated, processing continues and no error is generated.

Note:
Information about the available options can be included in the body text of the alert message. As a best practice, descriptions should include sufficient information to allow the user to make an informed choice, but should be concise enough to allow all options to display without scrolling.

After processing the user response, the server may continue the OMA DM protocol session with some other device management operation.

If the user doesn’t respond within the maximum display time, the action is cancelled and a timeout status (if DR isn’t specified) or default response status (if DR is specified) is sent to the server. Status code 215 (Not Executed) is sent for all commands not executed.

Code Example for Single User Choice Alert

The following example shows how a single user choice alert message (1103) is used in an OMA DM provisioning file sent to a Windows Mobile device.

Copy Code 
<Alert>
   <CmdID>2</CmdID>
   <Data>1103</Data>  <!-- alert code for Single
User Choice Alert -->
   <Item><Data>MINDT=10</Data></Item>
   <Item>
	<Data>Your mobile operator is offering you some
choices. You can choose one to get 1 or two to get 2 or n to get
n.</Data>  <!-- Body text -->
   </Item>
   <Item>
	<Data>This is choice number one</Data>
   </Item>
   <Item>
	<Data>This is choice number two</Data>
   </Item>
   <Item>
	<Data>This is choice number n</Data>
   </Item>
</Alert>

Comments

One provisioning XML file typically contains configuration information for multiple Configuration Service Providers. To use any of the examples above, the values must be replaced appropriately and the node added as a child or grandchild of the SyncBody node in an OMA DM provisioning file. For more information about the syntax of the provisioning file, see OMA DM Provisioning Files.

See Also