--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-BD7C45B2-11BF-5162-9F9B-B84E51C5C6D4.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,159 @@
+<?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 <RegistryInfo.rh>
+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) && 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 <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</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>
\ No newline at end of file