CLI Language Binding

From Apache OpenOffice Wiki
Jump to: navigation, search



The CLI (Common Language Infrastructure) language binding allows CLI programs to connect to an office and perform operations on it, such as creating and converting documents. A CLI-program consists of IL (Intermediate Language) code and can be produced by tools, such as C# or VB .NET compilers. The binding provides for type-safe programming. All UNO types are available as CLI types.

CLI - components are not fully supported. That is, although one can implement UNO interfaces in a CLI language there is no support for creating instances by means of the office's service manager. More accurately, one cannot register the components with unopkg and load them later from within the running program.

Currently the language binding is only available for the Windows operating system.

Terms

The following CLI-related abbreviations are used within this document:

  • IL = Intermediate Language
  • CLI = Common Language Infrastructure
  • CLR = Common Language Runtime
  • CTS = Common Type System

Requirements

The language binding is part of Apache OpenOffice and is only available for Windows platforms. Refer to the documentation of the Microsoft .NET Framework to find out which operating systems are supported and which prerequisites have to be fulfilled. A Microsoft .NET Framework Version 1.1 must be installed.

As of OpenOffice.org 3.0 the .NET Framework 3.5 is required. Only one office may be installed. That is, no different versions or different brands of Apache OpenOffice may be installed at the same time.

Supported Languages

The language binding should generally enable all CLI languages to be used with UNO. However, not every language may be suitable, because of missing features. For example, since UNO uses out parameters, the CLI language must support it as well, which is not given in JScript .NET.

The language binding was successfully tested with C# and VB code. We found that the C++ compiler provides false IL code in conjunction with arrays of enumeration values. This can cause exceptions, as the following example shows:

  __value enum Colors {Red, Green, Blue}; 
 
  public __gc class Test
  {
  public:
    static void foo()
    {
        Colors ar[] = new Colors[1];
    ar[0] = Red;
    Object* o = ar->GetValue(0);
    }
  //... 
  }

When calling ar->GetValue(0), then a System.ExecutionEngineException is thrown. Looking at the IL reveals two significant differences to code produced by a C# compiler. First, the array ar is constructed as array of System.Enum and not as Colors. Therefore ar->GetType() would return a type for System.Enum instead of Colors. Second, ar->GetValue() is compiled to a “call” instruction instead of “callvirt”. The example caused the same exception even when compiled with a compiler from the framework SDK version 1.1.

As a workaround you can provide arrays of System.Int32 for pure in parameter. There is no workaround for in/out and out parameter. Return values are not affected by this bug.

Another problem is that C++ does not support jagged arrays. Although it is possible to create an array of System.Array it is no substitute for a jagged array, since they have different types. Therefore, the compiler will produce an error if you try to pass an Array instance rather then a jagged array.

Running on 64 Bit Platforms

OOo 3.0, built by Sun, is built for a 32 bit Windows but also runs on 64 bit. To run cli applications on 64 bit one needs to have the 32bit .Net Framework installed (version 3.5 as of OOo 3.0). The application must be built for the x86 platform (see platform switch of csc.exe), otherwise it will not run. If it uses anycpu or x64 then the application will be loaded in a 64 bit process. In order to connect to Apache OpenOffice and creating the bridge, the process must load a couple of dlls from OOo, which are 32 bit dlls. This does not work and a System.BadImageFormatException is thrown.

To check if the application is set to run as 32 bit application one uses the corflags.exe program which is part of the .NET Framework SDK. For example:

corflags myapp.exe

could produce this output (not complete):

Version   : v2.0.50727
CLR Header: 2.5
PE        : PE32
CorFlags  : 3
ILONLY    : 1
32BIT     : 0
Signed    : 0

If the PE flag has the value PE32 then this binary can also run in a 64 bit process. The 32BIT flag controls the type of process which is created for this application. On a 64bit system a value of 32BIT=0 will cause a 64 bit process. 32BIT=1 will force the use of a 32 bit process.

If the application was build with "anycpu" then it is possible to later change the 32BIT flag with

corflags /32BIT+

This will set 32BIT=1 and therefore the application will always be loaded into a 32 bit process even if run on 64 bit system.

Changes in OpenOffice.org 3.0

cli_types.dll is replaced by cli_oootypes.dll and cli_uretypes.dll and both are installed in the GAC. The cli_uretypes.dll contains all types available to the URE (defined in project udkapi) and cli_oootype.dll contains all office types (defined in project offapi).

The consequence of this is that all client programs which linked with cli_types.dll do not work anymore. They need to be rebuild and reference cli_uretypes.dll and cli_oootypes.dll instead.

The 3.0 release contains a bug which prevents the bridge from working (see issue 95255 for details). This is fixed in 3.0.1.

For debugging purposes it may be convenient to install OOo with the /a switch, which prevents writing registry entries and installing the assemblies in the GAC. To make the client program work, one has to:

  • copy all assemblies which are otherwise in the GAC next to the client executable. They can be found in the OpenOffice.org/URE/bin and OpenOffice.org/Basis 3/program folders.
  • Set UNO_PATH to the program folder of the brand layer, for example, C:\staroffice\Sun\staroffice 9\program
  • run the client program in same console
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages