C++ UNO Language Specification

Introduction

This document describes the C++ representation of UNO IDL types as generated by the cppumaker tool. Each C++ UNO type is generated into a corresponding hpp and hdl header file. The hdl file contains only declarations while the hpp includes it and defines all inline functions (e.g., default constructors).

A inline getCppuType() function is available for each UNO type either in a hpp file or from basic type headers (, e.g. com/sun/star/uno/Any.hxx).

Calling this function you can obtain the meta type of a type, i.e. a value describing the type. Using this type (reference) you can get comprehensive description of the type using the C++ runtime (cppu library; have a look at typelib/typedescription.h).

The getCppuType() function has the following signature to be used for template statements:

// global lnamespace implied
const ::com::sun::star::uno::Type & SAL_CALL getCppuType( const Type * );

The UNO IDL character char type which is defined to be a C++ sal_Unicode 16 bit unsigned short integer is ambiguous to the C++ UNO IDL unsigned short (sal_uInt16), thus this points out an exception to the rule above. Also, the void type cannot be used, because any C++ pointer can be implicitly casted to a void pointer.

// global namespace implied
// header com/sun/star/uno/Type.hxx
const ::com::sun::star::uno::Type & SAL_CALL getCppuCharType();
const ::com::sun::star::uno::Type & SAL_CALL getCppuVoidType();
// header com/sun/star/uno/Sequence.hxx
const ::com::sun::star::uno::Type & SAL_CALL getCharSequenceCppuType();

The following sections define all types and UNO IDL constructs, which includes the binary memory layout, too.

• Modules, Constants
• basic Types
• Enum
• Sequence
• Array
• Interface
• Struct
• Exception
• union

Modules, Constants

An IDL module definition is mapped to a C++ namespace with the same name. All IDL type definition within the module are mapped to their corresponding C++ type declarations within the generated namespace. IDL declarations which are not enclosed in any modules are mapped into the C++ global scope.

IDL constant groups are mapped to a C++ namespaces with the same name as the constant group. All defined constants in this constant group are mapped to static const variables with type, name and value of the IDL equivalent.

Example:

module foo
{
    constants group
    {
        const long BAR = 0xdb0;
    };
};

is generated to

file foo/bar.hdl:

namespace foo
{
namespace group
{
static const sal_Int32 BAR = (sal_Int32)0xdb0;
}
}

basic Types

The binary representation of UNO types is machine (e.g. big-/little-endian), language and operating system dependent. Alignment of data structures complicates even more, and is also processor and bus dependent. The alignment used for C++ UNO types is defined by the following algorithm:

Structure members are stored sequentially by the order they are declared. Every data object has an alignment-requirement. For structures, the requirement is the largest size of its members. Every object then has an allocated offset so that

offset % alignment-requirement == 0

If it is possible that the maximum alignment-requirement can be restricted (Microsoft C/C++ compiler, IBM C/C++ compiler using a compiler pragma), then it is set to 8. Under this condition the alignment-requirement is

alignment-requirement := min( 8, sizeof( type ) ).
struct-alignment-requirement := min( 8, sizeof( largest-member-type ) ).

The size of the struct is ceiled up to the largest integral member type.

In general, if the maximal alignment-requirement can be restricted to max-alignment, then it is

alignment-requirement := min( max-alignment, sizeof( type ) ).
struct-alignment-requirement := min( max-alignment, sizeof( largest-member-type ) ).

The size of the struct is ceiled up to the largest integral member type.

The following table shows the IDL type, size and layout of the basic C++ UNO specification. Only 32-Bit C++ UNO is specified and tested for now. Basic type definitions like sal_Int32 are defined in header sal/types.h.

typedef struct _uno_Any
{
    typelib_TypeDescriptionReference * pType;
    void *                             pData;
} uno_Any;

Enum

An IDL enumeration is mapped to a C++ enumeration type (enum). The name of the enumeration is used as prefix for each enumeration label. The enumeration labels will be initialized with the defined values in IDL or by default in ascending order beginning with 0. The last label (EnumName_MAKE_FIXED_SIZE = SAL_MAX_ENUM) is appended to fix the size of the enumeration type to 32 bit.

Example:

module foo
{
    enum Bar
    {
        JOHN, DOE
    };
};

