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-380A8C4F-3EB6-5E1C-BCFB-ED5B866136D9" xml:lang="en"><title>How |
|
13 to use UIDs</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A UID is a globally unique identifier consisting of a 32-bit number. </p> |
|
15 <p>In Symbian platform, objects are identified by a compound identifier, known |
|
16 as the <keyword>UID type</keyword>, which is constructed from three 32 bit |
|
17 identifiers. The individual UIDs making up the UID type are referred to as <keyword>UID1</keyword>, <keyword>UID2</keyword> and <keyword>UID3</keyword>. </p> |
|
18 <p>Symbian platform makes widespread use of UIDs: </p> |
|
19 <ul> |
|
20 <li id="GUID-CD464385-25EF-5953-AA1F-31F99A12B7F1"><p>UIDs are used to identify |
|
21 the types of objects at runtime and loadtime, for example identifying executables, |
|
22 DLLs, filestores. </p> </li> |
|
23 <li id="GUID-E57A5374-9526-5BEA-BC18-14852DD30423"><p>UIDs are used to verify |
|
24 that objects present compatible and expected interfaces at runtime and loadtime, |
|
25 for example verifying that DLLs or filestores are of the expected type. </p> </li> |
|
26 <li id="GUID-5A2B51EC-DA36-5CC3-A2FA-0F318B80E983"><p>UIDs are fundamental |
|
27 to the association of applications with documents. For example, associating |
|
28 a document with an application allows the system to launch the application |
|
29 when the document is opened. </p> </li> |
|
30 </ul> |
|
31 <p>A file's three UIDs are stored in the first 12 bytes of the file. </p> |
|
32 <p>To program successfully, Symbian developers need to understand why and |
|
33 how to use UIDs in their programs. </p> |
|
34 <section><title>What UIDs are for</title> <p>From a user's point of view, |
|
35 conventional file names are preferable to UIDs for file identification. Symbian |
|
36 platform therefore supports a flexible, long filename, file naming scheme. </p> <p>However |
|
37 from a system point of view, guaranteed unique, 32-bit numbers provide for |
|
38 much safer, systematic, and more lightweight identification. </p> <p>UID1, |
|
39 UID2 and UID3 have the following general characteristics: </p> <ul> |
|
40 <li id="GUID-251CC75C-E12F-5602-AC72-D61769536325"><p> <keyword>UID1</keyword> indicates |
|
41 the structure of the file, for example, whether it is an executable, a DLL |
|
42 or a file store. </p> </li> |
|
43 <li id="GUID-04F9AE5C-CE1C-5A78-A58E-843CAA821975"><p>The meaning of <keyword>UID2</keyword> depends |
|
44 on the type of object it applies to. For polymorphic interface (plug-in framework) |
|
45 DLLs, UID2 identifies the interface that the DLL implements. For static interface |
|
46 (shared library) DLLs that others link to, the UID2 value is always the same. |
|
47 For executables the UID value has to be set to <codeph>KUidApp</codeph> or <codeph>NULL</codeph>. </p> </li> |
|
48 <li id="GUID-0C52BBE3-8971-5D13-92D9-1958BD053C90"><p> <keyword>UID3</keyword> distinguishes |
|
49 between objects with the same UID2 and can be thought of as a project identifier. |
|
50 For example, for an application, the same UID3 is shared by the executable, |
|
51 registration file (which defines the application's icon, caption, and some |
|
52 capability information), and all documents. </p> <p>The <xref href="GUID-A98F7AA2-A908-527E-9AEC-54DDD10A49C1.dita">SECUREID</xref> need |
|
53 not be explicitly specified in the .mmp file, but if it is omitted, then the |
|
54 value of the UID3, specified elsewhere in the .mmp file, is used. If the UID3 |
|
55 is not specified, then the secureid will take the value <codeph>KNullUID</codeph>. |
|
56 This has several consequences, including lack of privacy for data used by |
|
57 that application. </p> </li> |
|
58 </ul> <p>The UID type is a <codeph>TUidType</codeph> object and is constructed |
|
59 from a combination of all or some of the three possible UIDs. The UID type |
|
60 can be queried to return its component <keyword>UID1</keyword>, <keyword>UID2</keyword> and <keyword>UID3</keyword> values. </p> <p>If |
|
61 no UIDs are attached to an object, then all three component UIDs are returned |
|
62 as <codeph>KUidNull</codeph>. </p> </section> |
|
63 <section><title>UID1, UID2, UID3, and the no UIDs case</title> <p>An object |
|
64 in Symbian platform and more particularly files in Symbian platform may have |
|
65 all, some, or none of the three possible UIDs defined. </p> <p>Symbian platform |
|
66 predefines all possible UID1 values and the UID2 values used for GUI applications |
|
67 and static interface DLLs at system level. Symbian developers refer to them |
|
68 by their constant names, although in project (<filepath>.mmp</filepath>) files, |
|
69 hexadecimal numbers are used. </p> <ul> |
|
70 <li id="GUID-95B7B621-CE04-53DE-A708-FCBD4DB5A36D"><p>UID1: examples include <codeph>KExecutableImageUid</codeph>, <codeph>KDynamicLibraryUid</codeph> and <codeph>KDirectFileStoreLayoutUid</codeph> </p> </li> |
|
71 <li id="GUID-8956CAD8-C680-5BD6-9C3F-86821A268C1B"><p>UID2: examples include <codeph>KSharedLibraryUid</codeph> (0x1000008d) |
|
72 for a static interface DLL and <codeph>KUidApp</codeph> (0x100039CE) or NULL |
|
73 for a GUI application. <b>Note:</b> Both <codeph>KUidApp</codeph> and NULL |
|
74 are acceptable values for UID2 when the application is an EXE, although at |
|
75 the present time these values are ignored. At a later stage UID2 may be used |
|
76 for other purposes, so setting UID2 to values outside of these values is not |
|
77 recommended. </p> </li> |
|
78 <li id="GUID-BECDDD3F-58E9-5414-ACC7-25BE2217D81A"><p>Symbian developers are |
|
79 responsible for ensuring that where UID3 values are required, they are properly |
|
80 allocated. See the <xref href="https://www.symbiansigned.com" scope="external">Symbian |
|
81 Signed</xref> web site for information on how to allocate UIDs (free registration |
|
82 is required to see the FAQ). </p> </li> |
|
83 </ul> <p>Note that in project (<filepath>.mmp</filepath>) files, UID2 and |
|
84 UID3 values can be specified, but UID1 values cannot; the UID1 value is implied |
|
85 by the project's target type. </p> </section> |
|
86 <section><title>EXE targets and UIDs</title> <p>All executable targets have |
|
87 a UID1 of <codeph>KExecutableImageUid</codeph>. This is defined by Symbian |
|
88 platform and is automatically built into any executable target based on the <codeph>exe</codeph> target |
|
89 type declared in the project file. </p> <p>A UID2 value should be specified |
|
90 by GUI applications (.EXE) and the application architecture expects this to |
|
91 be <codeph>KUidApp</codeph> (0x100039CE) or NULL. Console applications (also |
|
92 .EXE), which are often used for testing and as example code, do not need to |
|
93 specify a UID2, and if they do, it is ignored. </p> </section> |
|
94 <section><title>DLLs and UIDs</title> <p>All DLLs, whether they have static |
|
95 or polymorphic interfaces, have a UID1 of <codeph>KDynamicLibraryUid</codeph>. |
|
96 This is defined by Symbian platform and is automatically built into any DLL |
|
97 target based on the <filepath>dll</filepath> target type declared in the project |
|
98 file. </p> <p>For static interface DLLs, the UID2 is <codeph>KSharedLibraryUid.</codeph> The |
|
99 UID3, which is used to identify the interface to the library, must be allocated |
|
100 by Symbian Signed. </p> <p>For polymorphic DLLs (for instance ECom plugins, |
|
101 device drivers and front end processors), UID2 identifies the interface that |
|
102 the DLL implements. UID3 (which, if required, must be allocated by Symbian |
|
103 Signed) may be used to identify a specific implementation of that interface. </p> </section> |
|
104 <section><title>Documents and UIDs</title> <p>In Symbian platform, documents |
|
105 are really file-stores: stores which can be closed and re-opened. There are |
|
106 two different kinds of file store, <keyword>direct file stores</keyword> which |
|
107 are write-once-read-many, and <keyword>permanent file stores</keyword> which |
|
108 are write-many-read-many. </p> <p>A document's UID1 will therefore be one |
|
109 of <codeph>KDirectFileStoreLayoutUid</codeph> or <codeph>KPermanentFileStoreLayoutUid</codeph>. |
|
110 The UID2 and/or UID3 will be application dependent. </p> <p>Every native document |
|
111 must have an appropriate UID1 which should be set by the application which |
|
112 creates the document. Typically documents may have a UID2 of <codeph>KUidAppDllDoc</codeph> and |
|
113 a UID3 shared with the creating application. More precisely, a document’s |
|
114 UID3 should match that of the application which will open it. </p> <p>Only |
|
115 the UID1 is required, but in most cases Symbian developers will want to specify |
|
116 second and third UIDs for the documents their applications create and use. |
|
117 These UIDs are used by the application architecture framework to manage associations |
|
118 between applications and their documents. This allows an application to be |
|
119 found and launched when a file is opened, and it also allows an application |
|
120 icon to be associated with documents in system shell displays. Conversely, |
|
121 it allows an application, when opening files, to select only applicable files. </p> <p>Symbian |
|
122 platform also allows default file associations with the implication that in |
|
123 some cases users may want to select a different application to open a file. |
|
124 Applications which support this must therefore be able to open documents whose |
|
125 third UID differs from their own. </p> <p>Applications may also want to open |
|
126 non-native documents which have no UIDs, and may wish to be specified as default |
|
127 applications for these documents. </p> </section> |
|
128 <section><title>UIDs in package files</title> <p>Package (.PKG) files are |
|
129 used in Symbian platform to provide the information required to create Symbian |
|
130 installation (.SIS) files. Each SIS file contains a UID, which is defined |
|
131 in the package file's <xref href="GUID-D9D20EE0-AC86-512A-91C0-EA0ACF3912A7.dita">package |
|
132 header</xref>. This UID should be allocated in the same way |
|
133 as other UIDs, through Symbian Signed. </p> </section> |
|
134 <section id="GUID-8D9B0F56-4CD1-506C-A8DF-A310DC5F58CE"><title>Uniqueness |
|
135 and allocation</title> <p>Because UIDs are fundamental to Symbian platform, |
|
136 it is important that they are used correctly when developing programs. To |
|
137 ensure uniqueness, it is essential that UIDs are properly allocated. </p> <p>Uniqueness |
|
138 is guaranteed by managing allocation centrally from a single database. All |
|
139 UIDs must therefore be assigned to users by a central allocating authority. </p> <p>UIDs |
|
140 are also split into protected and unprotected ranges. Any UID values falling |
|
141 below 0x7FFFFFFF are classed as "protected" and are only intended for use |
|
142 with signed applications (or those pre-installed in ROM). The software installer |
|
143 will refuse to install an unsigned application if it uses a package UID in |
|
144 the protected range. </p> <p>Symbian developers can request UIDs through <xref href="https://www.symbiansigned.com" scope="external">https://www.symbiansigned.com</xref>. |
|
145 For more information, see the Symbian Signed FAQ (free registration required). |
|
146 Note that from version 9 of Symbian platform, UIDs are no longer requested |
|
147 from uid@symbiandevnet.com. </p></section> |
|
148 <section><title>Reserved UID range for development only</title><p>During development, |
|
149 or for test code, temporary UIDs may be chosen from the unprotected test range |
|
150 0xExxxxxxx. These UIDs can be used during development for unsigned applications |
|
151 but must not be used in released software. Note that such applications may |
|
152 not be installable via a SIS file. See the Symbian Signed website for more |
|
153 information. </p> <p>Care must still be taken to avoid clashes within development |
|
154 teams and between multiple projects, including old projects which may still |
|
155 be installed on a Symbian emulator or native platforms. UID clashes may stop |
|
156 a program from loading correctly, typically leading to <systemoutput>Not Found</systemoutput> errors. </p> </section> |
|
157 </conbody></concept> |
|