View source for Documentation/DevGuide/ProUNO/Bridge/Using Automation Objects from UNO

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2c=block
|ABridgeSvcMgr=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Bridge/Usage of Types
|NextPage=Documentation/DevGuide/ProUNO/Bridge/Type Mappings
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Bridge/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Using Automation Objects from UNO}}
__NOTOC__
This language binding offers a way of accessing Automation objects from UNO. For an Automation object to be usable, it must be properly registered on the system and have a programmatic identifier (ProgId) with which an instance can be created. From UNO, all Automation objects are accessed via <idl>com.sun.star.script.XInvocation</idl>. <idls>com.sun.star.script.XInvocation</idls> is a scripting interface that is intended for dynamically performing calls similar to <code>IDispatch</code>. Since StarBasic uses <idls>com.sun.star.script.XInvocation</idls> to communicate with objects, Automation objects can be used from StarBasic.

=== Instantiation ===

To obtain an instance of an Automation object it is easiest to use the service <idl>com.sun.star.bridge.oleautomation.Factory</idl>. It provides an <idls>com.sun.star.lang.XMultiServiceFactory</idls> interface which is used to get the desired object. For example:
<syntaxhighlight lang="cpp">
  //C++
  
  Reference<XInterface> xInt = serviceManager->createInstance(
  OUString::createFromAscii("com.sun.star.bridge.oleautomation.Factory"));
  
  Reference<XMultiServiceFactory> automationFactory(xInt, UNO_QUERY);
  
  if(automationFactory.is())
  {
      Reference<XInterface> xIntApp = automationFactory->createInstance(
        OUString::createFromAscii("Word.Application"));
  
      Reference< XInvocation > xInvApp( xIntApp, UNO_QUERY);
      // call methods on the Automation object.
      ...
  }
</syntaxhighlight>

In StarBasic it looks quite simple:
<syntaxhighlight lang="oobas">
  'StarBasic
  
  Dim automationFactory As Object
  automationFactory = createUnoService("com.sun.star.bridge.oleautomation.Factory")
  
  Dim objApp As Object
  objApp = automationFactory.createInstance("Word.Application")
  'call methods on the Automation object
</source>
StarBasic function CreateObject offers a simpler code:
<source lang="oobas">
  Dim objApp As Object
  objApp = CreateObject("Word.Application")
  'call methods on the Automation object
</syntaxhighlight>

==== Accessing Automation Objects ====

All Automation objects are accessed through <idl>com.sun.star.script.XInvocation</idl> interface. The function <idlm>com.sun.star.script.XInvocation:getIntrospection</idlm> is not implemented. To call a method, <idlm>com.sun.star.script.XInvocation:invoke</idlm> is used. <idlm>com.sun.star.script.XInvocation:invoke</idlm> is also used to access properties with additional arguments. The methods <idlm>com.sun.star.script.XInvocation:setValue</idlm> and <idlm>com.sun.star.script.XInvocation:getValue</idlm> set or retrieve a property value. These methods can only be used with properties that do not have additional arguments.

<idlm>com.sun.star.script.XInvocation:hasMethod</idlm> returns true for a name that represents a method or a property with arguments. And last, <idlm>com.sun.star.script.XInvocation:hasProperty</idlm> returns true for a name that represents a property with no arguments. Refer to the IDL documentation for more information about <idls>com.sun.star.script.XInvocation</idls>.

==== Properties with Arguments ====

Unlike UNO properties, Automation properties can have arguments. Therefore, <idlm>com.sun.star.script.XInvocation:setValue</idlm> and <idlm>com.sun.star.script.XInvocation:getValue</idlm> method are not suitable for those properties. Instead <idlm>com.sun.star.script.XInvocation:invoke</idlm> is used. If a property takes arguments, then <idlm>com.sun.star.script.XInvocation:hasProperty</idlm> returns false and <idlm>com.sun.star.script.XInvocation:hasMethod</idlm> returns true. <idlm>com.sun.star.script.XInvocation:invoke</idlm> must also be used if the arguments of the property are optional and not provided in the call.

