Mapping of Interfaces and Structures

From Apache OpenOffice Wiki
Jump to: navigation, search

UNO interfaces or structures are represented as dispatch objects in the Automation environment. That is, the converted value is an object that implements IDispatch. If an UNO interface was mapped, then you also can access all other UNO interfaces of the object through IDispatch. In other words, the dispatch object represents the UNO object with all its interfaces and not only the one interface which was converted.

If a dispatch object, which actually is a UNO object or a structure, is now passed back to UNO, then the bridge will extract the original UNO interface or structure and pass it on. Since the UNO dispatch object represents the whole UNO object, that is, all its supported interfaces, you can use the dispatch object as argument for all those interface types. For example:

  //UNO IDL methods
  XFoo getFoo();
  void doSomething(XBar arg);
  ' VB
  Dim objUno As Object
  Set objUno = objOtherUnoObject.getFoo()
  'The returned interface belongs to an UNO object which implements XFoo and XBar.
  'Therefore we can use objUno in this call:
  call objOtherUnoObject.doSomething(objUno)

If Automation objects are called from UNO, then the called methods may return other Automation objects, either as IUnknown* or IDispatch*. These can then be used as arguments in later calls to Automation objects or you can perform calls on them. In case of IUnknown, this is only possible if the object also supports IDispatch. To make calls from UNO, the XInterface must first be queried for XInvocation. When a method returns IDispatch, then on UNO side a XInvocation is received and can be called immediately.

When these interfaces are passed back as arguments to a call to an Automation object, then the bridge passes the original IUnknown or IDispatch pointer. This is dependent upon what the parameter type is. Remember, calls can only be performed on Automation objects. Therefore IUnknown and IDispatch are the only possible COM interfaces. If the expected parameter is a VARIANT, then it will contain an IUnknown* if the Automation object was passed as IUnknown* into the UNO environment. It will contain an IDispatch* if the object was passed as IDispatch*. For example:

  HRESULT getUnknown([out,retval] IUnknown ** arg);
  HRESULT getDispatch([out, retval] IDispatch ** arg);
  HRESULT setUnknown([in] IUnknown * arg);
  HRESULT setDispatch([in] IDispatch * arg);
  HRESULT setVariant([in] VARIANT arg);
<syntaxhighlight lang="oobas">
<syntaxhighlight lang="oobas">  
  ' StarBasic
  Dim objUnknown As Object
  Dim objDispatch As Object
  Set objUnknown = objAutomation.getUnknown()
  Set objDispatch = objAutomation.getDispatch()
  objAutomation.setUnknown objUnknown 'Ok
  objAutomation.setDispatch objUnknown 'Ok, if objUnknow supports IDispatch, 
                                         otherwise a CannotConvertException will be thrown.
  objAutomation.setUnknown objDispatch 'OK
  objAutomation.setVariant objUnknown 'VARTYPE is VT_Unknown
  objAutomation.setVariant objDispatch 'VARTYPE is VT_DISPATCH

For the purpose of receiving events (listener) it is possible to implement UNO interfaces as dispatch objects Automation Objects with UNO Interfaces. That type of object is used as an argument in UNO functions where particular interface types are required. The bridge will make sure that the proper interface is provided to the UNO function. If the UNO interface is then passed back into the Automation environment, the original Automation object will be passed.

If the Automation object is passed as argument for an any, then the any will contain an XInterface if the object was passed as IUnknown or the any contains an XInvocation if the object was passed as IDispatch. If, for example, the UNO interface XFoo is implemented as a dispatch object, an instance to UNO as Any parameter is passed, and the Any contains XFoo rather then XInvocation, then the dispatch object must be placed in a Value Object (Value Objects). For example:

  //UNO method
  void foo([in] any)
  'objUno contains an interface with the method foo.
  'It expects that the argument with of type any contains an XFoo
  'objFoo is a dispatch object implementing XFoo.
  Dim objValueObject As Object
  Set objValueObject = objServiceManager.Bridge_GetValueObject()
  objValueObject.set "XFoo", objFoo objValueObject

Null pointers are converted to null pointers of the required type. That is, if an IDispatch pointer with the value null is passed as an argument to a UNO method then the resulting argument is a null pointer of the expected type. This also applies to UNO interface pointers, which are passed in calls to Automation objects. When a UNO method takes a struct as an argument and it is called from the Automation environment where a null pointer (IDispatch, or IUnknown) was supplied, then the UNO method receives a struct that was default constructed.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages