Difference between revisions of "Documentation/DevGuide/ProUNO/Bridge/Value Objects"

Revision as of 12:24, 30 March 2011

The Automation Value Object

The object can be obtained from any uno object by calling the Bridge_GetValueObject on it. It holds a value and a type description, hence it resembles a UNO any or a VARIANT. A Value Object can stand in for all kinds of arguments in a call to a UNO method from a automation language. A Value Object is used when the bridge needs additional information for the parameter conversion. This is the case when a UNO method takes an any as argument. In many cases, however, one can do without a Value Object if one provides an argument which maps exactly to the expected UNO type according to the default mapping. For example, a UNO method takes an any as argument which is expected to contain a short. Then it would be sufficient to provide a Long in Visual Basic. But in JScript there are no types and implicitly a four byte integer would be passed to the call. Then the any would not contain a short and the call may fail. In that case the Value Object would guarantee the proper conversion.

A Value Object also enables in/out and out parameter in languages which only know in-parameters in functions. JScript is a particular case because one can use Array objects as well as Value Objects for those parameters.

A Value Object exposes four functions that can be accessed through IDispatch. These are:

  void Set( [in]VARIANT type, [in]VARIANT value);

Assigns a type and a value.

  void Get( [out,retval] VARIANT* val);

Returns the value contained in the object. Get is used when the Value Object was used as inout or out parameter.

  void InitOutParam();

Tells the object that it is used as out parameter.

  void InitInOutParam( [in]VARIANT type, [in]VARIANT value);

Tells the object that it is used as inout parameter and passes the value for the in parameter, as well as the type.

When the Value Object is used as in or inout parameter then specify the type of the value. The names of types correspond to the names used in UNO IDL, except for the “object” name. The following table shows what types can be specified.

To show that the value is a sequence, put brackets before the names, for example:

  []char - sequence<char>
  [][]char - sequence < sequence <char > > 
  [][][]char - sequence < sequence < sequence < char > > >

The Value Objects are provided by the bridge and can be obtained from the service manager object. The service manager is a registered COM component with the ProgId “com.sun.star.ServiceManager” (The Service Manager Component). For example:

  // JScript
  var valueObject= objSericeManager.Bridge_GetValueObject();

To use a Value Object as in parameter, specify the type and pass the value to the object:

  // UNO IDL
  void doSomething( [in] sequence< short > ar);

  // JScript
  var value= objServiceManager.Bridge_GetValueObject();
  var array= new Array(1,2,3);
  value.Set("[]short",array);
  object.doSomething( value);

In the previous example, the Value Object was defined to be a sequence of short values. The array could also contain Value Objects again:

  var value1= objServiceManager.Bridge_GetValueObject();
  var value2= objServiceManager.Bridge_GetValueObject();
  value1.Set("short", 100);
  value2.Set("short", 111);
  var array= new Array();
  array[0]= value1;
  array[1]= value2;
  var allValue= objServiceManager.Bridge_GetValueObject();
  allValue.Set("[]short", array);
  object.doSomething( allValue);

If a function takes an out parameter, tell the Value Object like this:

  // UNO IDL
  void doSomething( [out] long);

  // JScript
  var value= objServiceManager.Bridge_GetValueObject();
  value.InitOutParam();
  object.doSomething( value);
  var out= value.Get();

When the Value Object is an inout parameter, it needs to know the type and value as well:

  //UNO IDL
  void doSomething( [inout] long);

  //JScript
  var value= objServiceManager.Bridge_GetValueObject();
  value.InitInOutParam("long", 123);
  object.doSomething(value);
  var out= value.Get();

UNO Value Object (as of OOo 3.4)

The UNO Value Object is basically the same as the Automation Value Object. It can be provided as argument in calls on automation objects. The value object is an uno service and implements com.sun.star.bridge.oleautomation.XValueObject. The type description is provided by flags which resemble the VARTYPE as used by VARIANTs. All possible type flags are provided as properties by the XValueObject interface.

'OOo Basic
'function expects a VARIANT of VT_I1 (signed char)
Dim value As Object
value = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
value.set(value.VT_I1, 100)
automation_object.func(value)
 
'function expects a VARIANT of SAFEARRAY of VT_I2
Dim valueI2 As Object
Dim arI2(1) As Long
arI2(0) = 1000
arI2(1) = 1000
valueI2 = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
valueI2.set(valueI2.VT_I2 Or valueI2.VT_ARRAY, arI2)
automation_object.func(valueI2)

If a Value Object is provided as out or in/out parameter then the type will be changed after the function has returned. Therefore the argument type must be of Variant. For example:

Dim valueLong As Variant
valueLong = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
valueLong.set(valueLong.VT_INT, 1000)
automation_object.outLong(valueLong)