is generated to

file foo/Bar.hdl:

namespace foo
{

enum Bar
{
    Bar_John = 0,
    Bar_DOE = 1,
    Bar_MAKE_FIXED_SIZE = SAL_MAX_ENUM
};

}

Sequence

C++ UNO sequences are reference counted. The value type of a sequence is handled by template class ::com::sun::star::uno::Sequence (header com/sun/star/uno/Sequence.hxx). It acquires a pointer to uno_Sequence which is of the following structure (headers uno/sequence2.h and sal/types.h):

typedef struct _sal_Sequence
{
    sal_Int32 nRefCount;
    sal_Int32 nElements;
    char      elements[1];
} sal_Sequence;

typedef sal_Sequence uno_Sequence;

Elements of the sequence follow up directly to the elements array. API functions to cope with sequences are in header uno/sequence2.h.

Sequences are used generically in UNO, i.e. nothing has to be generated for a specific sequence (e.g. used in an interface method declaration) by the cppumaker tool. A UNO IDL type usage of sequence< long > will last in a C++ UNO ::com::sun::star::uno::Sequence< sal_Int32 >.

Header com/sun/star/uno/Sequence.hxx defines a template getCppuType() function (template parameter is C++ UNO element type). As stated in the first section, UNO IDL type char is ambiguous to unsigned short C++ UNO type. Thus for UNO IDL sequence< char > you have to use getCharSequenceCppuType() obtaining its meta type (header com/sun/star/uno/Sequence.hxx).

Array

XXX TODO: The array has yet to be specified, but is in work. Ask Juergen Schmidt for current status.

Thus the array specification is not fixed, to give an outlook: It will follow C array specification and generated to a C array of given element type. Arrays will allow multiple dimensions. In contrast to sequences C arrays are not reference counted, thus copying big arrays may be time consuming.

Interface

Interfaces are generated to C++ classes having pure virtual member functions (, e.g. virtual void foo() = 0). C++ interface references control the lifetime of an interface (template wrapper class ::com::sun::star::uno::Reference<> in header com/sun/star/uno/Reference.hxx) and hold the acquired interface pointer as only member. They build up the value type of an interface, i.e. if a method expects an interface, this implicitly means it gets an interface reference. Note that the generated getCppuType() generated in the hpp file has the following signature:

inline const ::com::sun::star::uno::Type& SAL_CALL getCppuType(
    const ::com::sun::star::uno::Reference< generated_C++_class >* )
    throw();

Return values are passed as C++ return values, the three different types of parameters are generated as follows:

• in: the parameter is pure in parameter; it is passed as call-by-value for ordinal and float types or passed as call-by-reference (const & [const C++ reference]) for C++ objects (, e.g. struct, exception, interface reference).
• out: the parameter is pure out parameter; it is anytime passed as call-by-reference (& [non-const C++ reference]).
• inout: the parameter is inout parameter; it is anytime passed as call-by-reference (& [non-const C++ reference]).

If the UNO IDL interface declares an attribute, the corresponding C++ class gets a getAttributeName() and setAttributeName() (if non-readonly).

Any interface method can declare exceptions that may be thrown upon invocation of it. Implicitly any method may throw com.sun.star.uno.RuntimeException (generated C++ struct ::com::sun::star::uno::RuntimeException). For now exception clauses are generated for the pure virtual member functions, but due to compiler bugs this heavily increases code size on some platforms. So the currently used C++ throw clause will probably exchanged by a macro expansion soon. But nevertheless this only affects exception declarations, C++ UNO exceptions can be thrown and caught as common in C++ (try ... catch ()).

The latter said is valid except for com.sun.star.XInterface::acquire() and com.sun.star.XInterface::release() which never throw any exception.

Interface inheritance is similarly adopted to C++ class inheritance. All interfaces inherit from UNO IDL interface com.sun.star.XInterface (i.e. C++ generated class ::com::sun::star::XInterface) which serves as a base for lifetime control and querying the object for interfaces.

Example: com.sun.star.lang.XMultiServiceFactory

module com {  module sun {  module star {  module lang {

interface XMultiServiceFactory: com::sun::star::uno::XInterface
{ 
    com::sun::star::uno::XInterface createInstance(
        [in] string aServiceSpecifier ) 
        raises( com::sun::star::uno::Exception );
	
