GPRS Manager

EMDK For Xamarin - 2.5

Overview

The GprsMgr administers Access Point Name (APN) settings for the General Packet Radio Service (GPRS) network used by the device. In general terms, an APN acts as a bridge between a device's carrier network and the internet or other packet data networks, and stores preferences for security, multimedia messaging (MMS) and other services to which the device might require access.

Main Functionality

  • Create multiple APNs
  • Set default APN
  • Remove or replace old APNs
  • Remove all APNs
  • Define Custom APN parameters, including:
    • Mobile Country Code
    • MMS Port, Proxy and Center
    • Mobile Network Code
    • Custom Port, Proxy, Server and Type

About WWAN Communications

Devices equipped with Wireless Wide Area Network (WWAN) or cellular data capabilities can support one or more of the following WWAN technology types:

  • GPRS is a modulation method used to enable data communications over Global System for Mobile Communications (GSM) cellular networks. A key characteristic of GPRS networks is the Subscriber Identity Module (SIM) card, which securely stores the mobile subscriber identity (IMSI) number and its related key, which are used to identify and authenticate subscribers. Inserting a SIM card allows basic cellular service (including voice and text messaging over a GSM network) to be established. However, cellular data services may require additional configuration that cannot be performed based solely on the information provided by the SIM card.

  • Code Division Multiple Access (CDMA) is a modulation method used in many mobile phone standards such as cdmaOne, CDMA2000 (the 3G evolution of cdmaOne), and WCDMA. A key characteristic of CDMA networks is its lack of a SIM Card, which often often requires activation through a manual process between the device user and the cellular provider to configure voice, text messaging and cellular data services.

  • LTE (Long-Term Evolution, 4G) is a modulation method that can extend CDMA and GPRS into 4G. As with GPRS, LTE networks use a SIM card to securely store the mobile subscriber identity (IMSI) number and its related key, which are used to identify and authenticate subscribers. LTE SIM cards contain additional information that allows cellular data services to be activated without the manual configuration process associated with CDMA.

Custom APN Settings

Devices operating on GSM networks and that use GPRS cellular data sometimes require additional information not provided by the SIM card. This information is often referred to as the Access Point Name (APN), but can include more than simply the name of an access point. An APN identifies the packet data network (PDN) to which a mobile data user requires access and also sometimes defines other available services. Configuring a device to use a particular APN generally requires the name of the Access Point plus a user name and password to connect via that Access Point.

A GPRS-equipped Android device must generally have a suitable APN defined for each GPRS cellular data network that will be used. If a single GPRS cellular data network will be used, only one APN must be defined on the device. But if the device will operate on multiple GPRS cellular data networks, for example to enable roaming across multiple geographical regions, multiple APNs must be defined.

The Custom APN parameters in the GprsMgr permit a device administrator to create multiple APNs to match the settings required for a variety carrier networks. This allows a single GPRS-enabled WWAN device and SIM card to establish a cellular data connection on disparate cellular networks simply by changing the APN.

Note: The Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card. Zebra recommends testing carrier-specified APN settings on a working device and SIM card before general deployment.

APN Action

Contains the list of actions that can be performed on an APN.

Parm Name: GprsAction

Option Name Description Requires
1 Add/replace named APN Causes the specified APN to be added (replacing the existing APN, if any).

MX: 4.1.1+

Android API Level: 16+

2 Remove existing named APN Causes the specified APN to be removed.

MX: 4.1.1+

Android API Level: 16+

3 Remove all existing APNs Causes all existing APNs to be removed.

MX: 4.1.1+

Android API Level: 16+

APN Name

Used to specify the name by which the APN will be known in the device. All APN names in a device must be unique. Once an APN with a given name has been added, that name can be used to Remove that APN definition from the device or to Replace the definition of that APN with a new definition.

