How to port guide: control panel plug-ins

The purpose of this document is to help migrate control panel plug-ins to Symbian OS v9.1 and later; for which the OS architecture supports both old style plug-ins (implemented as polymorphic DLLs) as well as new style plug-ins, (implemented as applications).

• Introduction

• Supported features and pre-requisites

• Source code changes

• Resource and MMP file changes

Different control panel plug-ins are likely to need different capabilities in order to change the phone's configuration. Rather than each plug-in running in a parent process with a dangerously large set of capabilities, each plug-in should run in its own process, so that each can have the minimal set of capabilities that it requires. For this reason, the decision was made to convert all existing control panel plug-ins, which are implemented as polymorphic DLLs, into standard applications, but with a special registration file. This registration file is used by the application server to distinguish the plug-in from a normal application.

• The control panel application should be located in \sys\bin\<appname.exe>. Only executables (EXEs and DLLs) should exist in \sys\bin\.

• The control panel application's UI resource file should be located in \Resource\apps\<appname.rsc>.

• There should be a registration resource file for each control panel application in

  \private\10003a3f\apps\ if it is either on the emulator or built into the ROM, or

  \private\10003a3f\import\apps\ if it is installed via Software Install

Each existing control panel plug-in has only one exported function, which is called by default. To convert the plug-in into an application, the four classes which are required components of any application must be provided, for example:

• class CExampleAppView : public CCoeControl

• class CExampleAppUi : public CEikAppUi

• class CExampleDocument : public CEikDocument

• class CExampleApplication : public CEikApplication

Note that each System GUI provides its own application, app UI and document base classes.

The executable's entry points need to be modified as follows:

LOCAL_C CApaApplication* NewApplication()
    {
 return new CExampleApplication;
    } 
GLDEF_C TInt E32Main()
    {
    return EikStart::RunApplication(NewApplication);
    } 
#if defined(__WINS__) && !defined(EKA2) 
GLDEF_C TInt E32Dll(TDllReason)
    {
    return KErrNone;
    } 
EXPORT_C TInt WinsMain(TDesC* aCmdLine)
    {
    return EikStart::RunApplication(NewApplication, aCmdLine);
    } 
#endif

For details on converting existing control panel plug-ins into applications, refer to the migration document: How to port guide: apps to exes.