|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.|
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
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
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.
- The units for maximum display time are seconds.
- 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 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 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:
- 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
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
viewbutton 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 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.
<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.
<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.
|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.
<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>
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.