Sorry, you need to enable JavaScript to visit this website.

Feedback

Your feedback is important to keep improving our website and offer you a more reliable experience.

CPClient

The CPClient is a middleware component that provides support for wireless provisioning of application and connection settings and exposes d-Bus APIs. It implements the OMA Client Provisioning (CP) protocol controlling application and connection settings. It works with Provman, which directly modifies application and connection settings.

OMA CP describes a very flexible and powerful mechanism of provisioning connection settings. Settings for proxies and access points are configured separately. Multiple connectoids (access points or proxies) can be be associated with each provisioned application and multiple access points can be associated with each proxy. Connection fallback is also supported. Connectoids, referenced by applications and proxies, are listed in order of priority. If a connection cannot be made via the highest priority connectoid, the subsequent is tried.

This flexible connection model is not supported in today's smart phones. Typically, such phones group proxy and access point settings together and usually require only two sets of 3G connection settings (per SIM), one for general Internet access and one for MMS. For these reasons, the CPClient only implements a small subset of OMA CP's connection rules and parameters. A list of the supported parameters is presented in the table below:

OMA CP Parameter Occurrence Description Permissible Values
Supported NAPDEF Parameters
NAPDEF/NAPID 1 Unique identifier for the access point Any string
NAPDEF/NAME 0 or 1 Friendly name for the access point Any string
NAPDEF/BEARER 1 Indicates the bearer. Must be specified as this parameter is mandatory for OMA CP but the CPClient does not currently use it GSM-CSD, GSM-GPRS
NAPDEF/INTERNET 0 or 1 Indicates the access point is generic. See below. N/A
NAPDEF/NAPADDRESS 1 The address of the access point. Any string
NAPDEF/NAPAUTHINFO 0 or 1 Characteristic used to specify the security credentials of a NAPDEF  
NAPDEF/NAPAUTHINFO/AUTHTYPE 1 Type of authentication used. Must be specified as this parameter is mandatory for OMA CP but the CPClient does not currently use it PAP or CHAP
NAPDEF/NAPAUTHINFO/AUTHNAME 0 or 1 User name Any string
NAPDEF/NAPAUTHINFO/AUTHSECRET 0 or 1 Password Any string
Supported PXLOGICAL/PXPHYSICAL Parameters
PXLOGICAL/PXPHYSICAL 1 Characteristic that contains information about the physical proxy  
PXLOGICAL/PXPHYSICAL/PXADDR 1 Proxy address Any string (typically and IP address)
PXLOGICAL/PXPHYSICAL/PORT 0 or 1 Characteristic containing information about the proxy's type and port  
PXLOGICAL/PXPHYSICAL/PORT/PORTNBR 0 or 1 Proxy’s port number An integer
PXLOGICAL/PXPHYSICAL/PORT/SERVICE 0 or 1 Proxy's type http, https or ftp
Supported MMS Parameters
APPLICATION/APPID 1 Identifies the application characteristic as a group of MMS settings. w4
APPLICATION/ADDR 1 Address of the MMS service centre A URL
APPLICATION/TO-PROXY 0 or 1 Reference to a logical proxy defined elsewhere in the OMA CP document. The PROXY-ID of a PXLOGICAL
APPLICATION/TO-NAPID 0 or 1 Reference to a NAPDEF defined elsewhere in the OMA CP document. The NAPID of a NAPDEF

If you are familiar with the OMA CP specifications you will notice that many of the OMA CP connection parameters are missing. This reflects the fact that only a subset of the OMA CP connection rules are implemented by the CPClient. It should be noted however, that the CPClient's OMA CP document parser implements almost all the rules, characteristics and parameters described in the OMA CP specifications. It accepts an OMA CP document and generates a complete OMA CP model in memory. However, the code inside the CPClient that maps this internal model to Provman keys only uses the parameters listed in the table above. It ignores all the other parameters even though they are present in the in-memory model. This is mentioned here to publicise the fact that it would be possible to use the code in lib directory of the CPClient to create an OMA CP implementation more faithful to the standards, if anyone ever felt the need to do so.

The specific restrictions that exist are discussed in the paragraphs below.

The CPClient groups settings for proxies and access points together. The identifiers used to represent a group of connection settings are derived from the NAPID of the NAPDEF that specifies the access point. For example, the CPClient generates the following Provman keys

/telephony/contexts/nd1/apn = nap.address
/telephony/contexts/nd1/password = password
/telephony/contexts/nd1/name = test
/telephony/contexts/nd1/username = username
/telephony/contexts/nd1/http_proxy = 127.0.0.1:8080

