Embeddable -Applications

Procedure

Embeddable -applications are implemented as ECom plug-ins. The CApaApplication class -defines the interface, and the majority of an application's code will be in -the ECom plug-in. To allow an embeddable application to run as a standalone -application a small EXE also needs to be created which calls the EikStart::RunApplication() function, -but this time specifying the UID of the ECom plug-in rather than a pointer -to the factory function.

This section describes the steps for converting -an existing embeddable application to an ECom plug-in and executable.

Creating the ECom plug-in

The -MMP file of the embeddable application needs to be changed to create an ECom -plug-in instead of a DLL application, using the following lines:

TARGET Example_embedded.dll -TARGETTYPE PLUGIN -UID 0x10009d8d 0x01010101

where 0x01010101 is -a newly allocated UID, not the application's original UID - this is used elsewhere, -see below.

The MMP file also needs to create the ECom plug-in resource, -and the original resource line needs to be modified so the application resource -file(s) are created in the correct directory.

START RESOURCE 01010101.rss -#ifdef SYMBIAN_SECURE_ECOM -TARGET Example_embedded.rsc -#endif -END - -START RESOURCE Example.rss -HEADER -TARGETPATH \resource\apps -LANG SC -END

The 01010101.rss ECom plug-in resource -file uses the standard format for ECom plug-ins, where the interface definition -UID for CApaApplication s is:

const TUid KUidFileEmbeddedApplicationInterfaceUid={0x101f8c96};

The implementation UID should be the application's original UID (0x01234567 in -the example below), and therefore the file should look like this:

#include <RegistryInfo.rh> -RESOURCE REGISTRY_INFO - { - dll_uid = 0x01010101; - interfaces = - { - INTERFACE_INFO - { - interface_uid=0x101f8c96; - implementations= - { - IMPLEMENTATION_INFO - { - implementation_uid=0x01234567; - version_no=1; - } - }; - } - }; - }

ECom.lib should be included in -the library section in the MMP file.

The AIF section is not needed -as the application information is now provided by the registration file, localizable -resource file and icon file. A registration file should be provided to inform -the framework about the embeddable capability of the plug-in. This can be -achieved by setting the ‘embeddability' flag in APP_REGISTRATION_INFO structure. -If a stub EXE is provided to start the ECom plug-in, set the embeddability -flag to KAppEmbeddable, otherwise set KAppEmbeddableOnly. -For more information about the registration file please refer to the How to port guide - data -caged applications document.

The code for the application should -no longer export the NewApplication() function at ordinal -1, but instead the function which informs the ECom framework of the implementations -this ECom plug-in provides (as is standard for an ECom plug-in). This is demonstrated -by the following code:

#include "ExampleApp.h" -#include <ecom.h> -#include <implementationproxy.h> -GLDEF_C TInt E32Dll(TDllReason) - { - return KErrNone; - } - -LOCAL_C CApaApplication* NewApplication() - { - return new CExampleApplication; - } - -LOCAL_D const TImplementationProxy ImplementationTable[]= - { - IMPLEMENTATION_PROXY_ENTRY(0x01234567, NewApplication) - }; -EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) - { - aTableCount=sizeof(ImplementationTable)/sizeof(ImplementationTable[0]); - return ImplementationTable; - }

Creating -the standalone EXE for the application

The MMP file for the standalone -EXE should create an EXE-app (as described in the section above) and the EXE -should have the application's UID as its third UID. The AIF file should be -replaced by a registration file. The registration file is used to inform the -framework that the application is capable of being embedded by setting KAppEmbeddable in -the ‘embeddability' field of the APP_REGISTRATION_INFO structure.

#if !defined(EKA2) && defined(WINS) -TARGET Example.app -TARGETTYPE exedll -deffile \epoc32\release\wins\exedllapp.def -#else -TARGET Example.exe -TARGETTYPE exe -#endif -UID 0x100039CE 0x01234567 -TARGETPATH \sys\bin -EPOCSTACKSIZE 0x5000 -SOURCEPATH . -SOURCE Example_Standalone.cpp -USERINCLUDE . -SYSTEMINCLUDE \epoc32\include - -// Application exe registration resource file -start resource Example_reg.rss -targetpath \private\10003a3f\apps -lang sc -end - -LIBRARY euser.lib apparc.lib eikcore.lib

The executable need -only be a 'stub' to start the application architecture with the ECom UID. -Therefore the single source file should contain code similar to the following:

#include <e32std.h> -#include <eikstart.h> - -const TUid KExampleUid = {0x01234567}; -GLDEF_C TInt E32Main() - { - return EikStart::RunApplication(KExampleUid); - } -#if defined(__WINS__) && !defined(EKA2) -GLDEF_C TInt E32Dll(TDllReason) - { - return KErrNone; - } -EXPORT_C TInt WinsMain(TDesC* aCmdLine) - { - return EikStart::RunApplication(KExampleUid, aCmdLine); - } -#endif

Finally, the bld.inf for the application -needs to be modified to build both MMP files, for example:

PRJ_MMPFILES -Example_embedded.MMP -Example_standalone.MMP

Embedding -a new-style application in an existing application

To add a new -document to an application, an overload of CApaProcess::AddNewDocumentL() has -been created which can accept an ECom UID or an ECom CImplementationInformation reference. -However, the existing overload of AddNewDocumentL() handles -the case where the application for the document is an EXE, and attempts to -find an ECom plug-in with the correct UID to create the embedded application. -Therefore, existing applications (which perhaps offer a list of available -embeddable applications to the user) do not need to be modified. Also, the -internalizing and externalizing of embedded documents (through CApaDoor) -works with no modifications necessary.