Cellular Manager

Stagenow - 2.6

Overview

The Cellular Manager (CellularMgr) controls the way a device's cellular data connection is used. This CSP is supported only on Zebra Android devices equipped with a Wireless Wide Area Network (WWAN) adapter with access a cellular data network. Attempts to use the CellularMgr on unsupported devices will return an error in the Result XML document.

The CellularMgr provides the ability to control the State (active/inactive) and Usage (enabled/disabled) of features. An option's "State" can be thought of as an "On/Off" switch; the feature is available to programs or the device user to make active or inactive as desired. The term "Usage" would be like a cover over the switch, locking it in its current position. When Usage of an option has been Disabled, the cover is closed, and the position of the switch cannot be changed by the user. Enabling Usage lifts the cover, and lets the user make Cellular features active or inactive.

Main Functionality

Enable/Disable (control Usage of):
- Data Roaming
- Background Data
- SIM Slot(s)
Turn On/Off (control State of):
- Data Roaming
- Background Data
Select SIM Slot
Enter a custom cellular data limit and warning threshold

SIM Socket Selection Enable/Disable

Controls whether the device user can change the selected SIM Socket using the Select SIM Socket parameter. When Disabled, the SIM Socket cannot be selected by the device user. Supported on specific Zebra devices only.

Parm Name: SimSocketUsage

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to user control over SIM Socket selection; any previously selected setting will be retained.	All	MX: 6.2+
1	Enable	Enables the device user to control which SIM Socket is used.	All	MX: 6.2+
2	Disable	Prevents the user from changing the selected SIM Socket.	All	MX: 6.2+

Select SIM Socket

Used to select which SIM card will be used to connect the device to the carrier network. Supported on specific Zebra devices only.

Parm Name: SimSocketSelect

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change; the previously selected SIM socket will be used.	All	MX: 6.2+
1	SIM1	Uses SIM1 to connect the device to the carrier network.	All	MX: 6.2+
2	SIM2	Uses SIM2 to connect the device to the carrier network.	All	MX: 6.2+
3	SIM3	Uses SIM3 to connect the device to the carrier network.	All	MX: 6.2+
4	SIM4	Uses SIM4 to connect the device to the carrier network.	All	MX: 6.2+

Data Roaming Enable/Disable

Used to control whether the device user has access to the Data Roaming option on the device. When Disabled, Data Roaming cannot be turned on or off programmatically or by the device user.

The Data Roaming Option determines whether a device can communicate over cellular data networks other than the "home" network provided by the mobile operator with which the active SIM card is affiliated. The convenience of communicating over "foreign" networks while roaming must be weighed against the roaming charges imposed by foreign carriers, which can be significant.

Parm Name: DataRoamingUsage

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to usage of the Data Roaming Option; any previously selected setting will be retained.	All	OSX: 4.4+ MX: 4.4+
1	Enable	Enables Data Roaming to be used on the device and its state (active/inactive) to be controlled programmatically or by the device user.	All	OSX: 4.4+ MX: 4.4+
2	Disable	Disables Data Roaming on the device, preventing its state (active/inactive) from being controlled programmatically or by the device user.	All	OSX: 4.4+ MX: 4.4+

Option

Name

Description

Device Group

Requires

Do not change

This value (or the absence of this parm from the XML) will cause no change to usage of the Data Roaming Option; any previously selected setting will be retained.

All

OSX: 4.4+

MX: 4.4+

Enable

Enables Data Roaming to be used on the device and its state (active/inactive) to be controlled programmatically or by the device user.

All

OSX: 4.4+

MX: 4.4+

Disable

Disables Data Roaming on the device, preventing its state (active/inactive) from being controlled programmatically or by the device user.

All

OSX: 4.4+

MX: 4.4+

Data Roaming On/Off

This is the On/Off switch for Data Roaming, which gives a device user the option of allowing cellular data connections to be established while a device is outside its "home" network.

