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

Revision as of 14:50, 22 October 2009

A Value Object is an Automation object which can be obtained from the bridge. It can hold 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();