Each CPClient instance registers the name com.intel.cpclient.server on the session D-Bus bus. On start up, the server exposes a single D-Bus object, /com/intel/cpclient that implements a single interface, com.intel.cpclient.Manager. com.intel.cpclient.Manager exposes a method called CreatePushMessage. OMA CP UI applications should call this method when they receive a new OMA CP WAP Push message, passing it the binary contents of the message as an argument. If the message is valid, the CPClient will create a new object returning the path of this object to the calling UI as a return value. This new object implements a second interface called, com.intel.cpclient.PushMessage that supports 3 methods, Apply, GetProps and Close. These methods allow the UI to apply the OMA CP message, to determine the properties of the message, i.e. the settings it contains, the authentication method used, etc., and to delete the object, respectively. A simple example of using the d-Bus APIs in python is given below.
def parseWP(binaryMessage, pinCode): manager = dbus.Interface(bus.get_object('com.intel.cpclient.server', '/com/intel/cpclient'), 'com.intel.cpclient.Manager') path = manager.CreatePushMessage(binaryMessage) try: pm = dbus.Interface(bus.get_object('com.intel.cpclient.server', path), 'com.intel.cpclient.PushMessage') pm.Apply(pinCode) print "Message Applied" except dbus.exceptions.DBusException, err: print "Unable to process WAP Push message: ", err finally: pm.Close()
A complete list of all the d-Bus methods exposed by the CPClient are presented below.
Methods defined by com.intel.cpclient.Manager
path CreatePushMessage ( array message )
Creates a com.intel.cpclient.PushMessage object from an OMA CP WAP Push message.
This method extracts and parses the WAP Push headers and the WBXML encoded OMA CP document contained within the array of bytes passed to it by the caller. A new d-Bus object is created to represent this decoded message, the path of which is returned to the caller. If this message is corrupt or a problem is encountered while parsing it, an error is returned and the d-Bus object is not created. The new d-Bus object implements the com.intel.cpclient.PushMessage message and can be used to inspect and apply the contents of the WAP Push message.
Please note that this function does not cause any of the settings contained in the WAP Push message to be applied, i.e., passed to Provman. It merely decodes the message and creates a new object that allows the caller to inspect the message and apply it if he sees fit.
message the binary contents of an OMA CP WAP Push message including the WSP headers.
- the path of the newly created d-Bus object.
com.intel.cpclient.Error.Died The CPClient was killed before the GetVersion command could be executed. com.intel.cpclient.Error.OOM Not enough memory was available to process the message. com.intel.cpclient.Error.ParseError The contents of the message are not well formed. com.intel.cpclient.Error.IO Unable to register the new object with the session d-Bus.
string GetVersion ( )
Returns the version number of the CPClient.
- Returns the current version number as a string.
com.intel.cpclient.Error.Died The CPClient was killed before the GetVersion command could be executed.
void ParseCP ( string filename )
Test function to Parse and apply the contents of an OMA CP XML file.
This method is purely intended for testing purposes. It loads and parses the XML (not WBXML) and applies all the settings contained within that file. The message is applied directly without any authentication. As the IMSI card is not used during authentication, the Provman session used to provision the document's settings is initiated with the empty string, informing Provman that it should associate any SIM specific settings with the SIM card present in the first modem reported by the device.
filename The full path to the OMA CP XML file to be processed.
com.intel.cpclient.Error.Died The CPClient was killed before the GetVersion command could be executed. com.intel.cpclient.Error.OOM Not enough memory was available to process the message. com.intel.cpclient.Error.ParseError The contents of the message are not well formed. com.intel.cpclient.Error.LoadFailed Unable to load filename.
Methods defined by com.intel.cpclient.PushMessage
void Apply ( string pin_code )
Applies the settings contained within the Push Message object.
This method applies all the settings contained inside the Push Message. It does this by generating a set of Provman settings and meta data values, initiating a Provman session and passing all the generated settings and values to Provman to be applied.
The Push Message object is authenticated before the settings are applied. Most authentication methods require a PIN code, which needs to be passed by the CP UI application as an argument to this method. If the security method used by the message does not require a pin code to authenticate, i.e., it is using NETWPIN authentication, an empty string should be passed. The UI can determine whether or not a PIN code is required by calling the Push Message's GetProps method. If authentication fails, the UI can call the Apply method again with a different PIN code. No limits are placed on the number of attempts that can be made. If such a limit is required it needs to be implemented in the UI.
All OMA CP security mechanisms apart from no security are supported. Messages that contain no security information cannot be applied. Requirements to not support certain security mechanisms, such as NETWPIN, need to be implemented in the OMA CP UI application. The UI application can invoke the GetProps method of the Push Message object to determine the security mechanism used by that object.
Once a message has been successfully applied, the PushMessage object stays in existence, until its Close Method is called. However, any further calls to Apply will result in an error.
pin_code a string containing the pin_code to authenticate the message.
com.intel.cpclient.Error.Died The CPClient was killed before the Apply command could be executed. com.intel.cpclient.Error.Cancelled The CPClient was killed before the Apply command could be completed. com.intel.cpclient.Error.OOM Not enough memory was available to process the message. com.intel.cpclient.Error.IO Unable to communicate with Provman. com.intel.cpclient.Error.Denied The message could not be authenticated or the caller did not create the message. com.intel.cpclient.Error.AlreadyApplied The message has already been applied. com.intel.cpclient.Error.NotFound The specified Push Message does not exist
void Close ( )
Discards the Push Message Object.
The message is discarded and any settings it contains will be lost if the message has not already been applied.
com.intel.cpclient.Error.Denied The caller is not the creator of the Push Message object. com.intel.cpclient.Error.NotFound The specified Push Message does not exist
dictionary GetProps ( string pin_code )
Retrieves the properties of the Push Message.
This method returns a dictionary containing one instance of each of the key/value pairs described in the table below.
|SecType||The type of security used by the Push Message object||NONE, USERPIN, NETWPIN, USERNETWPIN, USERPINMAC|
|PinRequired||Indicates whether or not a PIN code is required to authenticate this PushMessage||Yes, No|
|StartSessionsWith||A list of DM servers with which the device should initiate DM sessions after it has applied the Push Message||A comma separated list of DM server IDs.|
|Settings||Provides an overview of the settings contained within the Push Message||A '/' separated list of setting types. The following types are defined: proxy, apn, bookmarks, email, mms, omadm, omads|
com.intel.cpclient.Error.Died The CPClient was killed before the GetProps command could be executed. com.intel.cpclient.Error.Denied The caller is not the creator of the Push Message object. com.intel.cpclient.Error.NotFound The specified Push Message does not exist