|
Introduction | ||||||||||||||||||||||||||||||||||||||||||||||||
This document describes the C representation of UNO IDL types as generated by the cunomaker
tool. Each C UNO type is generated into a corresponding .h
header file and optional a .c source file if a special type function is
wanted. A getCUnoType_<full_qualified_typename>() func tion is
available for each UNO type in the .h file if the special type
function is generated. 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 getCUnoType_<typename>() function has the following
signature:
| ||||||||||||||||||||||||||||||||||||||||||||||||
Modules, Constants | ||||||||||||||||||||||||||||||||||||||||||||||||
An IDL module definition is mapped only in the name of an IDL type definition within the module. All IDL type definition within the module are mapped to their corresponding C type declarations with a full qualified type name. IDL constant groups are mapped in the same way as modules. 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 typedef 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 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 structs containing function pointers for each function. C interfaces are reference counted and are represented by an interface pointer. Each function contains as first parameter a pointer to the implemented object itself and as second parameter (out parameter) a pointer to an uno_Any representing a possible thrown exception. Note that this parameter will not be valid if no exception occured. While return values are passed as pure out parameters (the third parameter if the function doesn't return void), each function returns a cuno_ErrorCode. This error code is used to signal if an exception was thrown or not. The three different types of parameters are generated as follows:
out parameters and return values are pure out paramters that means that you give only the memory for this types in the function but the types must not be constructed. If an exception occured these parameters are not valid.
If the UNO IDL interface declares an attribute, the corresponding C struct
gets an additional Note: The queryInterface method will be changed in C. The return value specified in IDL of type any will be changed in the C type declaration to a pure out parameter of type com_sun_star_uno_XInterface pointer.
Example:
|
||||||||||||||||||||||||||||||||||||||||||||||||
Struct | ||||||||||||||||||||||||||||||||||||||||||||||||
UNO IDL Structs are generated to C typedefs to C structs declaring the C UNO types and members in the same order. The member names are identical. Struct inheritance is done by an additional member (the first member) with the inherited type. Note that the maximal alignment-requirement for structures for the OS/2 and Microsoft Visual C++ compiler is 8.
Example:
.h file)
| ||||||||||||||||||||||||||||||||||||||||||||||||
Exception | ||||||||||||||||||||||||||||||||||||||||||||||||
Exceptions are generated similarly to structs, meaning they have identical binary layout. 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:
.h file)
| ||||||||||||||||||||||||||||||||||||||||||||||||
Union | ||||||||||||||||||||||||||||||||||||||||||||||||
XXX TODO: Currently, unions are not supported by the cunomaker
tool, but nevertheless the runtime can cope with it. Union will be passed
by a pointer. 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.
| ||||||||||||||||||||||||||||||||||||||||||||||||
Author: Jürgen Schmidt. Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. | ||||||||||||||||||||||||||||||||||||||||||||||||