from the OMA CP document below

<wap-provisioningdoc version="1.0">
        <characteristic type="NAPDEF">
                <parm name="NAME" value="test" />
                <parm name="NAPID" value="nd1" />
                <parm name="NAP-ADDRESS" value="nap.address" />
                <parm name="BEARER" value="GSM-GPRS" />
                <parm name="NAP-ADDRTYPE" value="APN" />
                <characteristic type="NAPAUTHINFO">
                        <parm name="AUTHTYPE" value="PAP" />
                        <parm name="AUTHNAME" value="username" />
                        <parm name="AUTHSECRET" value="password" />
                </characteristic>
        </characteristic>

        <characteristic type="PXLOGICAL">
                <parm name="NAME" value="pxtest" />
                <parm name="PROXY-ID" value="logical" />
                <characteristic type="PXPHYSICAL">
                        <parm name="PHYSICAL-PROXY-ID" value="physical" />
                        <parm name="PXADDR" value="127.0.0.1" />
                        <parm name="TO-NAPID" value="nd1" />
                        <characteristic type="PORT">
                                <parm name="PORTNBR" value="8080" />
                        </characteristic>
                </characteristic>
        </characteristic>
</wap-provisioningdoc>

Binding application settings to connection settings is not supported. Neither is connection fallback. TO-PROXY and TO-NAPID references are ignored in all application characteristics apart from MMS (see below).

Two different types of connection settings are defined. Settings for MMS and generic settings for browsing the Internet. The first set of connection settings referenced directly or indirectly by the MMS first application characteristic are deemed to be MMS connection settings. The CPClient generates a different set of Provman keys for such settings. For example, the CPClient generates the following keys

/telephony/mms/proxy = 127.0.0.1:8080
/telephony/mms/apn = nap.address
/telephony/mms/mmsc = http://mms.myoperator
/telephony/mms/name = test

for the OMA CP document below.

<wap-provisioningdoc version="1.0">
        <characteristic type="NAPDEF">
                <parm name="NAME" value="test" />
                <parm name="NAPID" value="nd1" />
                <parm name="NAP-ADDRESS" value="nap.address" />
                <parm name="BEARER" value="GSM-GPRS" />
                <parm name="NAP-ADDRTYPE" value="APN" />
        </characteristic>

        <characteristic type="PXLOGICAL">
                <parm name="NAME" value="proxy" />
                <parm name="PROXY-ID" value="logical" />
                <characteristic type="PXPHYSICAL">
                        <parm name="PHYSICAL-PROXY-ID" value="physical" />
                        <parm name="PXADDR" value="127.0.0.1" />
                        <parm name="TO-NAPID" value="nd1" />
                        <characteristic type="PORT">
                                <parm name="PORTNBR" value="8080" />
                        </characteristic>
                </characteristic>
        </characteristic>

        <characteristic type="APPLICATION">
                <parm name="APPID" value="w4" />
                <parm name="TO-PROXY" value="logical" />
                <parm name="ADDR" value="http://mms.myoperator" />
        </characteristic>

</wap-provisioningdoc>

Note that the settings are stored under /telephony/mms and not /telephony/contexts.

Connection settings associated with the MMS application cannot normally be used by other applications to browse the Internet. If, for some reason, you wish to use the same connection settings for MMS and Internet browsing you need to set the INTERNET parameter in the NAPDEF characteristic. This will cause two groups of settings to be created, one for MMS and one for Internet, e.g., adding <param name="INTERNET /> to the NAPDEF above would cause the following keys to be generated.

/telephony/contexts/nd1/apn = nap.address
/telephony/contexts/nd1/name = test
/telephony/contexts/nd1/http_proxy = 127.0.0.1:8080
/telephony/mms/proxy = 127.0.0.1:8080
/telephony/mms/apn = nap.address
/telephony/mms/mmsc = http://mms.myoperator
/telephony/mms/name = test

Note the proxy is used for both set of connection settings. If this is not what you want you will need to maintain separate NAPDEFS for MMS and Internet settings.

Only the first valid physical proxy inside a logical proxy is used. All others are ignored.

Only three types of proxies are supported, HTTP, HTTPS and FTP. The proxy type is deduced from the service parameter if specified or in the cases where it is not from the port number. Unknown port numbers maps to HTTP.

