Revision as of 12:46, 26 July 2006

For an introduction, you can read the tutorial.

Services and Interfaces

Introduction

See tutorial (in pdf) chapter 2 In OpenOffice API, a "service" is an abstract concept providing certain interfaces and properties/attributes. As Developer's Guide states : “Properties are data in an object that are provided by name over a generic interface for property access, that contains getPropertyValue() and setPropertyValue() access methods.”. It would be better to distinguish between attribute and property. A service has a collection of properties and an interface is a collection of methods that provide a means to change properties.

Danny Brewer's rules

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.)

2. A service can include zero or more services. (which each service can recursively follow these rules.)

3. A service can export (implement) interfaces.

4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.)

6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.)

7. An interface can implement methods.

8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

IDL specification

Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language. The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

Specifying an interface

We choose as an example, the interface XdrivingDirection (not in OOo):

// IDL
interface XdrivingDirection
	{
		void turnLeft();
		void turnRight();
	};

Specifying a service

Example above is still used, here is the corresponding IDL specification :

// IDL
interface XdrivingDirection
	{
		void turnLeft();
		void turnRight();
	};
interface XaccelerationControl
	{
		void speedUp();
		void slowDown();
	};
service car
	{
		// exported interfaces:
		interface XdrivingDirection;
		interface XaccelerationControl;
		[attribute] float speed; 
		[attribute] float angle;
	};

We see a float type and we would use other IDL types later.

Specifying a module

Now, the same example would give this IDL specification :

// IDL
module my_module
	{
	interface Xsomething
		{
			void methodone();
		};
	service my_service1
		{
			// exported interfaces:
			interface Xsomething;
		};
	interface XsomethingElse
		{
			void methodTwo();
			void methodThree();
		};
	service my_service2
		{
			// exported interfaces:
			interface XsomethingElse;
		};
};

Further with IDL

The IDL's types are :

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : the counter example

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface. An example of interface inheritance :

//IDL
interface animal {
	attribute long age;
};
interface dog : animal {
	attribute short leg;
}

Multiple inheritance is also possible :

// IDL
interface dog : animal, friend {

Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining shapes.

Gathering UNO information with IDL files

There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available here). Problem : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : General OOoWEB Index

We have provided examples in previous chapters (particularly programming OOoWriter in C++) and then normally reader has skills on the subject. We recall however the points (from Danny Brewer's post in OOoForum).

Danny Brewer 's Point of View

Nonetheless, it is important to understand the concept of a "service" in the API docs. A service is just a way to group....

1. more services
2. interfaces

The (1) more services part, of course, means that there are even more interfaces available at the original service. Let me give a different example. SpreadsheetDocument is a service. SpreadsheetDocument includes the service OfficeDocument. The correponding IDL file shows us this point :

//Listing 7 Interface Specification
//IDL
service SpreadsheetDocument
{
	//-------------------------------------------------------------------------

	/** common service for all types of documents.
	 */
	service com::sun::star::document::OfficeDocument;

	..........

	//-------------------------------------------------------------------------

	/** provides access to the collection of spreadsheets.
	 */
	interface com::sun::star::sheet::XSpreadsheetDocument;

	//------------------------------------------------------------------------- 

Therefore, the combined set of interfaces from both SpreadsheetDocument and OfficeDocument are available at a Spreadsheet document. So, even though loadComponentFromURL returns some interface, that interface represents an underlying service which is a SpreadsheetDocument. By looking at the API docs, you can tell what valid interfaces you may query. SpreadsheetDocument has service XSpreadsheetDocument. OfficeDocument has service XPrintable and XStorable. Since SpreadsheetDocument includes OfficeDocument, it is therefore valid to queryInterface for either XPrintable or XStorable from a SpreadsheetDocument.

Now in the above discussion, substitute TextDocument for SpreadsheetDocument. How to tell what is the underlying service?

There is no magic formula for that. Generally it is obvious. If you load a Spreadsheet, then you have the SpreadsheetDocument service.

Similarly, if I create an object by its service name..... oShape = oDoc.createUnoService( "com.sun.star.drawing.EllipseShape" ) then I know what service it is, because I gave the service name.

You can always tell what interfaces are available if you know the name of the service -- just by looking at the API docs. No guesswork. No need for Xray. It is an absolute science. The collection of valid interfaces are the interfaces of the service itself, and of all of the services which the service includes, recursively.

In some cases, it is fairly clear what service you have.

If you call getCellRangeByName(), then you have a SheetCellRange. If you call getCellByPosition(), then you only have a SheetCell. Many of the same things are available on both a SheetCell and a SheetCellRange, but they are different animals. A SheetCellRange does represent a rectangular group of cells, while a SheetCell represents only a single cell. There are things you can do to a single cell that you cannot do to a group of cells together.

There are other issues as well. If you get a com.sun.star.table.CellRange from a table, it is just that. But if you get one from a spreadsheet, it is not only that, but it is really a com.sun.star.sheet.SheetCellRange. The SheetCellRange is merely an extended version of the CellRange. Which of the two services you have depends on whether you called getCellRangeByName() on a table, or on a spreadsheet.

Sometimes, especially in Writer, only the Developer's Guide helps clear up exactly what underlying service you get back from some other API method call. Writer is especially bad about that. But it is always the case that when you know what service you have, you can directly deduce, only from the API docs, exactly all of the interfaces that are valid to query. No guesswork. It is an exact science.

A concrete Example

The IDL files are available with SDK in <OpenOffice.org1.1_SDK>/idl/ directory. Evidently, the problem with this way is we only see SDK's UNO which can be slightly different from our Openoffice.org : remember the SDK comes months after a new version of Openoffice.org (it's not the case now). However, we will explain this way after just mentioning an other way : registry exploring. In fact, at the moment, I have no idea what kind of information can be derived from registery (see UNO registery and Bootstrapping)

We want now to show an example : we start from a ::com::sun::star::document::OfficeDocument and then examine <OpenOffice.org1.1_SDK>/idl/com/sun/star/document/OfficeDocument.idl presented below, (with removing all comments) :

//Listing 8 Interface Specification
//IDL
service OfficeDocument
{
	interface com::sun::star::frame::XModel;
    interface com::sun::star::util::XModifiable;
	interface com::sun::star::frame::XStorable;
	interface com::sun::star::view::XPrintable;
    [optional] interface XEventBroadcaster;
	[optional] interface XEventsSupplier;
    [optional] interface XDocumentInfoSupplier;
    [optional] interface XViewDataSupplier;
    [optional] interface com::sun::star::view::XPrintJobBroadcaster;
	[property, optional] boolean AutomaticControlFocus;
	[property, optional] boolean ApplyFormDesignMode;
};

Remember we have already tackled Interfaces in this section. This conduct us to the [[1]]. If we now examine the

com::sun::star::text::TextDocument we find in <OpenOffice.org1.1_SDK>/idl/com/sun/star/text/TextDocument.idl

service TextDocument
{
	service com::sun::star::document::OfficeDocument;
	interface com::sun::star::text::XTextDocument;
	interface com::sun::star::util::XSearchable;
	interface com::sun::star::util::XRefreshable;
	....
};

IDL and C++

This problem is tackled in Developer's guide

Getting an interface in C++

In C++, you only have variables of an Interface type. One of the most often encountered problem in C++ programming is querying an interface. This problem occurs very rarely in OooBasic but very often in C++/Java. We can find an example in "SDK C++ language" and many other in Office UNO automation. As an example, we suppose we have to get a com::sun::star::document::officeDocument service. This is done in general by something like: [cpp] //Listing 2 C++ code to get a service //C++ Reference<com::sun::star::document::officeDocument> OfDoc = something_to_get_this_service(); or [cpp] Listing 3 using namespace to simplify the code //C++ using namespace com::sun::star::document; .... Reference<officeDocument> OfDoc = something_to_get_this_service(); and we want to query the XStorable interface to save our document. Three steps are involved in this query :

1. Add your code's line as UNO's query

[cpp] //Listing 4 The UNO query in C++ code // C++ // query from com::sun::star::frame::XStorable interface Reference< XStorable > oToStore (OfDoc, UNO_QUERY);

1. Add the hpp file in an include statement. Add the corresponding namespace in an using namespace statement. Including is done with :

[cpp] //Listing 5 The corresponding include statement //C++ #include <com/sun/star/frame/XStorable.hpp> and the corresponding namespace statement is : [cpp] //Listing 6 The corresponding namespace statement //C++ using namespace com::sun::star::frame;

1. Add the corresponding type in the makefile as shown below in red :

# makefile
# added com.sun.star.frame.XStorable
TYPES := \
	com.sun.star.uno.XNamingService \
	....
	com.sun.star.uno.XAggregation \
	com.sun.star.frame.XStorable \
	com.sun.star.lang.XMain \ 
    ...
    com.sun.star.container.XHierarchicalNameAccess

Learn to realize these three steps : you can not program in C++ without encountering an interface's query. This problem of asking an interface is already tackled in chapters 3 and 4. An other more technical problem is the mapping : you have an IDL file, how is it compiled in C++ ? The next chapter tackle the subject : you can skip it in a first reading and go on into the chapter 1.5.

Mapping for Modules and Interfaces

For instance:

// IDL 
module M 
{ struct E { long L; 
  }; 
}; 

is mapped into: [cpp] // C++ namespace M { struct E

 { Long L; }; 

} and E can be referred outside of M as M::E. Alternatively, a C++ using statement for namespace M can be used so that E can be referred to simply as E: [cpp] // C++ using namespace M; E e;

 e.L = 3;