Parm Name: DataRoamingState

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to the current state of the Data Roaming; any previously selected setting will be retained.	All	MX: 4.3+ Android API Level: 17+
1	Turn On	Turns On Data Roaming, allowing cellular data connections while a device is outside the carrier's home network.	All	MX: 4.3+ Android API Level: 17+
2	Turn Off	Turns Off Data Roaming, preventing cellular data connections while a device is outside the carrier's home network.	All	MX: 4.3+ Android API Level: 17+

Option

Name

Description

Device Group

Requires

Do not change

This value (or the absence of this parm from the XML) will cause no change to the current state of the Data Roaming; any previously selected setting will be retained.

All

MX: 4.3+

Android API Level: 17+

Turn On

Turns On Data Roaming, allowing cellular data connections while a device is outside the carrier's home network.

All

MX: 4.3+

Android API Level: 17+

Turn Off

Turns Off Data Roaming, preventing cellular data connections while a device is outside the carrier's home network.

All

MX: 4.3+

Android API Level: 17+

Cellular Data Enable/Disable

This feature to be implemented in the future.

Controls whether the cellular connection on the device can be used to transmit data. When Enabled, the state (active/inactive) of the cellular data connection can be controlled programmatically or by the user. When Disabled, the device is prevented from establishing a data connection using the cellular network and the state cannot be changed. This parameter controls only cellular data; voice and SMS messaging apps are uneffected by this setting.

Parm Name: CellularDataUsage

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	A	MX: 6.3+
1	Enable	Enables cellular data to be used on the device and its state (active/inactive) to be controlled programmatically or by the device user.	A	MX: 6.3+
2	Disable	Disables cellular data on the device, preventing the establishment of a data connection using the cellular network.	A	MX: 6.3+

Cellular Data On/Off

This is the On/Off switch for device users or apps to control the ability to establish a cellular data connection on the device. This parameter controls only cellular data; voice and SMS messaging apps are uneffected by this setting.

Parm Name: CellularDataState

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	All	MX: 6.3+
1	Turn On	Allows a cellular data connection to be established on the device.	All	MX: 6.3+
2	Turn Off	Prevents a cellular data connection from being established on the device.	All	MX: 6.3+

Cellular Data Limit Enable/Disable

This feature to be implemented in the future.

Controls whether a limit can be placed on cellular data usage on the device. When Enabled, the device user or an app running on the device can access other parameters that turn data limiting on and off and that control the limit value (in MB per month) and the warning message displayed when the limit is reached. If this parameter is Disabled and cellular data is Enabled on the device, there will be no means of limiting data usage over the cellular network, and all related parameters will be inaccessible by apps or the device user.

Parm Name: CellularDataLimitUsage

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	A	MX: 6.3+
1	Enable	Enables a limit to be set on cellular data usage and the state (active/inactive) of the limit to be controlled programmatically or by the device user.	A	MX: 6.3+
2	Disable	Prevents a limit on cellular data usage from being set on the device.	A	MX: 6.3+

Cellular Data Limit On/Off

This is the On/Off switch for limiting cellular data (in MB per month) on the device, and the selector for applying the Android-default or a custom limitation. When Enabled using the Android default limit, the limit will be the greater of 5GB or 1.2 times the value specified in the Cellular Data Warning Value parameter, to a maximum of 1TB. If the custom limit is selected, the limit will be the value specified in the Cellular Data Limit Value parameter. Once the limit is reached, the cellular data connection is terminated until a new month begins or the restriction is lifted. If no value is specified with the Cellular Data Limit Value parameter, this parameter is ignored and the previously selected Cellular Data Limit State is retained.

Shown if: Cellular Data State is set to "Enable"

Parm Name: CellularDataLimitState

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	A	MX: 6.3+
1	Enable and set default limit	Limits cellular data usage to the Android default value.	A	MX: 6.3+
2	Enable and set custom limit	Limits cellular data usage to the amount set in the Cellular Data Limit Value parameter.	A	MX: 6.3+
3	Disable	Prevents a limit on cellular data usage from being imposed on the device.	A	MX: 6.3+

Cellular Data Limit Value

Used to specify the limit (in MB per month) of cellular data usage by the device. Once the limit is reached, the cellular data connection is terminated until a new month begins or the restriction is lifted.