The bridge must recognize a write operation on a property. To achieve this, the caller has to provide the actual property value (not additional arguments) in a structure of type <idl>com.sun.star.bridge.oleautomation.PropertyPutArgument</idl>. Similar to <code>IDispatch::Invoke</code>, the property value must be the last in the argument list. For example:
<syntaxhighlight lang="idl">
  // MIDL 
  [propget,...] HRESULT Item([in] VARIANT val1, [out, retval] VARIANT* pVal);
  [propput,...] HRESULT Item([in] VARIANT val1, [in] VARIANT newVal);
</syntaxhighlight>

<syntaxhighlight lang="cpp">
  // C++
  Sequence< sal_Int16> seqIndices;
  Sequence<Any> seqOut;
  //Prepare arguments
  Any arArgs[2];
  arArgs[0] <<= makeAny((sal_Int32) 0);
  arArgs[1] <<= PropertyPutArgument(makeAny((sal_Int32) 0));
  Sequence<Any> seqArgs(arArgs, 2);
  
  //obj is a XInvocation of an Automation object
  obj->invoke(OUString::createFromAscii("Item"), seqArgs, seqIndices, seqOut);
  
  //now get the property value
  Any arGet[1];
  arGet[0] <<= makeAny((sal_Int32) 0);
  Sequence<Any> seqGet(arGet, 1);
  Any retVal = obj->invoke(OUString::createFromAscii("Item"), seqGet, seqIndices, seqOut);
</syntaxhighlight>
In StarBasic, <idls>com.sun.star.bridge.oleautomation.PropertyPutArgument</idls> is implicitly used:
<syntaxhighlight lang="oobas">
  'StarBasic
  
  obj.Item(0) = 0
  
  Dim propval As Variant
  propval = obj.Item(0)
</syntaxhighlight>
The property value that is obtained in a property get operation is the return value of <idlm>com.sun.star.script.XInvocation:invoke</idlm>.

==== Optional Parameters, Default Values, Variable Argument Lists ====

The bridge supports all these special parameters. Optional parameters can be left out of the argument list of <idlm>com.sun.star.script.XInvocation:invoke</idlm>. However, if a value is omitted, then all following arguments from the parameter list must also be omitted. This only applies for positional arguments and not for named arguments.

If the Automation object specifies a default value for an optional parameter, then the bridge supplies it, if no argument was provided by the caller.

If a method takes a variable argument list, then one can provide the respective UNO arguments as ordinary arguments to <idlm>com.sun.star.script.XInvocation:invoke</idlm>. <code>IDispatch::Invoke</code> would require those arguments in a <code>SAFEARRAY</code>.

==== Named Arguments ====

To provide named arguments in an <idlm>com.sun.star.script.XInvocation:invoke</idlm> call, one has to use instances of <idl>com.sun.star.bridge.oleautomation.NamedArgument</idl> for each argument. This is the struct in UNOIDL:
<syntaxhighlight lang="idl">
  module com { module sun { module star { module bridge { module oleautomation {
  struct NamedArgument
  {
      /** The name of the argument, for which
      <member>NamedArgument::Value</member> is intended.
      */
      string Name;
  
      /** The value of the argument whose name is the one as contained in the
      member <member>Name</member>.
      */
      any Value;
  }; 
  
  }; }; }; }; }; 
</syntaxhighlight>

In a call both, named arguments and positional arguments can be used together. The order is, first the positional arguments (the ordinary arguments), followed by named arguments. When named arguments are used, then arguments can be omitted even if arguments are provided that follow the omitted parameter. For example, assume that a method takes five arguments, which are all optional, then the argument lists for <idls>com.sun.star.script.XInvocation</idls> could be as follows:

* all provided: {A, B, C, D, E}
* arguments omitted: {A,B,C,D} or {A,B} but not {A, C, D}
* named arguments : {nA, nC, nB, nD}, {nC, nD}
* mixed arguments: { A, B, nD}, {A, nC}

Named arguments can also be used with properties that have additional arguments. However, the property value itself cannot be a named argument, since it is already regarded as a named argument. Therefore, it is always the last argument.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]