C++ UNO Components

Contents

Overview
C++ Components

Overview

UNO components, normally, provide an implementation of one or more services. A service description is written in idl. A service describes the interaction of different interfaces to support a special functionality. An idl description of a service specifies a set of interfaces which supports the expected functionality. It can also contain references to other services which are needed for this service. A service could be implemented by more than one component. At this time, the component which is registered last, will be used as the default implementation for the supported services of this component.

It is also possible to register or revoke components at runtime. For this it is necessary to use a registration service (com.sun.star.registry.ImplementationRegistration) to register external components in the runtime environment of the office suite. It should be possible to use almost any programming language to implement a component, since only two things are necessary: first, an appropriate language binding for the programming language used, and second, an appropriate loader service for components implemented in this language.

C++ Components

C++ UNO components are usually implemented as shared libraries. Such a shared library must provide a special interface which contains 4 exported "C" functions. These functions are searched by the appropriate loader service ("com.sun.star.loader.SharedLibrary") to register the component or to instantiate an object providing the service.

The exported "C" functions are:

component_getDescriptionFunc
component_getImplementationEnvironmentFunc
component_writeInfo
component_getFactory

component_getDescriptionFunc

Syntax:

extern "C" const sal_Char* SAL_CALL component_getDescriptionFunc(void);

This function is optional but should be supported. The function should return an XML formatted string describing the contents of the component. This function could be generated from a general XML component description. Such a description contains information about the name, the supported services, the needed services, the needed types, and so on. For more details, see XML Component Description. Any component should provide such an XML description.

component_getImplementationEnvironmentFunc

Syntax:

extern "C" void SAL_CALL component_getImplementationEnvironmentFunc(const sal_Char** ppEnvTypeName, uno_Environment** ppEnv );

Function to determine the implementation environment of the component. This function shows the runtime environment how to use the void* parameters of component_writeInfoFunc and component_getFactoryFunc. A component, implemented in C++, uses the C++ environment. The UNO runtime must map the void* parameters from the C++ environment to the current environment. If the environment is NOT session specific, i.e., it needs no additional context, then this function should return the environment type name and leave ppEnv (0).

component_writeInfo

Syntax:

extern "C" sal_Bool SAL_CALL component_writeInfoFunc(void* pServiceManager, void* pRegistryKey );

Function to write component specific data in a reserved section in the registry, at least, the supported services of the component. pRegistryKey refers to a reserved section in the registry. Any component should have a unique implementation name to specify their own subsection under this key. pServiceManager specifies the current service manager. The service manager could be used at this time to get information from other services which are important for this component (this parameter is seldom used).

Structure of an implementation section:

/IMPLEMENTATIONS/<implementation_name>/UNO/SERVICES/<service_name1>[/attribute_subkeys]
                                                   /<service_name2>...
                                                    ...
                                     [/REGISTRY_LINKS]
                                          (AsciiListValue)
                                          <registry_link1>
                                          <registry_link2>
                                           ...
                                     [/DATA]

Under the reserved key ".../UNO/SERVICES" there could be one or more services specified as a subkey with the name of the service. Each service key could also have subkeys to specify service-specific attributes. ".../REGISTRY_LINKS" specifies also a reserved key which is interpreted by the registration service. This key must have an ASCII list value. The values of these lists, specifies links which are created by the registration service. The notation of such a link name shows where the link is created and where the target is. If the link name begins with '/' the link will be created under the rootkey, if not the link will be created relative to the <implementation_name>. If the linkname contains a unique '%', then the part after the '%' is used as the link target; otherwise, the link target is the <implementation_name>. If a link target is specified, it is always relative to the <implementation_name>. To specify one's own service specific data, it is useful to create a special ".../DATA" section.

component_getFactory

Syntax:

extern "C" void* SAL_CALL component_getFactoryFunc(const sal_Char* pImplName, void* pServiceManager, void* pRegistryKey );

This Function returns a factory to create component instances. The first time a component instance will be created, this function is called and the returned factory is registered in the service manager. pImplName specifies the name of the implementation which the factory will create. It is possible to have more than one implementation in a shared library. pServiceManager points to the current service manager. This service manager should be given to the factory and later to any instances, so that all instances created in the environment of this service manager use this one. pRegistryKey points to the implementation key specified by pImplName. This key should also be given to the factory and later to every instance when there are component specific data in the implementation section, that will later be used.

Example

Under Component Tutorial, you will find a simple example of how to create a C++ UNO component. You will also find typical implementations of the C-functions which are necessary to support the C++ component interface.