Note: This parm does not specify the Access Point Name on the network, it only specifies the name by which the APN will be known and referred to by the device. The network name of the APN is specified in the Access Point parameter elsewhere in this document.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" or "Remove existing named APN"

Parm Name: ApnName

Requires:

  • MX: 4.1.1+
  • Android API Level: 16+

Replace If Exists

Used to specify whether an existing APN should be replaced on the device if a new one of the same name is created. If "False" is selected, any attempt to replace an existing APN on the device will fail and generate an error in the Result XML.

Shown if: The APN Action is "Add/replace named APN"

Parm Name: ReplaceIfExisting

Option Name Description Requires
1 true Causes an APN already defined on the device to be replaced by a new one of the same name.

MX: 4.1.1+

Android API Level: 16+

0 false Prevents an existing APN from being replaced if a new one of the same name is created.

MX: 4.1.1+

Android API Level: 16+

Make Default APN

Used to specify whether a new APN being added should be made the default, or the most preferred APN. When connecting automatically, the system will attempt to use the default APN, if available, before considering others in the list.

Shown if: The APN Action is "Add/replace named APN"

Parm Name: MakeDefault

Option Name Description Requires
1 true Causes a new APN to be set as the default APN.

MX: 4.1.1+

Android API Level: 16+

0 false Prevents any change to the current default APN.

MX: 4.1.1+

Android API Level: 16+

Access Point

Used to specify the name by which the desired APN is known on the network. This value is generally obtained from the GPRS carrier that provides the APN (for example, "wap.cingular" is the name of an APN commonly used by AT&T). This is relevant only when the value chosen for the GPRS carrier was "Custom" since otherwise the APN values for the pre-defined APN will be provided automatically based on the selected GPRS carrier.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: ATTAccessPoint, TMobileAccessPoint, CustomAccessPoint

Requires:

  • MX: 4.1.1+
  • Android API Level: 16+

User Name

Used to specify a User Name to authenticate on the APN being added. The value is generally obtained from the GPRS carrier that provides the APN (for example, "WAP.CINGULARGPRS.COM" is the User Name commonly used by AT&T to authenticate on its APNs). This is relevant only when the value chosen for GPRS Carrier was "Custom" since otherwise the APN values for the predefined APN will be provided automatically based on the selected GPRS carrier.

Note: If an empty (length of 0) value is specified, no User Name will be used. This should generally be done only if the GPRS carrier indicates that authentication with a user name is not required for a given APN.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: AttUserName, TmobileUserName, CustomUserName

Requires:

  • MX: 4.1.1+
  • Android API Level: 16+

Password

Used to specify a Password that to authenticate on the APN being added. The value is generally obtained from the GPRS carrier that provides the APN (for example, "CINGULAR1" is the password commonly used by AT&T to authenticate on its APNs). This is relevant only when the value chosen for GPRS Carrier was "Custom" since otherwise the APN values for the predefined APN will be provided automatically based on the selected GPRS carrier.

Note: If an empty (length of 0) value is specified, no Password will be used. This should generally be done only if the GPRS carrier indicates that authentication with a password is not required for a given APN.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: ATTPassword, TMobilePassword, CustomPassword

Requires:

  • MX: 4.1.1+
  • Android API Level: 16+

Custom MCC

Used to specify the Mobile Country Code (MCC). Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomMcc

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom MMSC

Used to specify the Multimedia Messaging Service Center (MMSC), the store-and-forward server for the carrier. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomMmsc

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom MMS Port

Used to specify the Multimedia Messaging Service (MMS) Port. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomMmsPort

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom MMS Proxy

Used to specify the Multimedia Messaging Service (MMS) Proxy. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomMmsProxy

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom MNC

Used to specify the Mobile Network Code (MNC). Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomMnc

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom Port

Used to specify a custom port. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomPort

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom Proxy

Used to specify a custom proxy. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomProxy

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom Server

Used to specify the custom server. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomServer

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Custom Type

Used to specify a custom type. Custom parameters are "pass-through" fields; they hold sets of values in various combinations for the purpose of easily switching from one APN to another to adapt to various cellular networks. The rules for these values and settings vary by region and SIM card.

Zebra recommends testing carrier-specified APN settings on a working device and SIM card before deployment.

Parm value input rules:

  • String from 0 - 255 characters

Shown if: The APN Action is "Add/replace named APN" and the GPRS Carrier is "Custom"

Parm Name: CustomType

Requires:

  • MX: 6.1+
  • Android API Level: 19+

Examples

Add AT&T GPRS APN


<wap-provisioningdoc>
    <characteristic type="GprsMgr" version="4.2" >
    <parm name="GprsAction" value="1"/>
    <parm name="GprsCarrier" value="1"/>
        <characteristic type="gprs-details">
            <parm name="ApnName" value="myATT"/>
            <parm name="ReplaceIfExisting" value="1"/>
            <parm name="MakeDefault" value="1"/>
        </characteristic>
        <characteristic type="att-details">
            <parm name="AttAccessPoint" value="wap.cingular"/>
            <parm name="AttUserName" value="WAP@CINGULARGPRS.COM"/>
            <parm name="AttPassword" value="CINGULAR1"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Add T-Mobile GPRS APN


<wap-provisioningdoc>
    <characteristic type="GprsMgr" version="4.2" >
    <parm name="GprsAction" value="1"/>
    <parm name="GprsCarrier" value="2"/>
        <characteristic type="gprs-details">
            <parm name="ApnName" value="myTMobile"/>
            <parm name="ReplaceIfExisting" value="0"/>
            <parm name="MakeDefault" value="1"/>
        </characteristic>
        <characteristic type="tmobile-details">
            <parm name="TmobileAccessPoint" value="internet3.voicestream.com"/>
            <parm name="TmobileUserName" value=""/>
            <parm name="TmobilePassword" value=""/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Add Custom GPRS APN


<wap-provisioningdoc>
    <characteristic type="GprsMgr" version="4.2" >
    <parm name="GprsAction" value="1"/>
    <parm name="GprsCarrier" value="0"/>
        <characteristic type="gprs-details">
            <parm name="ApnName" value="myCustom"/>
            <parm name="ReplaceIfExisting" value="1"/>
            <parm name="MakeDefault" value="1"/>
        </characteristic>
        <characteristic type="custom-details">
            <parm name="CustomAccessPoint" value="apn"/>
            <parm name="CustomUserName" value="user"/>
            <parm name="CustomPassword" value="pass"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>  

Remove Existing Named APN


<wap-provisioningdoc>
    <characteristic type="GprsMgr" version="4.2" >
        <parm name="GprsAction" value="2"/>
        <characteristic type="gprs-details">
            <parm name="ApnName" value="myTMobile"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Remove All Existing APNs


<wap-provisioningdoc>
    <characteristic type="GprsMgr" version="4.2" >
        <parm name="GprsAction" value="3"/>
    </characteristic>
</wap-provisioningdoc>

Examples

Queries

Get Air Plane Mode

Input


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" >
        <parm-query name="AirPlaneMode"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" version="4.3" >
        <parm name="AirPlaneMode" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Get Touch Panel

Input


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" >
        <parm-query name="TouchPanel"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" version="4.3" >
        <parm name="TouchPanel" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Get Safe Mode

Input


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" >
        <parm-query name="SafeMode"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" version="4.3" >
        <parm name="SafeMode" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Get Auto Screen Lock Option

Input


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" >
        <parm-query name="AutoScreenLockOption"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" version="4.3" >
        <parm name="AutoScreenLockOption" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Get Auto Screen Lock State

Input


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" >
        <parm-query name="AutoScreenLockState"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PowerKeyMgr" version="4.3" >
        <parm name="AutoScreenLockState" value="1"/>
    </characteristic>
</wap-provisioningdoc>