Core reflection service and its Interfaces

Many entry points for reflection are descibed in the SDK. We give again any of them here and show a way to use them with C++.

XIdlReflection interface

This interface is described here

The XIntrospection Interface

This interface is described here with code's example. Other code is given in Constructing Helpers section.

Using Java Inspector

For an introduction of using Java with OOo, see Java and Eclipse tutorial. This point is not tackled here : we are only interested by using a Java component with C++.

It is possible in principle, to use the Java inspector tools from every programming languages because it's a component. The way to do that is very simple :

1°) Compile the java example in <OpenOffice.org_SDK>/examples/java/Inspector after adding SDK_AUTO_DEPLOYMENT = YES in the beginning of makefile.

2°) Create a OOoBasic example, for instance : [oobas] 'Listing 17 Simple OOoBasic example to call the Java Inspector

REM ***** BASIC ***** Sub JavaInspector o = createUnoService("org.OpenOffice.InstanceInspector") 'XRay.XRay o oReflection = createUnoService( "com.sun.star.reflection.CoreReflection" ) o.inspect(oReflection) End Sub If java is not properly installed when running this program a dialog box will print out. Follow the instructions to install it (you have to know where your virtual machine (JRE) is installed. We see below in Figure what is the result of this program.

Our problem is now to use the Java Inspector from C++. But I encounter a problem when I try to do that. Here is the way I choose :

1. construct a urd file starting from IDL (in makefile)
2. don't forget the registry of urd file in makefile
3. add org.OpenOffice.XInstanceInspector in the TYPES macro in the makefile
4. copy IDL file from <OpenOffice.org1.1_SDK>/examples/java/Inspector/XInstanceInspector.idl into <OpenOffice.org1.1_SDK>/idl/org/OpenOffice/ XInstanceInspector.idl
5. add the #include <org/OpenOffice/XInstanceInspector.hpp> and using namespace org::OpenOffice;
6. add this code

[cpp] // C++ Any toInspect; toInspect <<= rDesktop; Reference< XInstanceInspector > xinspect (rOfficeServiceManager->createInstance(

   OUString::createFromAscii( "org.OpenOffice.InstanceInspector" )),UNO_QUERY);
   xinspect->inspect(toInspect);

And it works like in OOoBasic. The corresponding Linux makefile is :

#Listing 18 Simple Makefile to compile a Java Inspector C++ call
# very simple makefile
HELPER = ReflectionHelper
CXXFILE = office_connect.cxx
OBJFILE = office_connect.o
OUTBIN = office_connect
OUT_COMP_INC = ../../../../LINUXexample.out/inc
OUT_COMP_OBJ = ../../../../LINUXexample.out/obj
OUT_COMP_BIN = ../../../../LINUXexample.out/bin
# added for Inspector
OUT_COMP_URD = $(OUT_COMP_BIN)
# end added
COMPONENT_RDB = $(OUT_COMP_BIN)/office_connect.rdb
CC_FLAGS = -c -O -fpic -fno-rtti
CC_DEFINES = -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3
PS = /
TYPES := \
	com.sun.star.uno.XNamingService \
	....
	com.sun.star.container.XHierarchicalNameAccess \
	org.OpenOffice.XInstanceInspector
# last line added

TYPESLIST = $(foreach t,$(TYPES),-T$(t))
GENHPPFILES = $(foreach t,$(TYPES),$(OUT_COMP_INC)/$(subst .,/,$(t)).hpp)

ALL : \
    ProUNOCppBindingExample

# added for Inspector
#building urd file
$(OUT_COMP_URD)/XInstanceInspector.urd : ../../../../idl/org/OpenOffice/XInstanceInspector.idl
	-mkdir -p $(OUT_COMP_URD)
	idlc -I. -I../../../../idl -O$(OUT_COMP_URD)  ../../../../idl/org/OpenOffice/XInstanceInspector.idl

# end added

#office_connectrc is provided with SDK
$(OUT_COMP_BIN)/office_connectrc : office_connectrc
	-mkdir -p $(OUT_COMP_BIN)
	cp office_connectrc $(OUT_COMP_BIN)/office_connectrc

$(COMPONENT_RDB) : $(OUT_COMP_URD)/XInstanceInspector.urd
	-mkdir -p $(OUT_COMP_BIN)
# added for Inspector
	regmerge $(COMPONENT_RDB) /UCR $(OUT_COMP_URD)/XInstanceInspector.urd
# end added
	regmerge $(COMPONENT_RDB) / "/usr/lib/openoffice/program/types.rdb"
	@echo --------------------------------------------------------------------------------
	@echo   Register necessary runtime components in $(COMPONENT_RDB)
	@echo --------------------------------------------------------------------------------
	regcomp -register -r $(COMPONENT_RDB) -c connector.uno.so
	regcomp -register -r $(COMPONENT_RDB) -c remotebridge.uno.so
	regcomp -register -r $(COMPONENT_RDB) -c bridgefac.uno.so
	regcomp -register -r $(COMPONENT_RDB) -c uuresolver.uno.so
#	@echo bla > $@

$(GENHPPFILES) :  $(subst /,$(PS),$(@D))
	mkdir -p $(subst /,$(PS),$(@D))
# modified for Inspector	cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) "/usr/lib/openoffice/program/types.rdb"
	cppumaker -Gc -BUCR -O$(OUT_COMP_INC) $(TYPESLIST) $(COMPONENT_RDB)

$(OUT_COMP_OBJ)/$(OBJFILE) : $(CXXFILE) $(GENHPPFILES) $(HELPER).hpp
	-mkdir -p $(subst /,$(PS),$(@D))
	gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
	-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(OBJFILE) $(CXXFILE)

$(OUT_COMP_OBJ)/$(HELPER).o : $(HELPER).cxx $(HELPER).hpp
	-mkdir -p $(OUT_COMP_OBJ)/
	gcc $(CC_FLAGS) $(CC_INCLUDES) -I. -I/usr/include -I$(OUT_COMP_INC)/examples \
	-I../../../../include -I$(OUT_COMP_INC) $(CC_DEFINES) -o$(OUT_COMP_OBJ)/$(HELPER).o $(HELPER).cxx


$(OUT_COMP_BIN)/$(OUTBIN) : $(OUT_COMP_OBJ)/$(OBJFILE) $(OUT_COMP_OBJ)/$(HELPER).o
	-mkdir -p $(OUT_COMP_BIN)
	gcc -Wl -export-dynamic -L../../../../LINUXexample.out/lib -L../../../../linux/lib -L/usr/lib/openoffice/program \
	$(OUT_COMP_OBJ)/$(HELPER).o \
	-o$(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_OBJ)/$(OBJFILE) -lcppuhelpergcc3 -lcppu -lsalhelpergcc3 -lsal -lstlport_gcc


ProUNOCppBindingExample : $(COMPONENT_RDB) $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
	@echo --------------------------------------------------------------------------------
	@echo Please use one of the following commands to execute the examples!
	@echo
	@echo make office_connect.run
	@echo --------------------------------------------------------------------------------

office_connect.run : $(OUT_COMP_BIN)/$(OUTBIN) $(OUT_COMP_BIN)/office_connectrc
	cd $(OUT_COMP_BIN) && $(OUTBIN)

See Also

• Using C++ with OOo SDK : Main Page
• UNO tutorial
• UNO IDL
• Uno/Article/Types&Reflection
• IDL Files and C++ (Chapter 10 from UNO/C++ document)
• Writing a Program to Control OpenOffice.org, by Franco Pingiori — Part 1 and Part 2, Linux Journal