    com::sun::star::uno::XInterface createInstanceWithArguments(
        [in] string ServiceSpecifier, 
        [in] sequence Arguments ) 
        raises( com::sun::star::uno::Exception );
	
    sequence getAvailableServiceNames(); 
}; 

}; }; }; };

will be generated to (hdl file)

namespace com
{
namespace sun
{
namespace star
{
namespace lang
{

class XMultiServiceFactory : public ::com::sun::star::uno::XInterface
{
public:
    virtual ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > SAL_CALL
        createInstance( const ::rtl::OUString& aServiceSpecifier )
        throw(::com::sun::star::uno::Exception, ::com::sun::star::uno::RuntimeException) = 0;
	
    virtual ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > SAL_CALL
        createInstanceWithArguments(
	    const ::rtl::OUString& ServiceSpecifier,
	    const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& Arguments )
	throw(::com::sun::star::uno::Exception, ::com::sun::star::uno::RuntimeException) = 0;
	
    virtual ::com::sun::star::uno::Sequence< ::rtl::OUString > SAL_CALL
        getAvailableServiceNames(  )
        throw(::com::sun::star::uno::RuntimeException) = 0;
};

} // lang
} // star
} // sun
} // com

Oneway declarations are ignored for C++ bridges, they only affect inter-process bridges. The macro SAL_CALL forces C calling convention to be used, e.g. __cdecl for the Microsoft Visual C++ compiler.

Struct

UNO IDL Structs are generated to C++ structs declaring the C++ UNO types and members in the same order. The member names are identical. A default constructor initializing all members to their default values is generated, too. Struct inheritance is adopted to C++ inheritance. Note that the maximal alignment-requirement for structures for the OS/2 and Microsoft Visual C++ compiler is 8.

Example: com.sun.star.lang.Locale

module com {  module sun {  module star {  module lang {

struct Locale
{
    string Language;
    string Country;
    string Variant;
};

}; }; }; };

will be generated to (hdl file)

namespace com
{
namespace sun
{
namespace star
{
namespace lang
{

#ifdef SAL_W32
#   pragma pack(push, 8)
#elif defined(SAL_OS2)
#   pragma pack(8)
#endif

struct Locale
{
    inline Locale();

    // inline ctor definition in hpp file
    inline Locale(
        const ::rtl::OUString& __Language,
        const ::rtl::OUString& __Country,
	const ::rtl::OUString& __Variant );

    ::rtl::OUString Language;
    ::rtl::OUString Country;
    ::rtl::OUString Variant;
};

#ifdef SAL_W32
#   pragma pack(pop)
#elif defined(SAL_OS2)
#   pragma pack()
#endif

} // lang
} // star
} // sun
} // com

Exception

Exceptions are generated similarly to structs, meaning they have identical binary layout. There is only one minor difference in generation, i.e. exceptions are declared as C++ classes not as structs. Exception members appear in the public section of the class. Exceptions are thrown by instance.

Exceptions need not inherit from any base exception, though UNO API conventions want any exception ([in-]directly) inherit from com.sun.star.uno.Exception.

Example: com.sun.star.lang.IllegalArgumentException

module com {  module sun {  module star {  module lang {  
 
exception IllegalArgumentException: com::sun::star::uno::Exception
{ 
    short ArgumentPosition; 
}; 
 
}; }; }; };  

will be generated to (hdl file)

namespace com
{
namespace sun
{
namespace star
{
namespace lang
{

class IllegalArgumentException : public ::com::sun::star::uno::Exception
{
public:
    // inline ctor definition in hpp file
    inline IllegalArgumentException();
    // inline ctor definition in hpp file
    inline IllegalArgumentException(
        const ::rtl::OUString& __Message,
	const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& __Context,
	const sal_Int16& __ArgumentPosition );

    sal_Int16 ArgumentPosition;
};

} // lang
} // star
} // sun
} // com

Union

XXX TODO: Currently, unions are not supported by the cppumaker tool, but nevertheless the runtime can cope with it. Union will be passed by C++ reference upon member function calls except for return values. Unions will be generated as structs having a 64 bit discriminant as first member followed by a C union declaration. Alignment is as for structs.