How to use UIDs

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

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

Symbian OS makes widespread use of UIDs:

• UIDs are used to identify the types of different 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 are of the expected type or that filestores are of an appropriate 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.

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

UIDs are used throughout Symbian OS to enable various kinds of file identification and association. From a user's point of view, conventional file names are preferable, for either purpose. Symbian OS 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. UIDs are therefore a fundamental feature of the OS.

By convention, the UID type of an object is a set of three separate UIDs used in combination. The component UIDs are referred to as UID1, UID2 and UID3 and have the following general characteristics:

• UID1 can be thought of as a system level identifier; for example, executables, DLLs, and file stores are all distinguished by UID1.

• UID2 distinguishes between objects having the same UID1 and can be thought of as an interface identifier; for example, static interface (shared library) and polymorphic interface (plug-in framework) DLLs are distinguished by UID2.

• UID3 identifies objects having a particular UID2 and can be thought of as a project identifier; for example, UID3 might be shared by all objects belonging to a given program, including library DLLs, if any, framework DLLs, and all documents.

  In OS versions with platform security, the Secure ID for a binary is taken to be the same as the third UID for that file. If an application (EXE) does not specify a UID3 or specifies it as zero, then the Secure ID is undefined for the application. 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.

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

The no UIDs case is provided to allow users to interact and exchange data easily with other systems, allowing non-native data files to be used on Symbian OS. Symbian OS allows customisable file association and identification even where UIDs are absent, based on file extension naming conventions.

However, for native Symbian OS programs, UIDs are used as the primary means of file type identification. Where possible, this is preferable to depending on file extensions.

Symbian OS predefines all possible UID1 and UID2 values at system level. Developers refer to them by their constant names, although in project (.mmp) files, hexadecimal numbers are used.

• UID1: valid examples include KExecutableImageUid, KDynamicLibraryUid and KDirectFileStoreLayoutUid

• UID2: valid examples include KSharedLibraryUid for a static interface DLL and KUidApp for a GUI application

• Developers are responsible for ensuring that where UID3 values are required, they are properly allocated

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

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

GUI applications need to have a UID2 of KUidApp, and an application-specific third UID. Simple console programs used for testing often do not specify any further UIDs.

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

Static and polymorphic DLLs are therefore distinguished by the different interfaces they present, as defined by their UID2 values.

For static interface DLLs, the UID2 is KSharedLibraryUid. The UID3 which is used to identify the interface uniquely must be allocated by the developer.

For polymorphic DLLs, the UID2 is defined by the framework which is being implemented. Some frameworks also use a UID3 value.

DLL UIDs allow the loader to check whether the DLL is of the subtype intended. This prevents files which just happen to have the right name from being loaded inadvertently.

In Symbian OS, 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 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 OS 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.

Because UIDs are fundamental to Symbian OS, 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 by a central allocating authority.

With the introduction of platform security, 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.

Developers can request UIDs through https://www.symbiansigned.com. For more information, see https://www.symbiansigned.com/app/page/uidfaq. Note that from version 9 of Symbian OS, UIDs are no longer requested from uid@symbiandevnet.com.

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 an emulator or native platforms. UID clashes may stop a program from loading correctly, typically leading to Not Found errors.