Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

OMA Provisioning Adapter API

From Wiki
Jump to: navigation, search
Article Metadata
Code ExampleCompatibility
Created: ltomuta (17 Jun 2007)
Last edited: hamishwillee (30 May 2013)

Note.pngNote: :This API is not part of the public SDK. It can be found in the SDK API Plug-in.

This document provides a description of how to use the S60 Client Provisioning framework to manage device settings over SMS and describes how the OMA CP framework should be used from the CP plug-in adapter point of view.

CP Framework is designed to create CP adapters and pass on characteristics to all the adapters and parameters associated with the character will be sent only to the adapter which supports that Character.

OMA Provisioning Handler saves the message in Inbox by using services from OMA Provisioning Engine. OMA Provisioning engine in turn uses ECom plug-ins to deliver the settings to different applications as required. The adapter which supports the character will store all the parameters associated with the character as intermediate data in the VisitL( ) method. All the parameters (intermediate data) will be stored in the specific application in SaveL( ) method of the adapter call by CP framework.

Use cases

Manage device settings over SMS

Example code

Steps for creating the adapter

For CP Adapter to work we need to derive the adapter from CWPAdapter and implement the below mentioned pure virtual functions

ItemCount() 	-> Returns the number of the summary lines to be shown in Incoming message.
SummaryTitle() -> Returns the title of the nth summary line.
SummaryText() ->Returns the text of the nth summary line
SaveL() -> Saves the settings received from the message as per the requirement
CanSetAsDefault()-> Returns ETrue if the adapter can set the settings as default.
SetAsDefaultL() ->Adapter sets the settings as default.
DetailsL() ->Calls the pair visitor for each detail line of an item.
VisitL (CWPCharacteristics&) -> Called for each character found.
VisitL (CWPParameters&) -> Called for each parameter found.
VisitLinkL() -> Visits the adapter and checks from Parameters if the link
is targeted to it and acts according to that.

Header Files:

#include <CWPCharacteristic.h>
#include <CWPparameter.h>

Link against:

LIBRARY euser.lib ECom.lib


CAPABILITY NetworkServices LocalServices Location ReadUserData WriteUserData
ReadDeviceData WriteDeviceData SwEvent UserEnvironment NetworkControl

When a WAP Push Message is opened from the inbox, VisitL (CWPCharacteristic& aCharacteristic) function gets called. It Checks for the characteristic type sent by the provider. The characteristic type supported by the adapter should be accepted in this function by calling AcceptL() method on the Characteristic received.

For example in the code below “Application” and “Authtype” characteristic type are being checked for.

void CTestAdapter::VisitL( CWPCharacteristic& aCharacteristic )
TInt type = aCharacteristic.Type();
if ( type == KWPApplication )
aCharacteristic.AcceptL(*this );
if (type ==KWPAppAuth)
aCharacteristic.AcceptL(*this );

Once the characteristic is accepted, the parameters of the specific characteristic type will be delivered to the adapter in VistitL (CWParameter& aparameter).

void CTestAdapter::VisitL( CWPParameter& aParameter ) 
switch( aParameter.ID() )
// read these parameters
case EWPParameterAppID:

Check can be performed in this function if the characteristics are meant for application or not, for example, by comparing it with Application ID or any other parameter as shown below. (Here D1 is the application ID).

case EWPParameterAppID:
iVal = aParameter.Value();
If (iVal==Kval) //Check if App ID is for our application

The settings received in VistitL(CWParameter& aparameter) are stored in the intermediate storage for example in an array and later when settings are saved from the Inbox write the settings in File, database, etc., in SaveL depending on the requirement.

void CTestAdapter::SaveL(TInt aItem)
//Check is performed for confirmation that the settings are meant for our application.
if (iCheck)
TBuf<100> array;
CLogger::Log(array); //Writing the settings into File.

First perform a check for the characteristic type and if it is “Application”, accept the parameters of that characteristic type and save the Setting only if Application ID matches with the App ID Param value. i.e. don’t save the setting if the “APPID” is other than “D1”.

The ItemCount () returns the number of items that can be shown when the message is opened from the Inbox.

TInt CTestAdapter::ItemCount() const
return iArray->Count();

Depending upon the Item count returned, the summary text methods are called so many times. SummaryText method returns the values which are displayed when the message is opened from the Inbox.

const TDesC16& CTestAdapter::SummaryText(TInt aIndex) const
return (iArray->At(aIndex)->Value());

SummaryTitle method returns the Title to be displayed when the message is opened from the inbox.

const TDesC16& CTestAdapter::SummaryTitle(TInt /*aIndex*/) const
// The title is always the same.
_LIT(KTitle,"Test Adapter");
return KTitle;

Below are the sample WBXML settings that can be sent to the adapter and the corresponding XML is also shown. XML to WBXML is conversion is performed through nowsms client.

<wap-provisioningdoc version="1.0">
<characteristic type="APPLICATION">
<parm name="APPID" value="D1"/>
<parm name="NAME" value="Test Adapter"/>
<parm name="ADDR" value=""/>
<parm name="TO-NAPID" value="INTERNET"/>
</wap-provisioningdoc version="1.0">

The XML DTD defines two elements. A CHARACTERISTIC element and a PARM element. The PARM element is used to provide values for the individual parameters, while the CHARACTERISTIC element is used to group parameters into logical entities that are related to a specific characteristic of the configuration space.

Example project