Difference between revisions of "Documentation/DevGuide/ProUNO/CLI/Writing Client Programs"

Revision as of 10:54, 12 March 2009

To build a client program it must reference at least cli_types.dll and cli_cppuhelper.dll. Also cli_ure can be referenced when one of its classes is used. These libraries are installed in the GAC and the program folder of the office installation. The referencing is done by certain compiler switches, for example /AI for C++ (with managed extensions) or /reference for the C# compiler. C++ also requires dlls to be specified by using the #using:

 #using <mscorlib.dll>
 
 #using <cli_types.dll>

The following example discusses how to use services provided by a running office process:

The starting point of every remote client program is a component context. It is created by a static function defaultBootstrap_InitialComponentContext, which is provided by the class uno.util.Bootstrap. The context provides the service manager by which UNO components can be created. However, these components would still be local to the client process, that is, they are not from a running office and therefore cannot affect the running office. What is actually needed is a service manager of a running office. To achieve that, the component com.sun.star.bridge.UnoUrlResolver is used, which is provided by the local service manager. The UnoUrlResolver connects to the remote office and creates a proxy of the office's service manager in the client process. The example code (OOo 2.x) is as follows:

  //C# example
  System.Collections.Hashtable ht = new System.Collections.Hashtable();
  ht.Add("SYSBINDIR", "file:///<office-dir>/program");
  unoidl.com.sun.star.uno.XComponentContext xLocalContext =
           uno.util.Bootstrap.defaultBootstrap_InitialComponentContext(
           "file:///<office-dir>/program/uno.ini", ht.GetEnumerator());
 
  unoidl.com.sun.star.bridge.XUnoUrlResolver xURLResolver = 
                    (unoidl.com.sun.star.bridge.XUnoUrlResolver) 
                            xLocalContext.getServiceManager().
                                     createInstanceWithContext("com.sun.star.bridge.UnoUrlResolver",
                   xLocalContext);
 
  unoidl.com.sun.star.uno.XComponentContext xRemoteContext =
           (unoidl.com.sun.star.uno.XComponentContext) xURLResolver.resolve(
                    "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext");
 
  unoidl.com.sun.star.lang.XMultiServiceFactory xRemoteFactory =
           (unoidl.com.sun.star.lang.XMultiServiceFactory)
                    xRemoteContext.getServiceManager();

For OOo 3.x the code is this:

//C# example for OOo 3.x
//Workaround which is needed when using a socket connection
//This will initialize the Windows socket library.
System.Net.Sockets.Socket s = new System.Net.Sockets.Socket(
AddressFamily.InterNetwork, SocketType.Raw, ProtocolType.IP);
//
XComponentContext xLocalContext = 
String sUnoIni = "file:///d:/OpenOffice.org%203/URE/bin/uno.ini";
XComponentContext xLocalContext = 
    uno.util.Bootstrap.defaultBootstrap_InitialComponentContext(sUnoIni, null);
XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
 
XUnoUrlResolver xUrlResolver =
    (XUnoUrlResolver)xLocalServiceManager.createInstanceWithContext(
        "com.sun.star.bridge.UnoUrlResolver", xLocalContext);
 
XMultiServiceFactory multiServiceFactory =
    (XMultiServiceFactory)xUrlResolver.resolve(
         "uno:socket,host=localhost,port=8100;urp;StarOffice.ServiceManager");

Alternatively one could use pipe connection, in which case, no socket needs to be created beforehand.

//C# example for OOo 3.x
XComponentContext xLocalContext = 
String sUnoIni = "file:///d:/OpenOffice.org%203/URE/bin/uno.ini";
XComponentContext xLocalContext = 
    uno.util.Bootstrap.defaultBootstrap_InitialComponentContext(sUnoIni, null);
XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
 
XUnoUrlResolver xUrlResolver =
    (XUnoUrlResolver)xLocalServiceManager.createInstanceWithContext(
        "com.sun.star.bridge.UnoUrlResolver", xLocalContext);
 
XMultiServiceFactory multiServiceFactory =
    (XMultiServiceFactory)xUrlResolver.resolve(
         "uno:pipe,name=some_unique_pipe_name;urp;StarOffice.ServiceManager");

With the factory of the running office at hand, all components of the remote office are accessible.

For a client to connect to a running office, the office must have been started with the proper parameters. In this case, the command line looks like this:

 soffice -accept=socket,host=localhost,port=2002;urp

or using a pipe connection

 soffice -accept=pipe,name=pipe_name;urp

A complete invocation of OOo could look like this:

Other useful command line options for OOo are: -minimized -invisible -nologo -nolockcheck -nodefault

More information about interprocess communication can be found in the Developer's Guide, in chapter UNO Interprocess Connections.

The example shows a scenario where an office is controlled remotely. It is, however, possible to write UNO applications that do not depend on a running office. Then, you would typically provide an own database of registered services. For more information, see Manual Component Installation.

There is an overloaded function uno.util.Bootstrap.defaultBootstrap_InitialComponentContext, which does not take arguments. It is intended to always connect to the most recently installed office. It is even capable of starting the office. To do that, the function needs to know where the office is located. This information is obtained from the windows registry. During installation either the key HKEY_CURRENT_USER\Software\OpenOffice.org\UNO\InstallPath or HKEY_LOCAL_MACHINE\Software\OpenOffice.org\UNO\InstallPath is written dependent on whether the user chooses a user installation or an installation for all users. The function uses the key in HKEY_CURRENT_USER first, and if it does not exists it uses the key in HKEY_LOCAL_MACHINE. In case the office does not start, check these keys. Also make sure that the PATH environment variable does not contain the program path to a different office.Implementing UNO Interfaces

The CLI-UNO language binding does not support UNO components that are written in a CLI language. Instead, it acts as a liaison between a CLI client program and an office. The client program usually obtains UNO objects from the office and performs operations on them. Therefore, it is rarely necessary to implement UNO interfaces.

To receive notifications from UNO objects, then, it is necessary to implement the proper interfaces. Also, interfaces can be implemented in order to use the objects as arguments to UNO methods.

Interfaces are implemented by declaring a class that derives from one or more interfaces, and which provides implementations for the interface methods. How this is done is covered by the respective documentation of the various CLI languages.