How do I...

Binary UNO Specification

Abstract

This document contains the specification of the types mapped from the IDL to binary (C) UNO.

You should be familiar with the document the idea of UNO. A slight knowledge about interfaces, C/C++, and a background about an object model like COM is helpful.

Type Specification

All types which can be used in the IDL language are specified in this paragraph. The representation of the types is machine, language, and operating system dependent. The base types are swapped if the processor has little or big-endian format. The size of the types may vary depending on the processor bus size. The size of types may depend on the operating system. Another problem is the alignment of data structures: the alignment is processor and bus dependent. Alignment is defined through the following algorithm:

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

    offset % alignment-requirement == 0

If it is possible that the maximum alignment can be restricted (e.g. Microsoft Visual C++ compiler) then the maximum alignment is set to 8. Under this condition the alignment is set to

    min( n, sizeof( item ) ).

The size is rounded up to the largest integral base type.

The following table shows the IDL type, size, and layout:

IDL Type	32 Bit UNO	64 Bit UNO
byte	Signed 8 Bit (sal_Int8)	Signed 8 Bit (sal_Int8)
short	Signed 16 Bit (sal_Int16)	Signed 16 Bit (sal_Int16)
unsigned short	Unsigned 16 Bit (sal_uInt16)	Unsigned 16 Bit (sal_uInt16)
long	Signed 32 Bit (sal_Int32)	Signed 32 Bit (sal_Int32)
unsigned long	Unsigned 32 Bit (sal_uInt32)	Unsigned 32 Bit (sal_uInt32)
hyper	Signed 64 Bit (sal_Int64)	Signed 64 Bit (sal_Int64)
unsigned hyper	Unsigned 64 Bit (sal_uInt64)	Unsigned 64 Bit (sal_uInt64)
float	Processor dependent: Intel, Sparc = IEEE float (float)	Processor dependent: Intel, Sparc = IEEE float (float)
double	Processor dependent: Intel, Sparc = IEEE double (double)	Processor dependent: Intel, Sparc = IEEE double (double)
enum	A 32 bit value	A 32 bit value
boolean	A 8 bit value (sal_Bool)	A 8 bit value (sal_Bool)
char	16 Bit Unicode (sal_UniCode)	16 Bit Unicode (sal_UniCode)
string	A pointer to rtl_uString struct	A pointer to rtl_uString struct
struct	The struct contains the members in the order of their declaration. The memory layout is described at the beginning of this section.	The struct contains the members in the order of the declaration. The memory layout is described at the beginning of this section.
union (unsupported for now)	The size is 8+ size of the largest type. The first 64 bit values denotes the discriminant.	The size is 8+ size of the largest type. The first 64 bit values denotes the discriminant.
sequence	A pointer to sal_Sequence struct directly appending the elements.	A pointer to sal_Sequence struct directly appending the elements.
exception	is struct	is struct
interface	A pointer to uno_Interface struct.	A pointer to uno_Interface struct.
any	uno_Any struct: Anys cannot be nested, i.e. no any can contain an any!	uno_Any struct: Anys cannot be nested, i.e. no any can contain an any!
type	A pointer to typelib_TypeDescriptionReference struct.	A pointer to typelib_TypeDescriptionReference struct.
void	No memory representation	No memory representation

Remarks:

16 Bit UNO is not supported

Interfaces

All interfaces are derived from the interface com.sun.star.uno.XInterface. This interface is specified in the IDL language:

interface XInterface
{
    any queryInterface( [in] type aType );
    [oneway] void acquire();
    [oneway] void release();
};

In contrast to C++ vtable calling, binary UNO calls on a generic dispatcher function to perform calls on interfaces.

typedef void (SAL_CALL * uno_DispatchMethod)(
    uno_Interface * pUnoI,
    const typelib_TypeDescription * pMemberType,
    void * pReturn,
    void * pArgs[],
    uno_Any ** ppException );

/** The binary C uno interface description. */
typedef struct _uno_Interface
{
    void (SAL_CALL * acquire)( uno_Interface * pInterface );
    void (SAL_CALL * release)( uno_Interface * pInterface );
    uno_DispatchMethod pDispatcher;
} uno_Interface;

The lifetime of interfaces are controlled by acquire() and release(). Beware that the dispatch function expects an array of pointers to the parameter values (pArgs), which is for interfaces uno_Interface ** (pointer to interface reference storing an acquired pointer to the uno_Interface struct). To signal, that no exception has to be thrown, *ppException has to set to 0 before returning.

Author: Daniel Bölzle ($Date: 2004/11/27 05:48:04 $)
Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.

The Free and Open Productivity Suite

Binary UNO Specification

Contents

Abstract

Type Specification

Interfaces