Connecting your program to the LibreOffice/OpenOffice instance (or any UNO server), in order to read/write an office document or handle the instance.
Topics
About: UNO (Universal Network Objects)
About: LibreOffice
About: Apache OpenOffice
About: C++
The table of contents of this article
- Starting Context
- Target Context
- Orientation
- Main Body
- 1: Getting and Building the Console C++ UNO Client Sample
- 2: Executing the Sample Program
- 3: Understanding the Sample Program
- 3-1: Understanding the Projects Structure
- 3-2: What Matter in Order to Go Beyond Connecting to the UNO Server Using the Utility Projects
- 3-3: The Wrapper of UNO Objects Context
- 3-4: Creating a Local UNO Objects Context (Bootstrapping)
- 3-5: Connecting to the UNO Server
- 3-6: Cutting the Connection
- 4: Although There Is a Simpler Way of Connecting to an Office Instance . . .
- 5: The Conclusion and Beyond
Starting Context
- The reader has basic knowledge on C++ programming.
- The reader has knowledge on what UNO is and how it is related to LibreOffice or Apache OpenOffice.
- The reader has knowledge on basic elements of UNO and the terminology used for them in this series.
- The reader has built an environment for developing UNO programs in Linux or Windows, according to a previous article (here for Linux and here for Windows).
- The reader has knowledge on how to build any sample program of this series.
- The reader has knowledge on how to make any LibreOffice or Apache OpenOffice instance a UNO server.
Target Context
- The reader will know how to make his or her external console C++ program connect to any UNO server (for example, a LibreOffice or Apache OpenOffice instance).
Here are Hypothesizer 7, Objector 11A, and Objector 11B in front of a computer.
Orientation
Hypothesizer 7
In this article, we will get, build, execute, and understand a console C++ UNO client sample.
In fact, there is a previous article that is of a console Java UNO client sample, conceptually, the console C++ UNO client sample is no different from the console Java UNO client sample, and most of the descriptions in the previous article are valid for the console C++ UNO client sample except some programming language specific notations.
Objector 11A
So what? Are you telling me to read your damned previous article that is about Java while I am not any Java programmer and don't have any intention of becoming one?
Hypothesizer 7
Sir, I am not telling you to do anything, but am informing you that I will cite some subsections of my damned previous article and indicate how some notations in them should be replaced for C++, without making almost-same-with-some-descriptions-in-the-previous-article descriptions here.
Objector 11A
"informing"? You just inform what you have decided arbitrarily?
Hypothesizer 7
Sir, I have decided so because those subsections of the previous article seem quite enough for almost any C++ programmer; even the differences of the notations do not seem to have to be particularly indicated as they are obvious, although I explain them here based on my principle of making accurate descriptions.
Objector 11A
. . . What do you mean by "notations"?
Hypothesizer 7
Although they are what 'Main Body' explains, for example, the notation of the full name of any class in C++ is different from that in Java.
Objector 11A
Hmm . . .
Objector 11B
It's too bad for you that I don't have any intention of reading your articles cited in that 'Starting Context' as I just need a sample program.
Hypothesizer 7
That is not bad for me at all. I am just following my principle that I should clarify the prerequisites whenever I explain anything.
Main Body
1: Getting and Building the Console C++ UNO Client Sample
Hypothesizer 7
Here is a console C++ UNO client sample. How to build any sample project of this series is described in a previous article.
After expanding the ZIP file, 'hiConsoleCplusplusUnoClients' is the project directory of the sample program; the other two directories are of projects-common projects.
How to build your development environment is explained in a previous article (here for Linux and here for Windows).
Stage Direction
Hypothesizer 7 opens a terminal and builds the sample project.
2: Executing the Sample Program
Hypothesizer 7
Before we execute the sample program, we have to have started a LibreOffice or Apache OpenOffice instance so that it accepts connections from clients, as we can know how in a previous article.
Stage Direction
Hypothesizer 7 starts a LibreOffice instance with the port number 2002.
Hypothesizer 7
We can execute the sample program like this with the current directory positioned at the sample project directory and the file URL adjusted to our environment.
@bash or cmd Source Code
gradle i_executeCplusplusExecutableFileTask -Pc_commandLineArguments="socket,host=localhost,port=2002,tcpNoDelay=1;urp;StarOffice.ComponentContext file://${HOME}/myData/development/hiConsoleCplusplusUnoClients/execution/HiConsoleCplusplusUnoClientsTests.odt"
Stage Direction
Hypothesizer 7 executes the command in the terminal with the current directory positioned at the sample project directory. A OpenDocument Text file is opened and then closed immediately.
Objector 11A
Hmm . . .
Hypothesizer 7
We can just change the host name from 'localhost' if the LibreOffice or Apache OpenOffice instance is in a remote host, if some firewalls do not block the communication, of course.
Note that in Windows, '${HOME}' is like '/E:/home/tanichida'.
3: Understanding the Sample Program
Hypothesizer 7
As I mentioned in 'Orientation', the explanation for the console C++ UNO client sample is mostly same with that of the console Java UNO client sample, and I will cite some subsections of the previous article and indicate how some notations in them should be replaced for C++, without making almost-same-with-some-descriptions-in-the-previous-article descriptions here.
3-1: Understanding the Projects Structure
Hypothesizer 7
There are three projects: 'coreUtilitiesToBeDisclosed', 'unoUtilitiesToBeDisclosed', and 'hiConsoleCplusplusUnoClients'. 'coreUtilitiesToBeDisclosed' contains utility code pieces that are supposed to be commonly used in all kinds of projects; 'unoUtilitiesToBeDisclosed' contains utility code pieces that are supposed to be commonly used in UNO program projects; 'hiConsoleCplusplusUnoClients' is the sample project.
As the sample program does not do much than just uses 'unoUtilitiesToBeDisclosed', we have to look into the 'unoUtilitiesToBeDisclosed' project in order to learn how to make our external console C++ program connect to any UNO server.
Objector 11A
. . . The utility project contains also Java code?
Hypothesizer 7
In fact, it does as well as 'coreUtilitiesToBeDisclosed' does.
Objector 11A
. . . Do I need such Java code?
Hypothesizer 7
For the console C++ UNO client sample (and all (probably) the future C++ samples), no, you do not. I just have not separated utility code into programming-language-based projects. . . . If you do not want any Java code, you can just eliminate the 'source/java' directories.
3-2: What Matter in Order to Go Beyond Connecting to the UNO Server Using the Utility Projects
Hypothesizer 7
Just in case that you use the utility projects as they are, let us see what matter in order to go beyond connecting to the UNO server using the utility projects.
In fact, as the structure of the C++ utility classes accords with that of the Java utility classes, the descriptions of this subsection of the previous article are valid except some programming language specific notations.
Specifically, any Java full class name like "theBiasPlanet.unoUtilities.connectionsHandling.UnoConnection" should be replaced with the corresponding C++ full class name like '::theBiasPlanet::unoUtilities::connectionsHandling::UnoConnection'.
3-3: The Wrapper of UNO Objects Context
Hypothesizer 7
The '::theBiasPlanet::unoUtilities::connectionsHandling::UnoObjectsContext' class in the 'unoUtilitiesToBeDisclosed' project is a wrapper of 'UNO objects context'.
The descriptions on the wrapper of this subsection of the previous article are valid for here, except some programming language specific notations.
Specifically, any Java full class or interface name like "theBiasPlanet.unoUtilities.connectionsHandling.UnoObjectsContext" should be replaced with the corresponding C++ full class name like '::theBiasPlanet::unoUtilities::connectionsHandling::UnoObjectsContext'.
3-4: Creating a Local UNO Objects Context (Bootstrapping)
Hypothesizer 7
The descriptions on the concept of 'bootstrapping' of this subsection of the previous article are valid for here, although how to create the local UNO objects context is different for C++.
This is how to create the local UNO objects context, as can be seen in the constructor of the '::theBiasPlanet::unoUtilities::programsHandling::UnoProcessEnvironment' class.
@C++ Source Code
#include <com/sun/star/uno/Reference.hxx>#include <com/sun/star/uno/XComponentContext.hpp>#include <cppuhelper/bootstrap.hxx>Reference <XComponentContext> l_originalLocalObjectsContext = defaultBootstrap_InitialComponentContext ();
3-5: Connecting to the UNO Server
Hypothesizer 7
The descriptions on connecting to the UNO server of this subsection of the previous article are valid for here, except some programming language specific notations.
Specifically, any Java full class or interface name, or any static member name of any Java class or interface like "com.sun.star.connection.XConnector" should be replaced with the corresponding C++ full class name or static member name like '::com::sun::star::connection::XConnector'.
Objector 11A
. . . How about UNO service names and initial UNO object names?
Hypothesizer 7
They do not depend on the programming language.
3-6: Cutting the Connection
Hypothesizer 7
The descriptions on cutting the connection of this subsection of the previous article are valid for here, except some programming language specific notations.
Specifically, any Java full class or interface name like "theBiasPlanet.unoUtilities.connectionsHandling.UnoConnection" should be replaced with the corresponding C++ full class name like '::theBiasPlanet::unoUtilities::connectionsHandling::UnoConnection'.
4: Although There Is a Simpler Way of Connecting to an Office Instance . . .
Hypothesizer 7
Actually, there is a simpler way of connecting to an office instance, but that way has some limitations, which are critical in certain cases.
The discussion in this section of the previous article is valid for here.
5: The Conclusion and Beyond
Hypothesizer 7
Now, we can connect to any UNO server from our console C++ UNO client.
The reason why I have specified that the sample is a 'console' client is that a GUI C++ UNO client sample will come in a future article.
The GUI C++ UNO client might not seem to have to be different from the console C++ UNO client UNO-wise, but there is a difference: as the UNO client is supposed to be up for long duration, it is more appropriate to detect connection cuts caused by the UNO server or the network.
And we will look at UNO clients in another program language (C#) in future articles.
