How +to use UIDs

A UID is a globally unique identifier consisting of a 32-bit number.

In Symbian platform, objects are identified by a compound identifier, known +as the UID type, which is constructed from three 32 bit +identifiers. The individual UIDs making up the UID type are referred to as UID1, UID2 and UID3.

Symbian platform makes widespread use of UIDs:

UIDs are used to identify +the types of objects at runtime and loadtime, for example identifying executables, +DLLs, filestores.
UIDs are used to verify +that objects present compatible and expected interfaces at runtime and loadtime, +for example verifying that DLLs or filestores are of the expected type.
UIDs are fundamental +to the association of applications with documents. For example, associating +a document with an application allows the system to launch the application +when the document is opened.

A file's three UIDs are stored in the first 12 bytes of the file.

To program successfully, Symbian developers need to understand why and +how to use UIDs in their programs.

What UIDs are for

From a user's point of view, +conventional file names are preferable to UIDs for file identification. Symbian +platform therefore supports a flexible, long filename, file naming scheme.

However +from a system point of view, guaranteed unique, 32-bit numbers provide for +much safer, systematic, and more lightweight identification.

UID1, +UID2 and UID3 have the following general characteristics:

UID1 indicates +the structure of the file, for example, whether it is an executable, a DLL +or a file store.
The meaning of UID2 depends +on the type of object it applies to. For polymorphic interface (plug-in framework) +DLLs, UID2 identifies the interface that the DLL implements. For static interface +(shared library) DLLs that others link to, the UID2 value is always the same. +For executables the UID value has to be set to KUidApp or NULL.
UID3 distinguishes +between objects with the same UID2 and can be thought of as a project identifier. +For example, for an application, the same UID3 is shared by the executable, +registration file (which defines the application's icon, caption, and some +capability information), and all documents.

The SECUREID need +not be explicitly specified in the .mmp file, but if it is omitted, then the +value of the UID3, specified elsewhere in the .mmp file, is used. If the UID3 +is not specified, then the secureid will take the value KNullUID. +This has several consequences, including lack of privacy for data used by +that application.

The UID type is a TUidType object and is constructed +from a combination of all or some of the three possible UIDs. The UID type +can be queried to return its component UID1, UID2 and UID3 values.

If +no UIDs are attached to an object, then all three component UIDs are returned +as KUidNull.

UID1, UID2, UID3, and the no UIDs case

An object +in Symbian platform and more particularly files in Symbian platform may have +all, some, or none of the three possible UIDs defined.

Symbian platform +predefines all possible UID1 values and the UID2 values used for GUI applications +and static interface DLLs at system level. Symbian developers refer to them +by their constant names, although in project (.mmp) files, +hexadecimal numbers are used.

UID1: examples include KExecutableImageUid, KDynamicLibraryUid and KDirectFileStoreLayoutUid
UID2: examples include KSharedLibraryUid (0x1000008d) +for a static interface DLL and KUidApp (0x100039CE) or NULL +for a GUI application. Note: Both KUidApp and NULL +are acceptable values for UID2 when the application is an EXE, although at +the present time these values are ignored. At a later stage UID2 may be used +for other purposes, so setting UID2 to values outside of these values is not +recommended.
Symbian developers are +responsible for ensuring that where UID3 values are required, they are properly +allocated. See the Symbian +Signed web site for information on how to allocate UIDs (free registration +is required to see the FAQ).

Note that in project (.mmp) files, UID2 and +UID3 values can be specified, but UID1 values cannot; the UID1 value is implied +by the project's target type.

EXE targets and UIDs

All executable targets have +a UID1 of KExecutableImageUid. This is defined by Symbian +platform and is automatically built into any executable target based on the exe target +type declared in the project file.

A UID2 value should be specified +by GUI applications (.EXE) and the application architecture expects this to +be KUidApp (0x100039CE) or NULL. Console applications (also +.EXE), which are often used for testing and as example code, do not need to +specify a UID2, and if they do, it is ignored.

DLLs and UIDs

All DLLs, whether they have static +or polymorphic interfaces, have a UID1 of KDynamicLibraryUid. +This is defined by Symbian platform and is automatically built into any DLL +target based on the dll target type declared in the project +file.

For static interface DLLs, the UID2 is KSharedLibraryUid. The +UID3, which is used to identify the interface to the library, must be allocated +by Symbian Signed.

For polymorphic DLLs (for instance ECom plugins, +device drivers and front end processors), UID2 identifies the interface that +the DLL implements. UID3 (which, if required, must be allocated by Symbian +Signed) may be used to identify a specific implementation of that interface.

Documents and UIDs

In Symbian platform, documents +are really file-stores: stores which can be closed and re-opened. There are +two different kinds of file store, direct file stores which +are write-once-read-many, and permanent file stores which +are write-many-read-many.

A document's UID1 will therefore be one +of KDirectFileStoreLayoutUid or KPermanentFileStoreLayoutUid. +The UID2 and/or UID3 will be application dependent.

Every native document +must have an appropriate UID1 which should be set by the application which +creates the document. Typically documents may have a UID2 of KUidAppDllDoc and +a UID3 shared with the creating application. More precisely, a document’s +UID3 should match that of the application which will open it.

Only +the UID1 is required, but in most cases Symbian developers will want to specify +second and third UIDs for the documents their applications create and use. +These UIDs are used by the application architecture framework to manage associations +between applications and their documents. This allows an application to be +found and launched when a file is opened, and it also allows an application +icon to be associated with documents in system shell displays. Conversely, +it allows an application, when opening files, to select only applicable files.

Symbian +platform also allows default file associations with the implication that in +some cases users may want to select a different application to open a file. +Applications which support this must therefore be able to open documents whose +third UID differs from their own.

Applications may also want to open +non-native documents which have no UIDs, and may wish to be specified as default +applications for these documents.

UIDs in package files

Package (.PKG) files are +used in Symbian platform to provide the information required to create Symbian +installation (.SIS) files. Each SIS file contains a UID, which is defined +in the package file's package +header. This UID should be allocated in the same way +as other UIDs, through Symbian Signed.

Uniqueness +and allocation

Because UIDs are fundamental to Symbian platform, +it is important that they are used correctly when developing programs. To +ensure uniqueness, it is essential that UIDs are properly allocated.

Uniqueness +is guaranteed by managing allocation centrally from a single database. All +UIDs must therefore be assigned to users by a central allocating authority.

UIDs +are also split into protected and unprotected ranges. Any UID values falling +below 0x7FFFFFFF are classed as "protected" and are only intended for use +with signed applications (or those pre-installed in ROM). The software installer +will refuse to install an unsigned application if it uses a package UID in +the protected range.

Symbian developers can request UIDs through https://www.symbiansigned.com. +For more information, see the Symbian Signed FAQ (free registration required). +Note that from version 9 of Symbian platform, UIDs are no longer requested +from uid@symbiandevnet.com.

Reserved UID range for development only

During development, +or for test code, temporary UIDs may be chosen from the unprotected test range +0xExxxxxxx. These UIDs can be used during development for unsigned applications +but must not be used in released software. Note that such applications may +not be installable via a SIS file. See the Symbian Signed website for more +information.

Care must still be taken to avoid clashes within development +teams and between multiple projects, including old projects which may still +be installed on a Symbian emulator or native platforms. UID clashes may stop +a program from loading correctly, typically leading to Not Found errors.