SDKCppLanguage

The UNO C++ Language

The aim of this chapter is to explain peculiarities of the C++ language in the UNO environment and not to provide skills on traditional C++. To put it differently, I want to give here the UNO/C++ background, quite helpful in getting us started. You can find e-Books on C++ here.

Our starting Example : Simple Binaries (Executable)

We want now to start with a SDK example. The purpose of the example presented is to create an executable which interacts with OpenOffice.org. We can imagine two kind of interactions : direct interaction with OpenOffice.org or interaction with one of OOo's shared library. We focus on this second case where the makefile is simpler. The shared library involved is then cppuhelper.uno.so (cppuhelper.uno.dll under Windows). Former case will be examined later. I assume (I know nobody of the SDK team) this example is given to provide the simplest example we can do with the SDK. This is the Lifetime example : see at “<OpenOffice.org1.1_SDK>/examples/DevelopersGuide/ProfUNO/Lifetime”

Before diving into the examples, you will need to set up your programming environment so you can create UNO programs. What's required depends on what platform you're working. This is shown in the first example with LINUX platform. To check this example you only have to launch the makefile :

cd <OpenOffice.org1.1_SDK>
./setsdkenv_unix
cd examples/DevelopersGuide/ProfUNO/Lifetime
make
make ProfUnoLifetime.runexe

The last command line only launch the binary executable “ProfUnoLifetime” which interact with cpphelper.uno.so (cppuhelper.uno.dll under Windows) even if OpenOffice.org is not running. This example only create and release an object, not more. The constructor and destructor of the object only write out a message. Its little size allow us to give its code here :

// C++
#include <stdio.h>
#include <cppuhelper/weak.hxx>

class MyOWeakObject : public ::cppu::OWeakObject
{
public:
    MyOWeakObject() { fprintf( stdout, "constructed\n" ); }
    ~MyOWeakObject() { fprintf( stdout, "destructed\n" ); }
};


void simple_object_creation_and_destruction()
{
    // create the UNO object
    com::sun::star::uno::XInterface * p = new MyOWeakObject();

    // acquire it, refcount becomes one
    p->acquire();

    fprintf( stdout, "before release\n" );

    // release it, refcount drops to zero
    p->release();

    fprintf( stdout, "after release\n" );
}


int main( char * argv[] )
{
    simple_object_creation_and_destruction();
    return 0;
}

The two methods acquire and release will be encounter later. What they exactly do is not important for the moment. This example recall us how to write a class which inherits from an other class, how to write and call methods and how to instantiate the class. All the listings given below only need to modify this C++ code compile it and run it. You can therefore use the same makefile by possibly changing the name of the source file (tackled in next section).

Types

The UNO types are given in the table below :

UNO Types

UNO	Type description	Java	C++	Basic
char	16-bit unicode character type	char	sal_Unicode	-
boolean	boolean type; true and false	boolean	sal_Bool	Boolean
byte	8-bit ordinal type	byte	sal_Int8	Integer
short	signed 16-bit ordinal type	short	sal_Int16	Integer
unsigned short	unsigned 16-bit ordinal type	-	sal_uInt16	-
long	signed 32-bit ordinal type	int	sal_Int32	Long
unsigned long	unsigned 32-bit type	-	sal_uInt32	-
hyper	signed 64-bit ordinal type	long	sal_Int64	-
unsigned hyper	unsigned 64-bit ordinal type	-	sal_uInt64	-
float	processor dependent float	float	float (IEEE float)	Single
double	processor dependent double	double	double (IEEE double)	Double

The UNO's column represents all the types you can find in the specifications files : IDL files. We describe IDL files later (see chapter 10). The C++ column is what we are interested in when we program with this language. If you want to check the different programs given in this chapter, you can use the <OpenOffice.org1.1_SDK>/examples/DevelopersGuide/ProfUNO/Lifetime example. Replace the complete object_lifetime.cxx by the listing below (don't forget to save the old file)

// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>

main( ) {
	sal_Int32 var1;
	var1 = 34;
	printf("The var1 value is : %d\n",var1);
   	return 0;
}

then launch

make ALL
make ProfUnoLifetime.runexe

and it works. Don't forget ./setsdkenv_unix (only one time) on Linux and the corresponding command (setsdkenv_windows.bat) on Windows.

Sequences

A sequence is an abstract view of a set of UNO types with a variable number of elements. As first example, we give a very simple program :

// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;

main( ) {
	Sequence < sal_Int32 > SetOfInt(5);
	//var1 = 34;
	SetOfInt[2]=44;
	printf("The value is : %d\n",SetOfInt[2]);
    return 0;
}

The important things to notice are as follows :

• the type of each element of the set is put between angular brackets : "<" and ">". In the example above sal_int32 is the type.
• declaration of sequence is done with parenthesis "(" and ")" and the number of elements of the sequence between them. In the example above a sequence of five sal_Int32 elements is declared.

accessing elements of the sequence is done with "[" and "]" and an index between them. This allows us to say that sequences are referenced like arrays. But they are different in some way, for instance they have not a fixed size.

• We have to include Sequence.hxx file in a program when using sequence. Note that this file is provided with the SDK and this not always the case for all hxx files (some of them have to be reconstructed).

We have to use the correct namespace with adding "using namespace ..." If you don't use this statement you have to write com::sun::star::uno::Sequence instead of Sequence. A Sequence can be created with arbitrary UNO type but not with other types. The object SetOfInt has many methods. We give an example to show any of them :

// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;

main( ) {
	Sequence < sal_Int32 > SetOfInt(5);
	sal_Int32 *table;
	SetOfInt[2]=44;
	printf("The value is : %d\n",SetOfInt[2]);
	// Tests whether the sequence has elements, i.e. elements count is greater than zero
	if (SetOfInt.hasElements()) printf("Set not empty\n");
	// Gets a pointer to elements array for reading and writing. If the sequence 
	//  has a length of 0, then the returned pointer is undefined
	table = SetOfInt.getArray();
	table[4]=78;
	printf("The value is : %d\n",SetOfInt[4]); // prints out 78
	SetOfInt.realloc(7);
	printf("New length : %d\n",SetOfInt.getLength()); // prints out 7
	return 0;
}

The comments explain what is printed out when executing this example. The method realloc is particularly important : it allows the size of set to change.

Let us focus on using sequences in function or as parameter. An example is again more descriptive than a long text :

// C++
// function
Sequence < sal_Int32 > initSequence(){
	sal_Int32 sourceArray[5]={1,2,3,4,5};
	Sequence < sal_Int32 > SeqOfInt(sourceArray,5);
	return SeqOfInt;
}
// reference parameter
void initSequence2(Sequence < sal_Int32 > &SeqOfInt ) {
	sal_Int32 sourceArray[4]={1,2,3,4};
	Sequence < sal_Int32 > SeqOfInt2(sourceArray,4);
	SeqOfInt=SeqOfInt2;
}

An obvious call could be :

// C++
	SetOfInt = initSequence();
	printf("New length : %d\n",SetOfInt.getLength()); // prints out 5
	initSequence2(SetOfInt);
	printf("New length : %d\n",SetOfInt.getLength()); // prints out 4

See other material in Developer's Guide (UNO C++ Binding).