Transparent Use of Office UNO Components

From Apache OpenOffice Wiki
Jump to: navigation, search

When writing C++ client applications, the office component context can be obtained in a more transparent way. For more details see section Transparent Use of Office UNO Components (Java).

The bootstrap function

Also for C++, a bootstrap function is provided, which bootstraps the component context from a UNO installation. An example for a simple client application shows the following code snipplet:

  // get the remote office component context
  Reference< XComponentContext > xContext( ::cppu::bootstrap() );
  // get the remote office service manager
  Reference< XMultiComponentFactory > xServiceManager(
      xContext->getServiceManager() );
  // get an instance of the remote office desktop UNO service
  // and query the XComponentLoader interface
  Reference < XComponentLoader > xComponentLoader(
      xServiceManager->createInstanceWithContext( OUString(
      xContext ), UNO_QUERY_THROW );

The ::cppu::bootstrap() function is implemented in a similar way as the Java method. It first bootstraps a local component context by calling the ::cppu::defaultBootstrap_InitialComponentContext() function and then tries to establish a named pipe connection to a running office by using the service. If no office is running, an office process is started. If the connection succeeds, the remote component context is returned.

Documentation caution.png The ::cppu::bootstrap() function is only available since 2.0.

SDK tooling

For convenience the Apache OpenOffice Software Development Kit (SDK) provides some tooling for writing C++ client applications.

Application Loader

A C++ client application that uses UNO is linked to the C++ UNO libraries, which can be found in the program directory of a UNO installation. When running the client application, the C++ UNO libraries are found only, if the UNO program directory is included in the PATH (Windows) or LD_LIBRARY_PATH (Unix/Linux) environment variable.

As this requires the knowledge of the location of a UNO installation, the SDK provides an application loader (unoapploader.exe for Windows, unoapploader for Unix/Linux), which detects a UNO installation on the system and adds the program directory of the UNO installation to the PATH / LD_LIBRARY_PATH environment variable. After that, the application process is loaded and started, whereby the new process inherits the environment of the calling process, including the modified PATH / LD_LIBRARY_PATH environment variable.

The SDK tooling allows to build a client executable file (e.g. SimpleBootstrap_cpp for Unix/Linux), which can be invoked by


In this case, the SimpleBootstrap_cpp executable is simply the renamed unoapploader executable. All the application code is part of a second executable file, which must have the same name as the first executable, but prefixed by a underscore '_'; that means in the example above the second executable is named _SimpleBootstrap_cpp.

On the Unix/Linux platforms the application loader writes error messages to the stderr stream. On the Windows platform error messages are written to the error file <application name>-error.log in the application's executable file directory. If this fails, the error file is written to the directory designated for temporary files.

Finding a UNO Installation

A UNO installation can be specified by the user by setting the UNO_PATH environment variable to the program directory of a UNO installation, e.g.

 setenv UNO_PATH /opt/

If no UNO installation is specified by the user, the default installation on the system is taken.

On the Windows platform, the default installation is read from the default value of the key 'Software\\UNO\InstallPath' from the root key HKEY_CURRENT_USER in the Windows Registry. If this key is missing, the key is read from the root key HKEY_LOCAL_MACHINE.

On the Unix/Linux platforms, the default installation is found from the PATH environment variable. This requires that the soffice executable or a symbolic link is in one of the directories listed in the PATH environment variable.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages