|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-BD7C45B2-11BF-5162-9F9B-B84E51C5C6D4" xml:lang="en"><title>Embeddable |
|
13 Applications</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-4CE56897-FEB9-523F-843A-E5BAFFDBBCDB"><title>Procedure</title> <p>Embeddable |
|
15 applications are implemented as ECom plug-ins. The <xref href="GUID-C0297A58-2E39-3211-A2B4-C334192CE2A7.dita"><apiname>CApaApplication</apiname></xref> class |
|
16 defines the interface, and the majority of an application's code will be in |
|
17 the ECom plug-in. To allow an embeddable application to run as a standalone |
|
18 application a small EXE also needs to be created which calls the <codeph>EikStart::RunApplication()</codeph> function, |
|
19 but this time specifying the UID of the ECom plug-in rather than a pointer |
|
20 to the factory function. </p> <p>This section describes the steps for converting |
|
21 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 |
|
22 MMP file of the embeddable application needs to be changed to create an ECom |
|
23 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 |
|
24 TARGETTYPE PLUGIN |
|
25 UID 0x10009d8d 0x01010101</codeblock> <p>where <codeph>0x01010101</codeph> is |
|
26 a newly allocated UID, not the application's original UID - this is used elsewhere, |
|
27 see below. </p> <p>The MMP file also needs to create the ECom plug-in resource, |
|
28 and the original resource line needs to be modified so the application resource |
|
29 file(s) are created in the correct directory. </p> <codeblock id="GUID-C47AD0E7-8A92-5AB4-A742-C1DDB6AC74D4" xml:space="preserve">START RESOURCE 01010101.rss |
|
30 #ifdef SYMBIAN_SECURE_ECOM |
|
31 TARGET Example_embedded.rsc |
|
32 #endif |
|
33 END |
|
34 |
|
35 START RESOURCE Example.rss |
|
36 HEADER |
|
37 TARGETPATH \resource\apps |
|
38 LANG SC |
|
39 END</codeblock> <p>The <filepath>01010101.rss</filepath> ECom plug-in resource |
|
40 file uses the standard format for ECom plug-ins, where the interface definition |
|
41 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 |
|
42 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> |
|
43 RESOURCE REGISTRY_INFO |
|
44 { |
|
45 dll_uid = 0x01010101; |
|
46 interfaces = |
|
47 { |
|
48 INTERFACE_INFO |
|
49 { |
|
50 interface_uid=0x101f8c96; |
|
51 implementations= |
|
52 { |
|
53 IMPLEMENTATION_INFO |
|
54 { |
|
55 implementation_uid=0x01234567; |
|
56 version_no=1; |
|
57 } |
|
58 }; |
|
59 } |
|
60 }; |
|
61 }</codeblock> <p> <filepath> ECom.lib</filepath> should be included in |
|
62 the library section in the MMP file. </p> <p>The AIF section is not needed |
|
63 as the application information is now provided by the registration file, localizable |
|
64 resource file and icon file. A registration file should be provided to inform |
|
65 the framework about the embeddable capability of the plug-in. This can be |
|
66 achieved by setting the ‘embeddability' flag in <codeph>APP_REGISTRATION_INFO</codeph> structure. |
|
67 If a stub EXE is provided to start the ECom plug-in, set the embeddability |
|
68 flag to <codeph>KAppEmbeddable</codeph>, otherwise set <codeph>KAppEmbeddableOnly</codeph>. |
|
69 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 |
|
70 caged applications</xref> document. </p> <p>The code for the application should |
|
71 no longer export the <codeph>NewApplication()</codeph> function at ordinal |
|
72 1, but instead the function which informs the ECom framework of the implementations |
|
73 this ECom plug-in provides (as is standard for an ECom plug-in). This is demonstrated |
|
74 by the following code: </p> <codeblock id="GUID-77C1A71A-E4DB-5D1D-BBFC-8DB508BE439C" xml:space="preserve">#include "ExampleApp.h" |
|
75 #include <ecom.h> |
|
76 #include <implementationproxy.h> |
|
77 GLDEF_C TInt E32Dll(TDllReason) |
|
78 { |
|
79 return KErrNone; |
|
80 } |
|
81 |
|
82 LOCAL_C CApaApplication* NewApplication() |
|
83 { |
|
84 return new CExampleApplication; |
|
85 } |
|
86 |
|
87 LOCAL_D const TImplementationProxy ImplementationTable[]= |
|
88 { |
|
89 IMPLEMENTATION_PROXY_ENTRY(0x01234567, NewApplication) |
|
90 }; |
|
91 EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) |
|
92 { |
|
93 aTableCount=sizeof(ImplementationTable)/sizeof(ImplementationTable[0]); |
|
94 return ImplementationTable; |
|
95 }</codeblock> <p id="GUID-F2901432-ED44-576A-B081-D3AF916C9A93"><b>Creating |
|
96 the standalone EXE for the application</b> </p> <p>The MMP file for the standalone |
|
97 EXE should create an EXE-app (as described in the section above) and the EXE |
|
98 should have the application's UID as its third UID. The AIF file should be |
|
99 replaced by a registration file. The registration file is used to inform the |
|
100 framework that the application is capable of being embedded by setting <codeph>KAppEmbeddable</codeph> in |
|
101 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) |
|
102 TARGET Example.app |
|
103 TARGETTYPE exedll |
|
104 deffile \epoc32\release\wins\exedllapp.def |
|
105 #else |
|
106 TARGET Example.exe |
|
107 TARGETTYPE exe |
|
108 #endif |
|
109 UID 0x100039CE 0x01234567 |
|
110 TARGETPATH \sys\bin |
|
111 EPOCSTACKSIZE 0x5000 |
|
112 SOURCEPATH . |
|
113 SOURCE Example_Standalone.cpp |
|
114 USERINCLUDE . |
|
115 SYSTEMINCLUDE \epoc32\include |
|
116 |
|
117 // Application exe registration resource file |
|
118 start resource Example_reg.rss |
|
119 targetpath \private\10003a3f\apps |
|
120 lang sc |
|
121 end |
|
122 |
|
123 LIBRARY euser.lib apparc.lib eikcore.lib</codeblock> <p>The executable need |
|
124 only be a 'stub' to start the application architecture with the ECom UID. |
|
125 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> |
|
126 #include <eikstart.h> |
|
127 |
|
128 const TUid KExampleUid = {0x01234567}; |
|
129 GLDEF_C TInt E32Main() |
|
130 { |
|
131 return EikStart::RunApplication(KExampleUid); |
|
132 } |
|
133 #if defined(__WINS__) && !defined(EKA2) |
|
134 GLDEF_C TInt E32Dll(TDllReason) |
|
135 { |
|
136 return KErrNone; |
|
137 } |
|
138 EXPORT_C TInt WinsMain(TDesC* aCmdLine) |
|
139 { |
|
140 return EikStart::RunApplication(KExampleUid, aCmdLine); |
|
141 } |
|
142 #endif</codeblock> <p>Finally, the <filepath>bld.inf</filepath> for the application |
|
143 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 |
|
144 Example_embedded.MMP |
|
145 Example_standalone.MMP</codeblock> <p id="GUID-C75A516F-B0BA-5E5C-8C86-2A4FBA9C3034"><b>Embedding |
|
146 a new-style application in an existing application</b> </p> <p>To add a new |
|
147 document to an application, an overload of <codeph>CApaProcess::AddNewDocumentL()</codeph> has |
|
148 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. |
|
149 However, the existing overload of <codeph>AddNewDocumentL()</codeph> handles |
|
150 the case where the application for the document is an EXE, and attempts to |
|
151 find an ECom plug-in with the correct UID to create the embedded application. |
|
152 Therefore, existing applications (which perhaps offer a list of available |
|
153 embeddable applications to the user) do not need to be modified. Also, the |
|
154 internalizing and externalizing of embedded documents (through <xref href="GUID-F9CF2D9A-DF57-3603-896F-E2D5A2AE7481.dita"><apiname>CApaDoor</apiname></xref>) |
|
155 works with no modifications necessary. </p> </section> |
|
156 </conbody><related-links> |
|
157 <link href="GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F.dita#GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F/GUID-A28ABF97-3EF0-5554-8A66-C9EB1FF954B6"> |
|
158 <linktext>Application properties</linktext></link> |
|
159 </related-links></concept> |