Parm value input rules:

Integer from 5-1048576 (5MB-1TB) corresponding to the data usage monthly limit

Shown if: Cellular Data State is set to "Enable" and Cellular Data Limit State is set to "Enable and set custom limit"

Parm Name: CellularDataLimitValue

Requires:

MX: 6.3+

Cellular Data Warning

Controls whether the device user or an app running on the device can specify a threshold for cellular data usage that triggers a warning.

Shown if: Cellular Data State is set to "Turn On"

Parm Name: CellularDataWarning

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	All	MX: 6.3+
1	Set new warning	Enables a data limit warning threshold (in MB) to be specified.	All	MX: 6.3+

Set Cellular Data Warning

Used to specify a threshold (in MB per month) for cellular data usage after which a warning is displayed on the device.

Parm value input rules:

Integer from 5-1048576 (5MB-1TB) corresponding to the data usage limit

Shown if: Cellular Data State is set to "Turn On" and Cellular Data Warning is set to "Set new warning"

Parm Name: CellularDataWarningValue

Requires:

MX: 6.3+

Background Data Enable/Disable

Used to control whether the device user has access to the Background Data option on the device. When Disabled, Background Data cannot be turned on or off programmatically or by the device user.

The Background Data Option determines whether applications that are not in the foreground should be permitted to maintain a data connection over the cellular network (if they are capable of doing so). For example, some email applications continue to download messages while other apps are active or when the device's screen is turned off. The convenience of having data ready "when it's asked for" must be considered when planning for cellular bandwidth utilization and weighed against the potential for data overage and roaming costs.

Parm Name: BackgroundDataUsage

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	All	OSX: 4.4+ MX: 4.4+
1	Enable	Enables Background Data to be used on the device and its state (active/inactive) to be controlled programmatically or by the device user.	All	OSX: 4.4+ MX: 4.4+
2	Disable	Disables Background Data from being used on the device and prevents its state (active/inactive) from being controlled programmatically or by the device user.	All	OSX: 4.4+ MX: 4.4+

Option

Name

Description

Device Group

Requires

Do not change

This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.

All

OSX: 4.4+

MX: 4.4+

Enable

Enables Background Data to be used on the device and its state (active/inactive) to be controlled programmatically or by the device user.

All

OSX: 4.4+

MX: 4.4+

Disable

Disables Background Data from being used on the device and prevents its state (active/inactive) from being controlled programmatically or by the device user.

All

OSX: 4.4+

MX: 4.4+

Background Data Blocking On/Off

This is the On/Off switch for blocking background data communication. When On, apps will be allowed to use the cellular data connection only when in the foreground, and blocked at all other times. When Off, all background-capable apps will be allowed to maintain a data connection whenever they're running, even if they're not in the foreground.

Shown if: Background Data Usage is set to "Enable"

Parm Name: BackgroundDataState

Option	Name	Description	Device Group	Requires
0	Do not change	This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.	All	OSX: 1.3+ MX: 4.3+
1	Turn On	Prevents background-capable apps from using the cellular data connection when the app is not in the foreground.	All	OSX: 1.3+ MX: 4.3+
2	Turn Off	Allows background-capable apps to use the cellular data connection when in the background or the foreground.	All	OSX: 1.3+ MX: 4.3+

Option

Name

Description

Device Group

Requires

Do not change

This value (or the absence of this parm from the XML) will cause no change to CellularMgr settings; any previously selected setting will be retained.

All

OSX: 1.3+

MX: 4.3+

Turn On

Prevents background-capable apps from using the cellular data connection when the app is not in the foreground.

All

OSX: 1.3+

MX: 4.3+

Turn Off

Allows background-capable apps to use the cellular data connection when in the background or the foreground.

All

OSX: 1.3+

MX: 4.3+

Examples

Turn Off Data Roaming and Background Data


<wap-provisioningdoc>
    <characteristic type="CellularMgr" version="4.3" >
        <parm name="DataRoamingState" value="2"/>
        <parm name="BackgroundDataState" value="2"/>
    </characteristic>
</wap-provisioningdoc>