<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-BD7C45B2-11BF-5162-9F9B-B84E51C5C6D4" xml:lang="en"><title>Embeddable

Applications</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-4CE56897-FEB9-523F-843A-E5BAFFDBBCDB"><title>Procedure</title> <p>Embeddable

applications are implemented as ECom plug-ins. The <xref href="GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7.dita"><apiname>CApaApplication</apiname></xref> 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 <codeph>EikStart::RunApplication()</codeph> function,

but this time specifying the UID of the ECom plug-in rather than a pointer

to the factory function. </p> <p>This section describes the steps for converting

an existing embeddable application to an ECom plug-in and executable. </p> <p id="GUID-D3711552-3728-592E-9244-4A94D17B430D"><b>Creating the ECom plug-in</b> </p> <p>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: </p> <codeblock id="GUID-5A76A5A1-5E8B-50A5-A222-03775DB8784C" xml:space="preserve">TARGET Example_embedded.dll 

TARGETTYPE PLUGIN 

UID 0x10009d8d 0x01010101</codeblock> <p>where <codeph>0x01010101</codeph> is

a newly allocated UID, not the application's original UID - this is used elsewhere,

see below. </p> <p>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. </p> <codeblock id="GUID-C47AD0E7-8A92-5AB4-A742-C1DDB6AC74D4" xml:space="preserve">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</codeblock> <p>The <filepath>01010101.rss</filepath> ECom plug-in resource

file uses the standard format for ECom plug-ins, where the interface definition

UID for <xref href="GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7.dita"><apiname>CApaApplication</apiname></xref> s is: </p> <codeblock id="GUID-AEDBF454-0768-5A16-BC2B-CFF4EEF81D87" xml:space="preserve">const TUid KUidFileEmbeddedApplicationInterfaceUid={0x101f8c96};</codeblock> <p>The implementation UID should be the application's original UID (<codeph>0x01234567</codeph> in

the example below), and therefore the file should look like this: </p> <codeblock id="GUID-04F88175-A0D8-5358-8183-8DDF040CBD01" xml:space="preserve">#include &lt;RegistryInfo.rh&gt; 

RESOURCE REGISTRY_INFO

    {

    dll_uid = 0x01010101; 

    interfaces =

        {

        INTERFACE_INFO

            {

            interface_uid=0x101f8c96;

            implementations=

                {

                IMPLEMENTATION_INFO

                    {

                    implementation_uid=0x01234567;

                    version_no=1;

                    }

                };

            }

        };

    }</codeblock> <p> <filepath> ECom.lib</filepath> should be included in

the library section in the MMP file. </p> <p>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 <codeph>APP_REGISTRATION_INFO</codeph> structure.

If a stub EXE is provided to start the ECom plug-in, set the embeddability

flag to <codeph>KAppEmbeddable</codeph>, otherwise set <codeph>KAppEmbeddableOnly</codeph>.

For more information about the registration file please refer to the <xref href="GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita">How to port guide - data

caged applications</xref> document. </p> <p>The code for the application should

no longer export the <codeph>NewApplication()</codeph> 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: </p> <codeblock id="GUID-77C1A71A-E4DB-5D1D-BBFC-8DB508BE439C" xml:space="preserve">#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; 

    }</codeblock> <p id="GUID-F2901432-ED44-576A-B081-D3AF916C9A93"><b>Creating

the standalone EXE for the application</b> </p> <p>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 <codeph>KAppEmbeddable</codeph> in

the ‘embeddability' field of the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> <codeblock id="GUID-BE2079A0-F267-583F-8098-3F7143EE22FF" xml:space="preserve">#if !defined(EKA2) &amp;&amp; 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</codeblock> <p>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: </p> <codeblock id="GUID-F6746743-4040-51C8-837A-851AE41B69F5" xml:space="preserve">#include &lt;e32std.h&gt; 

#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</codeblock> <p>Finally, the <filepath>bld.inf</filepath> for the application

needs to be modified to build both MMP files, for example: </p> <codeblock id="GUID-ADA03DA8-4AE4-50BB-9A28-5745A0F807E2" xml:space="preserve">PRJ_MMPFILES 

Example_embedded.MMP 

Example_standalone.MMP</codeblock> <p id="GUID-C75A516F-B0BA-5E5C-8C86-2A4FBA9C3034"><b>Embedding

a new-style application in an existing application</b> </p> <p>To add a new

document to an application, an overload of <codeph>CApaProcess::AddNewDocumentL()</codeph> has

been created which can accept an ECom UID or an ECom <xref href="GUID-3107B19B-0607-3E9E-AEA5-BAD07EEC59D0.dita"><apiname>CImplementationInformation</apiname></xref> reference.

However, the existing overload of <codeph>AddNewDocumentL()</codeph> 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 <xref href="GUID-F9CF2D9A-DF57-3603-896F-E2D5A2AE7481.dita"><apiname>CApaDoor</apiname></xref>)

works with no modifications necessary. </p> </section>

</conbody><related-links>

<link href="GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F.dita#GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F/GUID-A28ABF97-3EF0-5554-8A66-C9EB1FF954B6">

<linktext>Application properties</linktext></link>