|
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:
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||
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:
| ||||||||||||||||||||||||||||||||||||||||||||||||
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 == 0If 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 .
| ||||||||||||||||||||||||||||||||||||||||||||||||
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 the compiler's sizeof(int) .
Example:
| ||||||||||||||||||||||||||||||||||||||||||||||||
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 ):
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
| ||||||||||||||||||||||||||||||||||||||||||||||||
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
inteface 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:
Return values are passed as C++ return values, the three different types of parameters are generated as follows:
get AttributeName() and
set AttributeName()
(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:
hdl file)
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:
hdl file)
| ||||||||||||||||||||||||||||||||||||||||||||||||
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:
hdl file)
| ||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||
Auhor: Daniel Bölzle. Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. | ||||||||||||||||||||||||||||||||||||||||||||||||