Difference between revisions of "Documentation/DevGuide/ProUNO/CLI/CLI Language Binding"

Revision as of 10:49, 20 June 2008

About the Language Binding

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 OpenOffice.org 2.0 and is only available for Windows platforms, such as Windows XP and Windows 2000. 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.

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.

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.

cli_cppuhelper now uses the UREINSTALLLOCATION value of the keys HKEY_CURRENT_USER\Software\OpenOffice.org\Layer\URE\1 HKEY_LOCAL_MACHINE\Software\OpenOffice.org\Layer\URE\1 to find a URE in order to find the necessary libraries for establishing the connection to OOo.

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.

• Open a console and extend PATH to contain the bin folder of the URE
• Set UNO_PATH to the program folder of the brand layer, for example, C:\staroffice\Sun\staroffice 9\program
• run the client program from within this console