How to use UIDs

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

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

EPOC 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 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 the Symbian platform to enable various kinds of file identification and association. From a user point of view, conventional file names are preferable, for either purpose. Symbian 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 platform.

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 (application or 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

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 EPOC and more particularly files in EPOC 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 freely and conveniently on Symbian systems. The Symbian Platform allows customisable file association and identification even where UIDs are absent, based on file extension naming conventions.

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

EPOC predefines all possible UID1 and UID2 UIDs 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 an EIKON 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 EPOC and is automatically built into any executable target based on the exe target type declared in the project file.

Because exe targets define no interfaces and use no frameworks they need specify no further UIDs. An executable project therefore specifies no UIDs, including in ER5 no Unicode specific UIDs.

All DLLs, whether they have static or polymorphic interfaces, have a UID1 of KDynamicLibraryUid. This is system-defined by EPOC 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 require a UID3 to be specified, others do not. For example, a GUI application must specify a UID2 of KUidApp which is defined by the application framework, and a UID3 which must be allocated by the developer. To give another example, the printer driver framework, requires a UID2 but not a UID3.

Where one project uses multiple DLLs, for example a GUI application comprising a framework-derived polymorphic DLL with an application engine built separately as a static interface DLL, the DLLs will usually share the same UID3. In other cases where multiple projects share some common DLLs, for example multiple different applications which share some engine DLLs, each project including the shared engine project will specify unique UID3s.

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 EPOC, 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.

EPOC 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.

In previous releases the UNICODEUID project file statement was used to identify the UID for the Unicode build, and UID was used for the narrow build. Since Symbian has now moved exclusively to Unicode builds, the UNICODEUID keyword is deprecated — the UID statement should be used.

Because UIDs are fundamental to the 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. The only exception to this rule is a reserved range of values which may be used as UIDs by developers during development but which must not be used in released software.

During development temporary UIDs may be chosen from the range 0x01000000 to 0x0fffffff. Care must still be taken to avoid clashes within development teams and between multiple projects, including old projects which may still be installed on EPOC Emulator or native platforms. UID clashes may stop a program from loading correctly, typically leading to Not Found errors.

Developers can request UIDs either individually or in pre-allocated blocks by emailing uid@symbiandevnet.com. More information about allocating UIDs can be obtained from the Symbian Developer Network at: http://www.symbiandevnet.com/techlib/techcomms/techpapers/papers/tn_uid/uidinfo.html.