S60 3.2: System Startup Extension Plug-in API Specification

DN0645972
CONFIDENTIAL

©Nokia 2006
This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia. This material also contains confidential information, which may not be disclosed to others without the prior written consent of Nokia.

Nokia is a registered trademark of Nokia Corporation. S60 and logo is a trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other company and product names mentioned herein may be trademarks or tradenames of their respective owners.

Change History

Version

Date

Status

Description

1.1

30.06.2006

Approved

More detailed description and an example added.

1.0

06.06.2006

Approved

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API description
Use cases
API class structure
Using System Startup Extension Plug-in API
Implementing a system startup extension plug-in
Plug-in configuration
Error handling
Memory overhead
Extensions to the API
Glossary
Abbreviations
Definitions
References

 


Purpose

The purpose of System Startup Extension Plug-in API is to allow extending the startup process without having to modify S60 Starter Server. The system startup process and S60 Starter Server are described in more detail in reference documents [1] and [2].

The system startup can be customized by configuring the system startup configuration resource. Basically, the system startup configuration resource contains lists of the executables to be started in each phase of the startup process. Other custom actions besides starting executables can be added to the system startup configurations by implementing them in DLLs. The DLLs must implement System Startup Extension Plug-in API.

System startup extension plug-ins can be used to add small tasks to the startup process without the need to start a process to handle the tasks. For example, DB recovery is a task that does not necessarily require starting a process to handle the task, but it can be executed by a plug-in DLL. Restore factory settings operation is also such a task.

Another use of system startup extension plug-ins is starting those processes that cannot be started by simply creating the process by executable name and giving command line arguments. They may require connecting to some server or performing some other special processing to start. The code required for starting this kind of servers can be implemented in a system startup extension plug-in, which can then be added to the system startup configuration.

 


S60 or Symbian OS exceptions

System Startup Extension Plug-in API is valid from S60 release 3.2 onwards.

 


API description

System Startup Extension Plug-in API is an ECom API defining a virtual base class from which all system startup extension plug-in implementations must be derived. System startup extension plug-ins are optional - it is allowed to have zero system startup extension plug-in implementations in a system.

To add a system startup extension plug-in implementation as part of the system startup, it should be added to the system startup configuration resource using Startup List API (see reference document [3]). If a system startup extension plug-in implementation has not been included in the system startup configuration resource, it is not loaded or executed during the system startup.

System startup extension plug-ins should not be used to execute very time-consuming tasks, because that makes the overall startup time longer. The plug-ins are loaded into S60 Starter Server’s thread, so they also consume S60 Starter Server’s heap and stack space. Thus, when writing system startup extension plug-ins, performance and memory consumption issues should be considered carefully.

Because system startup extension plug-ins run in S60 Starter Server’s thread, they need to have enough capabilities, specifically the capability set of CAP_GENERAL_DLL. Due to security reasons, system startup extension plug-ins can only be loaded from the Z: drive.

 


Use cases

Using System Startup Extension Plug-in API means implementing a system startup extension plug-in.

 


API class structure

The class structure of System Startup Extension Plug-in API is shown in Figure 1.

Figure 1: Structure of system startup extension plug-in API

All system startup extension plug-in implementations should be derived from the CSystemStartupExtension base class. S60 Starter Server instantiates the plug-in implementation using ECom based on the plug-in implementation UID.

 


Using System Startup Extension Plug-in API

 


Implementing a system startup extension plug-in

To implement a system startup extension plug-in, derive a class from the CSystemStartupExtension base class and implement its ExecuteL and Cancel functions.

Example:

class CMyStartupExtensionPlugin : public CSystemStartupExtension
    {
    public:
        IMPORT_C static CMyStartupExtensionPlugin* NewL( TAny* aConstructionParameters );
        virtual ~CMyStartupExtensionPlugin();
        virtual void ExecuteL( TRequestStatus& aStatus, const TDesC& aParams );
        virtual void Cancel();
    private:
        CMyStartupExtensionPlugin( TAny* aConstructionParameters );
        void ConstructL();
    };

A DLL implementing a system startup extension plug-in should contain an ECom factory method for creating an instance of the plug-in class. In the example below, the factory method is named NewL.

Example:

const TImplementationProxy ImplementationTable[] =
    {
    IMPLEMENTATION_PROXY_ENTRY( 0x????????, CMyStartupExtensionPlugin::NewL )
    };
 
EXPORT_C const TImplementationProxy* ImplementationGroupProxy( TInt& aTableCount )
    {
    aTableCount = sizeof( ImplementationTable ) / sizeof( TImplementationProxy );
    return ImplementationTable;
    }
   

CSystemStartupExtension constructor takes the construction parameters as a TAny* value. CSystemStartupExtension expects the value to be exactly the same that has been passed to ECom when the request has been made to construct the plug-in. Never pass NULL as constructor parameter. Instead, create a factory method with the same signature as CSystemStartupExtension constructor, and pass the parameter to the constructor.

Example:

CMyStartupExtensionPlugin* CMyStartupExtensionPlugin::NewL( TAny* aConstructionParameters )
    {
    CMyStartupExtensionPlugin* self = new( ELeave ) CMyStartupExtensionPlugin( aConstructionParameters );
    CleanupStack::PushL( self );
    self->ConstructL();
    CleanupStack::Pop( self );
    return self;
    }

