<?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 &lt;ecom.h&gt; 
#include &lt;implementationproxy.h&gt; 
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&amp; 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 &lt;eikstart.h&gt;

const TUid KExampleUid = {0x01234567}; 
GLDEF_C TInt E32Main()
    {
    return EikStart::RunApplication(KExampleUid);
    } 
#if defined(__WINS__) &amp;&amp; !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>
</related-links></concept>