To specify multiple proxy types for a 3G connection multiple PXLOGICALS must be used. Only a single instance of each type of proxy can be associated with an access point (NAPDEF). For example, if the document contains multiple PXPHYSICAL characteristics that associate a HTTP proxy with a single NAPDEF, the first proxy will be used and all subsequent proxies will be ignored. To clarify, the OMA CP document below,

<wap-provisioningdoc version="1.0">
        <characteristic type="NAPDEF">
                <parm name="NAME" value="test" />
                <parm name="NAPID" value="nd1" />
                <parm name="NAP-ADDRESS" value="nap.address" />
                <parm name="BEARER" value="GSM-GPRS" />
                <parm name="INTERNET"/>
                <parm name="NAP-ADDRTYPE" value="APN" />
        </characteristic>

        <characteristic type="PXLOGICAL">
                <parm name="NAME" value="proxy" />
                <parm name="PROXY-ID" value="logical" />
                <characteristic type="PXPHYSICAL">
                        <parm name="PHYSICAL-PROXY-ID" value="physical" />
                        <parm name="PXADDR" value="127.0.0.1" />
                        <parm name="TO-NAPID" value="nd1" />
                        <characteristic type="PORT">
                                <parm name="PORTNBR" value="8080" />
                        </characteristic>
                </characteristic>
                <characteristic type="PXPHYSICAL">
                        <parm name="PHYSICAL-PROXY-ID" value="physical2" />
                        <parm name="PXADDR" value="127.1.1.1" />
                        <parm name="TO-NAPID" value="nd1" />
                        <characteristic type="PORT">
                                <parm name="PORTNBR" value="8080" />
                                <parm name="SERVICE" value="https" />
                        </characteristic>
                </characteristic>
        </characteristic>

        <characteristic type="PXLOGICAL">
                <parm name="NAME" value="proxy2" />
                <parm name="PROXY-ID" value="logical2" />
                <characteristic type="PXPHYSICAL">
                        <parm name="PHYSICAL-PROXY-ID" value="physical" />
                        <parm name="PXADDR" value="127.2.2.2" />
                        <parm name="TO-NAPID" value="nd1" />
                        <characteristic type="PORT">
                                <parm name="PORTNBR" value="8080" />
                                <parm name="SERVICE" value="https" />
                        </characteristic>
                </characteristic>
        </characteristic>

        <characteristic type="PXLOGICAL">
                <parm name="NAME" value="proxy3" />
                <parm name="PROXY-ID" value="logical3" />
                <characteristic type="PXPHYSICAL">
                        <parm name="PHYSICAL-PROXY-ID" value="physical" />
                        <parm name="PXADDR" value="127.3.3.3" />
                        <parm name="TO-NAPID" value="nd1" />
                        <characteristic type="PORT">
                                <parm name="PORTNBR" value="8080" />
                                <parm name="SERVICE" value="https" />
                        </characteristic>
                </characteristic>
        </characteristic>

</wap-provisioningdoc>

generates the following Provman keys:

/telephony/contexts/nd1/apn = nap.address
/telephony/contexts/nd1/name = test
/telephony/contexts/nd1/http_proxy = 127.0.0.1:8080
/telephony/contexts/nd1/https_proxy = 127.2.2.2:8080

The important thing to note here is that the HTTPS proxy used is the one specified in the second PXLOGICAL. This is because we only support one PXPHYSICAL characteristic per PXLOGICAL. So even though the first PXLOGICAL contains a PXPHYSICAL that specifies a HTTPS proxy, this proxy is ignored, as it is specified in the second PXPHYSICAL. The third proxy is ignored as it occurs further down in the document and hence has a lower priority than the second.

ACCESS rules are not supported.

There are a number of restrictions placed on the provisioning of MMS settings.

Multiple sets of Internet access point/proxy combinations can be provisioned. However, only a single set of MMS connection settings are supported. This is evident from looking at the Provman keys above. So even though OMA CP documents can contain multiple MMS applications characteristics, the CPClient will only use the first of such characteristics that appears in the document.

In OMA CP, application characteristics can have multiple connectoids. However, the CPClient will only use the first connectoid it encounters in an MMS application characteristic, be it a NAPDEF or a PXLOGICAL. If it is a NAPDEF no proxy information will be used to access the MMSC. If the connectoid is a PXLOGICAL characteristic, the access point settings used to connect to the MMS server will be the those of the first NAPDEF associated with the first physical proxy of the PXLOGICAL. As only a single connectoid is used with an MMS characteristic, it follows that only a single proxy can be specified for use with MMS, this being the proxy specified in the first physical proxy of the logical proxy referenced by the MMS characteristic.

Project: