OMA DM User Interactive Alerts

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:

• display alert
• confirmation alert
• single user choice alert

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 maximum length of the body text is 1,000 characters. Longer messages will cause the OMA DM client to halt with a status code 400 (Bad Request).
• Each message starts with the predefined string <server name> sent you a message:. The server name is retrieved from the DM account object’s Name node. For more information about DM account objects, see DMS Configuration Service Provider.
• When one of these alerts is displayed, a sound is played to draw the user’s attention to the device.
• If the device receives multiple alerts during one DM session, the second and subsequent alerts will not display until the user confirms the current alert.

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 Call while an alert is displayed, the client will hide the full-screen alert dialog, but not delete it. After the alert dialog is hidden:

• On Windows Mobile Standard, the OMA DM client will bring the alert dialog back to the front after a wait time configured in the registry. The alert wait time registry key is HKLM\Security\Provisioning\OMADM\UIReactivationWaitTime. The unit is seconds and the default value is 120 (2 minutes).
• On Windows Mobile Professional, the title bar displays the DM initiation notification alert icon. The user can retrieve a toast alert dialog by clicking on the notification icon. The toast dialog is a pop-up window that displays for a few seconds when the notification icon is selected. The title of the toast will be Notification, and the text will be the predefined string <server name> sent you a message. The server's name is retrieved from the DM account object’s Name node. The toast's left soft key is View. The right soft key is Dismiss. Clicking the view button will display the detailed alert message.

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 OK confirmation 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.

<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 Yes or 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.

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.

<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 Cancel option, 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.

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.

<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

Reference

DMS Configuration Service Provider

Concepts

OMA DM version 1.2 Architecture
OMA DM Generic Alert

Other Resources