|
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-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF" xml:lang="en"><title>Porting |
|
13 Data-caged Applications</title><shortdesc>This document describes the changes required to migrate exe-apps |
|
14 to a data caged directory structure. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section><title>Introduction</title> <p>In Symbian OS v8.0 and earlier, application |
|
16 specific information (for instance captions and icons) was provided by a combination |
|
17 of the AIF (Application Information File) and the caption file. Both of these |
|
18 files were optional. </p> <p>Migrated applications must provide a registration |
|
19 file, and may optionally provide localizable application information resource |
|
20 files and icon files. Localizable application information resource files provide |
|
21 localizable application information (for instance captions and icons), whereas |
|
22 an application's localizable UI resource file provides UI resources such as |
|
23 menus and dialogs. </p> <p>The localizable information that was previously |
|
24 provided by a combination of AIF and caption files, has been split into two |
|
25 categories: </p> <p>The diagram below shows the new file structure used to |
|
26 provide application information. </p> <fig id="GUID-7C0D7121-43A4-5C29-86E6-A92F753D29A4"> |
|
27 <image href="GUID-E4B5C7CE-7820-5D80-8CD1-DCD692C11F23_d0e137102_href.png" placement="inline"/> |
|
28 </fig> <ul> |
|
29 <li id="GUID-0D14076A-26FE-5E6A-BF57-69B169287BF1"><p>A registration file |
|
30 which 'points' to one of three localizable resource files provided. If the |
|
31 current language is <filepath>01</filepath> or <filepath>02</filepath>, the |
|
32 system will load the corresponding version of <filepath>AppName_loc</filepath>, |
|
33 otherwise <filepath>AppName_loc.rsc</filepath> will be loaded. </p> </li> |
|
34 <li id="GUID-AF8CD591-A112-5AF3-92CD-97ADD83C277C"><p> <filepath>AppName_loc.r01</filepath> and <filepath>AppName_loc.r02</filepath> share |
|
35 the same icon file. </p> </li> |
|
36 </ul> <p>Migrated applications may be used with or without data caging enforced. </p> </section> |
|
37 <section><title>Procedure</title> <p>The following sections detail the mandatory |
|
38 and optional steps required to migrate an application. </p> <p> <b>Mandatory |
|
39 steps</b> </p> <ol id="GUID-8CCDDC52-4EB1-567A-A9F5-A480E9912B66"> |
|
40 <li id="GUID-27A355EC-835B-59AC-8B40-B855BCB1BD34"><p>Provide a registration |
|
41 file. </p> <p>A registration file is a standard Symbian platform compiled |
|
42 resource file (<filepath>.rsc</filepath>). The <filepath>.rss</filepath> file |
|
43 used to build the registration file should be named <codeph>AppName_reg.rss</codeph> and |
|
44 contain at least the following lines: </p> <codeblock id="GUID-192653ED-EF93-566D-907F-46462D825B96" xml:space="preserve">#include <appinfo.rh> |
|
45 UID2 KUidAppRegistrationResourceFile |
|
46 UID3 0x01000000 // application UID |
|
47 RESOURCE APP_REGISTRATION_INFO |
|
48 { |
|
49 app_file="AppName"; // filename of application binary (minus extension) |
|
50 }</codeblock> <p>To build the registration file, add the following lines |
|
51 to the application's MMP file: </p> <codeblock id="GUID-2C8C8693-E881-578B-91CB-FDC17C357CDA" xml:space="preserve">START RESOURCE AppName_reg.rss |
|
52 TARGETPATH \private\10003a3f\apps |
|
53 END</codeblock> <p>The <filepath>_reg</filepath> filename suffix is used as |
|
54 a naming convention only and is not mandatory. </p> <p>Note that any lines |
|
55 in the MMP file that are used to build an AIF file should be removed. </p> </li> |
|
56 <li id="GUID-B5D1F806-91F1-5326-8026-D1E36C30889E"><p>Build the application |
|
57 binary to a new location. </p> <p>The following line should replace the <codeph>TARGETPATH</codeph> line |
|
58 associated with the <codeph>TARGET</codeph>, <codeph>TARGETTYPE</codeph> and <codeph>UID</codeph> lines: </p> <codeblock id="GUID-5BD260BF-9A9D-5998-83AE-667D9C3B1A96" xml:space="preserve">TARGETPATH \sys\bin</codeblock> </li> |
|
59 </ol> <p> <b>Optional steps</b> </p> <ul> |
|
60 <li id="GUID-967BFB2B-6862-5C79-A89F-F897F2036415"><p>A UI resource file whose |
|
61 location is provided by <codeph>CEikApplication::ResourceFileName()</codeph> </p> </li> |
|
62 <li id="GUID-0B7D3B27-0D56-50E5-9EE0-9084FE138FD9"><p>An MBM file whose location |
|
63 is provided by <codeph>CEikApplication::BitmapStoreName()</codeph> </p> </li> |
|
64 <li id="GUID-AF83E0ED-F59E-5BFC-9C58-1DED13A78645"><p>Application information |
|
65 through an AIF and/or caption file. </p> </li> |
|
66 </ul> <p>The following steps are only required if the application provides |
|
67 one or more of the following: </p> <ol id="GUID-42AA9F22-B442-5972-985F-6F629C257093"> |
|
68 <li id="GUID-1706E3AD-7343-56EA-8E74-977E7F033E08"><p>Specify the default |
|
69 UI resource file location. </p> <p>When building the application UI resource |
|
70 file, the <codeph>TARGETPATH</codeph> must be specified as follows: </p> <codeblock id="GUID-9429B307-D5F6-5EEF-8FDD-FA2E962E1695" xml:space="preserve">TARGETPATH \resource\apps</codeblock> </li> |
|
71 <li id="GUID-A21B102D-7C2A-562A-80A5-464EE0F42C56"><p>Specify the default |
|
72 MBM file location. </p> <p>When building the application's MBM file, the <codeph>TARGETPATH</codeph> must |
|
73 be specified as follows: </p> <codeblock id="GUID-E7A8DD91-70AA-519E-91EB-493EFCF9302A" xml:space="preserve">TARGETPATH \resource\apps</codeblock> </li> |
|
74 <li id="GUID-1E07FA6D-F5E1-524D-AD7C-E6CAD3E8F5E5"><p>Specify the application |
|
75 information by providing the following files: </p> <ul> |
|
76 <li id="GUID-619E778D-E4E5-5755-B6F1-E02C047C4BEE"><p>Non-localizable information |
|
77 (provided by the registration file) </p> <p>The registration file provides |
|
78 non-localizable application information. For an example registration file |
|
79 see <codeph>AppName_reg.rss</codeph> in the <xref href="GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita#GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF/GUID-52802361-8A7A-5C8A-ACC1-F41E50CFD1CF">Example |
|
80 files</xref> section. </p> </li> |
|
81 <li id="GUID-38C4EF86-05A7-5D95-BB04-644DEC26C582"><p>Localizable information |
|
82 (localizable resource file and icon file) </p> <p>Localizable application |
|
83 information can either be provided in a separate resource file (see <codeph>AppName_loc.rss</codeph>), |
|
84 or as a resource within the application UI resource file (see <codeph>AppName.rss</codeph> and <codeph>AppName2_reg.rss</codeph> in |
|
85 the <xref href="GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita#GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF/GUID-52802361-8A7A-5C8A-ACC1-F41E50CFD1CF">Example |
|
86 files</xref> section). </p> <p>When providing the information as a resource |
|
87 within the application UI resource file, the registration file's <codeph>APP_REGISTRATION_INFO</codeph> struct |
|
88 must contain the following lines: </p> <codeblock id="GUID-EF9F185B-FBF7-52BA-B218-4B3DF2FC8A40" xml:space="preserve">localisable_resource_file="\\resource\\apps\\AppName"; |
|
89 localisable_resource_id = R_LAI;</codeblock> <p>where <codeph>R_LAI</codeph> is |
|
90 a named <codeph>LOCALISABLE_APP_INFO</codeph> resource struct within the UI |
|
91 resource file. </p> <p>The <codeph>localisable_resource_file</codeph> field |
|
92 should not include a drive in the path, or a file-extension, but it should |
|
93 provide a full directory path and a file name (without extension). </p> <p>To |
|
94 build a resource file for language <filepath>01</filepath>, add the following |
|
95 to the MMP file: </p> <codeblock id="GUID-8ECAB691-7720-5B7C-AD77-AF706AE621B8" xml:space="preserve">start resource AppName_loc.rss |
|
96 targetpath \resource\apps |
|
97 lang 01 |
|
98 end</codeblock> <p>The <filepath>_loc</filepath> filename suffix is used as |
|
99 a naming convention only and is not mandatory. </p> <p>Icon files referenced |
|
100 in the localizable resource should also be built to <filepath>\resource\apps\</filepath>. </p> </li> |
|
101 </ul> </li> |
|
102 </ol> </section> |
|
103 <section id="GUID-3C64BE3F-859A-5E81-BCBD-C4BF717D4439"><title>Software install |
|
104 package file requirements</title> <p>When creating a PKG file (software install |
|
105 package file) for an application, the registration file must be installed |
|
106 to the <filepath>\private\10003a3f\import\apps\</filepath> directory. </p> <p>The |
|
107 application binary must be installed to <filepath>\sys\bin\</filepath> on |
|
108 the same drive as the registration file. </p> <p>The localizable resource |
|
109 files must be installed to <filepath>\resource\apps\</filepath> on the same |
|
110 drive as the registration file. </p> </section> |
|
111 <section id="GUID-BB2F1E46-47CE-51F8-9020-D0D1DD9E06CB"><title>Data caged |
|
112 file locations</title> <p>To comply with the directory structure imposed by |
|
113 data caging, many of the files associated with an application need to be relocated. </p> <p>Care |
|
114 should be taken to ensure application code which overrides the following APIs |
|
115 uses appropriate file locations: </p> <codeblock id="GUID-4CED50C3-3B76-5FCD-8F22-0B1D051E1A7A" xml:space="preserve">CEikApplication::ResourceFileName() |
|
116 CEikApplication::BitmapStoreName() |
|
117 CEikApplication::OpenIniFileLC( RFs& aFs )</codeblock> <p>When specifying |
|
118 the location of files on a target device, application IBY files should explicitly |
|
119 specify <filepath>\sys\bin</filepath> as the destination location for application |
|
120 binary files instead of using <codeph>SYSTEM_BINDIR</codeph>. </p> </section> |
|
121 <section id="GUID-52802361-8A7A-5C8A-ACC1-F41E50CFD1CF"><title>Example files</title> <p id="GUID-CDA35D97-FF46-5A5F-A57B-F3E93B935E1C"><b>AppName_reg.rss</b> </p><codeblock id="GUID-AE62EB61-5776-55D8-9CA3-DB18EAC00CC7" xml:space="preserve">#include <appinfo.rh> |
|
122 |
|
123 UID2 KUidAppRegistrationResourceFile |
|
124 UID3 0x01000000 // application UID |
|
125 |
|
126 RESOURCE APP_REGISTRATION_INFO |
|
127 { |
|
128 app_file = "AppName"; |
|
129 // |
|
130 localisable_resource_file = "\\resource\\apps\\AppName_loc"; |
|
131 // |
|
132 hidden = KAppNotHidden; |
|
133 embeddability = KAppNotEmbeddable; |
|
134 newfile = KAppDoesNotSupportNewFile; |
|
135 launch = KAppLaunchInForeground; |
|
136 group_name = "AppNameGroup"; |
|
137 // |
|
138 default_screen_number = 2; |
|
139 // |
|
140 datatype_list = |
|
141 { |
|
142 DATATYPE { priority=EDataTypePriorityNormal; type="image/jpeg"; }, |
|
143 DATATYPE { priority=EDataTypePriorityNormal; type="image/gif"; } |
|
144 }; |
|
145 // |
|
146 file_ownership_list = |
|
147 { |
|
148 FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppNameTempFile.txt"; }, |
|
149 FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppName.txt"; } |
|
150 }; |
|
151 }</codeblock> <p id="GUID-7F026167-77F9-5AC2-A68F-049DEC624A4E"><b> AppName_loc.rss</b> </p><codeblock id="GUID-E2F5C25C-206E-510F-BF8C-6E8EBA41F1DD" xml:space="preserve">#include <appinfo.rh> |
|
152 #ifdef LANGUAGE_01 |
|
153 #include "AppName01.rls" |
|
154 #else |
|
155 #include "AppNamesc.rls" |
|
156 #endif |
|
157 RESOURCE LOCALISABLE_APP_INFO |
|
158 { |
|
159 short_caption = STRING_r_short_caption; |
|
160 caption_and_icon = |
|
161 { |
|
162 CAPTION_AND_ICON_INFO |
|
163 { |
|
164 caption = STRING_r_caption; |
|
165 number_of_icons = 2; // each icon must be a bitmap/mask pair |
|
166 icon_file = STRING_r_icon_file; |
|
167 } |
|
168 }; |
|
169 // |
|
170 view_list = |
|
171 { |
|
172 VIEW_DATA |
|
173 { |
|
174 uid = 268123123; |
|
175 screen_mode = 0x00; |
|
176 caption_and_icon = |
|
177 { |
|
178 CAPTION_AND_ICON_INFO |
|
179 { |
|
180 caption = STRING_r_view_268123123_caption; |
|
181 number_of_icons = 1; // each icon must be a bitmap/mask pair |
|
182 } |
|
183 }; |
|
184 }, |
|
185 VIEW_DATA |
|
186 { |
|
187 uid = 268123124; |
|
188 screen_mode = 0x01; |
|
189 caption_and_icon = |
|
190 { |
|
191 CAPTION_AND_ICON_INFO |
|
192 { |
|
193 caption = STRING_r_view_268123124_caption; |
|
194 number_of_icons = 1; // each icon must be a bitmap/mask pair |
|
195 icon_file = "z:\\resource\\apps\\icon.svg"; |
|
196 } |
|
197 }; |
|
198 } |
|
199 }; |
|
200 }</codeblock> <p><b>Note</b>: In the above example, RLS files have been |
|
201 used to demonstrate how resource files for different languages (<codeph>AppName_loc.r01</codeph> and <codeph>AppName_loc.rsc</codeph>) |
|
202 can be built from a single RSS file. </p> <p id="GUID-E828B29C-35AC-50CA-8B76-FD626D825E1A"><b> AppName01.rls</b> </p><codeblock id="GUID-BB8CC777-51FC-5BFC-99B3-19D68C130458" xml:space="preserve">rls_string STRING_r_short_caption "English AppName" |
|
203 rls_string STRING_r_caption "English AppName Long Caption" |
|
204 rls_string STRING_r_icon_file "z:\\resource\\apps\\EnglishAppNameIcons.mbm" |
|
205 rls_string STRING_r_view_268123123_caption "caption for view 268123123" |
|
206 rls_string STRING_r_view_268123124_caption "English view 268123124"</codeblock> <p id="GUID-8E9F17B1-4A22-56EF-ACD8-0432F3BB9DBD"><b> AppNamesc.rls</b> </p><codeblock id="GUID-F5182C0B-1F5E-5F7A-9F10-C0DCA34E0B84" xml:space="preserve">rls_string STRING_r_short_caption "AppName" |
|
207 rls_string STRING_r_caption "Default AppName Caption" |
|
208 rls_string STRING_r_icon_file "z:\\resource\\apps\\DefaultAppNameIcons.mbm" |
|
209 rls_string STRING_r_view_268123123_caption "caption for view 268123123" |
|
210 rls_string STRING_r_view_268123124_caption "caption for view 268123124"</codeblock> <p id="GUID-065DF486-615D-55F1-8572-DF30E58927C3"><b> AppName2_reg.rss</b> </p><codeblock id="GUID-3B7C2951-9B1D-51FD-9AED-2B68EEE6CA62" xml:space="preserve">#include <appinfo.rh> |
|
211 #include <appname.rsg> |
|
212 |
|
213 UID2 KUidAppRegistrationResourceFile |
|
214 UID3 0x01000000 // application UID |
|
215 |
|
216 RESOURCE APP_REGISTRATION_INFO |
|
217 { |
|
218 app_file = "AppName"; |
|
219 // |
|
220 localisable_resource_file = "\\resource\\apps\\appname"; |
|
221 localisable_resource_id = R_LAI; |
|
222 }</codeblock> <p id="GUID-661C0B2C-9BA9-5168-B2A9-A2FA1F87B5D7"><b> AppName.rss</b> </p><codeblock id="GUID-54DDDB25-E66F-5CF1-ACA3-93244C44CC8D" xml:space="preserve">NAME APPN |
|
223 #include <eikon.rh> |
|
224 #include <eikon.rsg> |
|
225 #include <appinfo.rh> |
|
226 |
|
227 RESOURCE RSS_SIGNATURE { } |
|
228 RESOURCE TBUF r_appname_default_file { buf="default file name"; } |
|
229 RESOURCE EIK_APP_INFO { hotkeys=r_appname_hotkeys; menubar=r_appname_menubar; toolbar=r_appname_toolbar; } |
|
230 RESOURCE LOCALISABLE_APP_INFO r_lai |
|
231 { |
|
232 short_caption = "AppName"; |
|
233 } |
|
234 RESOURCE TOOLBAR r_appname_toolbar { } |
|
235 RESOURCE HOTKEYS r_appname_hotkeys { } |
|
236 RESOURCE MENU_BAR r_appname_menubar { }</codeblock> </section> |
|
237 </conbody><related-links> |
|
238 <link href="GUID-3CAD7211-2164-5F93-9EA7-7167E1C14012.dita"><linktext>Porting Applications |
|
239 to EXEs</linktext></link> |
|
240 </related-links></concept> |