S60 3.2: System Startup Extension Plug-in API Specification |
DN0645972 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
1.1 |
30.06.2006 |
Approved |
More detailed description and an example added. |
1.0 |
06.06.2006 |
Approved |
|
![]() |
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.
![]() |
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.
![]() |
Using System Startup Extension Plug-in API means implementing a system startup extension plug-in.
![]() |
The class structure of System Startup Extension Plug-in API is shown in Figure 1.
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.
![]() |
![]() |
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(); }
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.
![]() |
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.
#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; } }; } }; }
![]() |
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.
![]() |
1. S60 3.2 Startup Subsystem Architecture Description | |
2. S60 Starter Design Document | |
3. S60 Startup List API Specification |
![]() |