CMyStartupExtensionPlugin::CMyStartupExtensionPlugin( TAny* aConstructionParameters )
  : CSystemStartupExtension( aConstructionParameters )
    {
    }

A class derived from CSystemStartupExtension must provide an implementation for the ExecuteL function to actually initiate the task the plug-in is intended to handle.

ExecuteL should pass the request status object given as a parameter to the service handler that implements the actual service logic.

Time-consuming synchronous function calls in ExecuteL should be avoided whenever possible, because they block S60 Starter Server’s main thread. Never call User::WaitForRequest in ExecuteL.

Example:

void CMyExtensionPlugin::ExecuteL(
    TRequestStatus& aStatus,
    const TDesC& aParams )
    {
    TInt errorCode = iServer.Connect();
    if ( errorCode == KErrNone )
        {
        iServer.DoAsyncOperation( aStatus );
        }
    else
        {
        TRequestStatus* status = &aStatus;
        User::RequestComplete( status, errorCode );
        }
    }

A class derived from CSystemStartupExtension must provide an implementation to cancel the request made in ExecuteL. S60 Starter Server calls the Cancel() function of the plug-in if the operation takes too long or a fatal error occurs while the request is pending.

Example:

void CMyExtensionPlugin::Cancel()
    {
    iServer.CancelAsyncOperation();
    }
The sequence diagram in Figure 2 shows the sequence of actions in a successful scenario of loading and executing a system startup extension plug-in.
Figure 2: Loading and executing a system startup extension plug-in
1-3: S60 Starter Server creates the plug-in implementation via ECom based on the implementation UID specified in the system startup configuration resource.
4: S60 Starter Server starts a timer to be notified if the plug-in request does not complete in time.
5. S60 Starter Server calls the plug-in object’s ExecuteL method. The plug-in object initiates the task it is designed to handle.
6: When the plug-in-specific task has been completed, the plug-in object completes the request using the request status object that was given as a parameter to the ExecuteL function.
7. S60 Starter Server stops the timer.
8. S60 Starter Server deletes the plug-in object.

If the class derived from CSystemStartupExtension requires a file server session in its implementation, it should use CSystemStartupExtensions iFs member variable. It is of type RFs&. The plug-in implementation may not call iFs.Close() or iFs.Connect(). The file server session is already connected when the plug-in is created, and it will be used also after the plug-in is destroyed.

 


Plug-in configuration

System Startup Extension Plug-in API is implemented as a Symbian OS ECom plug-in. For more information about ECom plug-ins, refer to Symbian documentation.

With the ECom architecture, special care must be taken when writing the registration resource files.

  • The resource file must follow resource format version 2 or newer (see Symbian documentation). The version 1 does not have all the required fields.
  • The rom_only field must equal to 1. This also means that the actual plug-in binary must reside in ROM.
  • The resource file must implement the interface_uid of 0x10205067. This specifies that the plug-in implements System Startup Extension Plug-in API.
If these conditions are not fulfilled, the plug-in implementation will not load correctly. Below is an example resource file demonstrating the correct values:
#include "RegistryInfoV2.rh"

RESOURCE REGISTRY_INFO example_registration_information
    {
    resource_format_version =     
    dll_uid = 0x00000000; // allocate your own UID
    interfaces = 
        {
        INTERFACE_INFO
            {           
            interface_uid = 0x10205067; // UID of System startup extension plug-in API
            implementations = 
                {
                IMPLEMENTATION_INFO
                    {
                    /* Allocate your own UID. This is the UID to be specified when
                       adding the plug-in to system startup configuration resource. */
                    implementation_uid = 0x00000000;
                    version_no = 1;    // this field is not needed
                    display_name = ""; // this field is not needed
                    default_data = ""; // this field is not needed
                    opaque_data = "";  // this field is not needed
                    rom_only = 1;
                    }
                };
            }
        };
    }

 


Error handling

Possible error conditions common for all system startup extension plug-ins are:
  • The plug-in implementation specified in the system startup configuration resource is not found.
  • The plug-in instantiation fails.
  • The ExecuteL method leaves.
  • The plug-in implementation does not complete the request in the maximum time specified in the system startup configuration resource.
  • The plug-in implementation completes the request with an error code.

How the error is handled depends on whether the plug-in is a part of the critical or non-critical phase of startup. System startup extension plug-in failures during the critical phase are considered as fatal errors, and the general error handling policy of S60 Starter Server applies. System startup extension plug-in failures during the non-critical phase are ignored.

Errors caused by badly implemented or misbehaving plug-in DLLs (such as a plug-in implementation panicking or crashing) can not be detected by S60 Starter Server, and they effectively cause an uncontrolled reset.

 


Memory overhead

The memory overhead is implementation-dependant.

 


Extensions to the API

System Startup Extension Plug-in API is not intended to be extended.

 


Glossary

 


Abbreviations

Table: Abbreviations

None.

 
   

 


Definitions

Table: Definitions
System startup configuration resource A resource file defining lists of the servers and applications to start and the system startup extension plug-ins to load in each phase of the startup.

 


References

Table: References
1. S60 3.2 Startup Subsystem Architecture Description  
2. S60 Starter Design Document  
3. S60 Startup List API Specification  

Back to top