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.