How to provide registry information

An implementation collection publishes the properties of its implementations in a compiled resource file. The ECom framework reads all such resource files to find the interface implementations available on the system. Collections can be added, removed, or altered at any time.

ECom provides two versions of the resource structure types from which registration resource files are built:

• the standard version that allows ROM-based plug-ins to be overridden by RAM-based plug-ins

  See Writing a standard registration resource file

• a modified version (version 2) that prevents ROM-based plug-ins from being overridden by RAM-based plug-ins.

  See Writing a version 2 registration resource file

To write a standard registration resource file:

• set the file name to be the same as that of the executable with extension .rss

• the registration resource structure types are defined RegistryInfo.rh, so include that file

• define a single REGISTRY_INFO resource. Set its dll_uid member to be the DLL's UID. Set its interfaces member to be an array of INTERFACE_INFO resources.

• each INTERFACE_INFO resource defines registration information for implementations of the interface identified by its interface_uid member. The information takes the form of an array of IMPLEMENTATION_INFO resources.

• each IMPLEMENTATION_INFO resource declares the properties of a single implementation. It has five members:

• implementation_uid: the unique identifier for this implementation.

  For this value, use a new UID allocated by Symbian Signed. It does not matter whether the value comes from the protected or non-protected range of UIDs.

• version_no: the version of this interface implementation

• display_name: the implementation's human-readable name

• default_data: the data identifier field which a resolver uses to determine if the implementation matches a client request

• opaque_data: a binary data field, unused by ECom, which can contain additional data, for example, for use by custom resolvers

Example

The following example gives a resource registration file for an implementation collection with two implementations.

// 10009DB1.RSS
//
#include "RegistryInfo.rh"

RESOURCE REGISTRY_INFO theInfo
{
dll_uid = 0x10009DB1;
interfaces = 
    {
    INTERFACE_INFO
        {
        interface_uid = 0x10009DC0;
        implementations = 
            {
            IMPLEMENTATION_INFO
                {
                implementation_uid = 0x10009DC3;
                version_no = 1;
                display_name = "Implementation name 1";
                default_data = "text/wml";
                opaque_data = "some extra data";
                },
            IMPLEMENTATION_INFO
                {
                implementation_uid = 0x10009DC4;
                version_no = 1;
                display_name = "Implementation name 1";
                default_data = "text/xml||Type of data handled";
                opaque_data = "";
                }
            };
        }
    };
}

Writing a version 2 registration resource file is the same as writing a writing a standard registration resource file, but with the following additions and differences:

• the registration resource structure types are defined in RegistryInfoV2.rh, and means that you need to include that file instead of RegistryInfo.rh

• in the definition of the single REGISTRY_INFO resource, version 2 has the additional member resource_format_version; you must set this member to the value of RESOURCE_FORMAT_VERSION_2 defined in RegistryInfoV2.rh.

• each IMPLEMENTATION_INFO resource that declares the properties of a single implementation, has the additional member: rom_only. Set this member to 1 to identify a ROM-only implementation, and to 0 for an implementation that is not intended to be ROM-only.

  Note that you must remember to set a value for all implementations declared in a version 2 registration resource file.

Example

The following example gives a resource registration file for an implementation collection with two implementations; the first cannot be overridden by a RAM-based plug-in; the second can be overridden by a RAM-based plug-in.

// 10009DB1.RSS
//
#include "RegistryInfoV2.rh"

RESOURCE REGISTRY_INFO theInfo
{
// resource_format_version must always be set as follows
resource_format_version = RESOURCE_FORMAT_VERSION_2;

// Normal plug-in parameters
dll_uid = 0x10009DB5;
interfaces = 
    {
    INTERFACE_INFO
        {
        interface_uid = 0x10009DC9;
        implementations = 
            {
            IMPLEMENTATION_INFO
                {
                implementation_uid = 0x10009DCA;
                version_no = 1;
                display_name = "Example Implementation - ROM-only ";
                default_data = "text/wml";
                opaque_data = "";
    
                // This implementation CANNOT be overridden by a RAM-based plug-in
                rom_only = 1;
                },
            IMPLEMENTATION_INFO
                {
                implementation_uid = 0x10009DCB;
                version_no = 1;
                display_name = "Example Implementation - not ROM-only ";
                default_data = "text/wml";
                opaque_data = "";

                // This implementation CAN be overridden by a RAM-based plug-in
                rom_only = 0;
                }
            };
        }
    };
}