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

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.

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.

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

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.

The memory overhead is implementation-dependant.

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