Difference between revisions of "Documentation/DevGuide/ProUNO/Bridge/Usage of Types"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (FINAL VERSION FOR L10N)
m
 
Line 22: Line 22:
  
 
Automation does not know about structs as they exist in other languages, for example, in C++. Instead, it uses Automation objects that contain a set of properties similar to the fields of a C++ struct. Setting or reading a member ultimately requires a call to <code>IDispatch::Invoke</code>. However in languages, such as VB, VBScript, and JScript, the interface call is obscured by the programming language. Accessing the properties is as easy as with C++ structs.
 
Automation does not know about structs as they exist in other languages, for example, in C++. Instead, it uses Automation objects that contain a set of properties similar to the fields of a C++ struct. Setting or reading a member ultimately requires a call to <code>IDispatch::Invoke</code>. However in languages, such as VB, VBScript, and JScript, the interface call is obscured by the programming language. Accessing the properties is as easy as with C++ structs.
 
+
<source lang="vb">
   // VB. obj is an object that implements a UNO struct
+
   ' VB. obj is an object that implements a UNO struct
 
   obj.Width= 100
 
   obj.Width= 100
 
   obj.Height= 100
 
   obj.Height= 100
 +
</source>
  
 
Whenever a UNO function requires a struct as an argument, the struct must be obtained from the UNO environment. It is not possible to declare a struct. For example, assume there is an office function <code>setSize()</code> that takes a struct of type Size. The struct is declared as follows:
 
Whenever a UNO function requires a struct as an argument, the struct must be obtained from the UNO environment. It is not possible to declare a struct. For example, assume there is an office function <code>setSize()</code> that takes a struct of type Size. The struct is declared as follows:
 
+
<source lang="idl">
 
   // UNO IDL
 
   // UNO IDL
 
   struct Size
 
   struct Size
Line 38: Line 39:
 
   // the interface function, that will be called from script
 
   // the interface function, that will be called from script
 
   void XShape::setSize( Size aSize)
 
   void XShape::setSize( Size aSize)
 +
</source>
  
 
You cannot write code similar to the following example (VBScript):
 
You cannot write code similar to the following example (VBScript):
 
+
<source lang="vb">
 
   Class Size
 
   Class Size
 
       Dim Width
 
       Dim Width
Line 50: Line 52:
 
   'now set the size
 
   'now set the size
 
   call objXShape.setSize( new Size) // wrong
 
   call objXShape.setSize( new Size) // wrong
 +
</source>
  
 
The <idl>com.sun.star.reflection.CoreReflection</idl> service or the <code>Bridge_GetStruct</code> function that is called on the service manager object can be used to create the struct. The following example uses the <code>CoreReflection</code> service
 
The <idl>com.sun.star.reflection.CoreReflection</idl> service or the <code>Bridge_GetStruct</code> function that is called on the service manager object can be used to create the struct. The following example uses the <code>CoreReflection</code> service
 
+
<source lang="vb">
 
   'VBScript in Windows Scripting Host
 
   'VBScript in Windows Scripting Host
 
   Set objServiceManager= Wscript.CreateObject("com.sun.star.ServiceManager")
 
   Set objServiceManager= Wscript.CreateObject("com.sun.star.ServiceManager")
Line 69: Line 72:
 
   'pass the struct into the function
 
   'pass the struct into the function
 
   objXShape.setSize aSize
 
   objXShape.setSize aSize
 +
</source>
  
 
The next example shows how <code>Bridge_GetStruct</code> is used.  
 
The next example shows how <code>Bridge_GetStruct</code> is used.  
 
+
<source lang="vb">
 
   Set objServiceManager= Wscript.CreateObject("com.sun.star.ServiceManager")
 
   Set objServiceManager= Wscript.CreateObject("com.sun.star.ServiceManager")
 
   Set aSize= objServiceManager.Bridge_GetStruct("com.sun.star.awt.Size")
 
   Set aSize= objServiceManager.Bridge_GetStruct("com.sun.star.awt.Size")
Line 79: Line 83:
 
    
 
    
 
   objXShape.setSize aSize
 
   objXShape.setSize aSize
 +
</source>
  
 
The <code>Bridge_GetStruct</code> function is provided by the service manager object that is initially created by <code>CreateObject</code> (Visual Basic) or <code>CoCreateInstance[Ex] (VC++).c</code>
 
The <code>Bridge_GetStruct</code> function is provided by the service manager object that is initially created by <code>CreateObject</code> (Visual Basic) or <code>CoCreateInstance[Ex] (VC++).c</code>
  
 
The corresponding C++ examples look complicated, but ultimately the same steps are necessary. The method <code>forName()</code> on the <code>CoreReflection</code> service is called and returns a <idl>com.sun.star.reflection.XIdlClass</idl> which can be asked to create an instance using <code>createObject()</code>:
 
The corresponding C++ examples look complicated, but ultimately the same steps are necessary. The method <code>forName()</code> on the <code>CoreReflection</code> service is called and returns a <idl>com.sun.star.reflection.XIdlClass</idl> which can be asked to create an instance using <code>createObject()</code>:
 
+
<source lang="cpp">
 
   // create the service manager of OpenOffice
 
   // create the service manager of OpenOffice
 
   IDispatch* pdispFactory= NULL;  
 
   IDispatch* pdispFactory= NULL;  
Line 138: Line 143:
 
   pdispCoreReflection->Release();
 
   pdispCoreReflection->Release();
 
   pdispFactory->Release();
 
   pdispFactory->Release();
 
+
</source>
 
The <code>Bridge_GetStruct</code> example.
 
The <code>Bridge_GetStruct</code> example.
 
+
<source lang="cpp">
 
   // objectServiceManager is the service manager of the office
 
   // objectServiceManager is the service manager of the office
 
   OLECHAR* strstructFunc= L"Bridge_GetStruct";
 
   OLECHAR* strstructFunc= L"Bridge_GetStruct";
Line 158: Line 163:
 
   // do something with the struct pdispPropertyValue
 
   // do something with the struct pdispPropertyValue
 
   ...
 
   ...
 +
</source>
  
 
JScript:
 
JScript:
 
+
<source lang="javascript">
 
   // struct creation via CoreReflection
 
   // struct creation via CoreReflection
 
   var objServiceManager= new ActiveXObject("com.sun.star.ServiceManager");
 
   var objServiceManager= new ActiveXObject("com.sun.star.ServiceManager");
Line 178: Line 184:
 
   size.Width=111;
 
   size.Width=111;
 
   size.Height=112;
 
   size.Height=112;
 
+
</source>
  
 
{{PDL1}}
 
{{PDL1}}
  
 
[[Category:Documentation/Developer's Guide/Professional UNO]]
 
[[Category:Documentation/Developer's Guide/Professional UNO]]

Latest revision as of 12:31, 22 October 2009



Interfaces

Many UNO interface functions take interfaces as arguments. If this is the case, there are three possibilities to get an instance that supports the needed interface:

  • Ask the service manager to create a service that implements that interface.
  • Call a function on a UNO object that returns that particular interface.
  • Provide an interface implementation if a listener object is required. Refer to Automation Objects with UNO Interfaces for additional information.

If createInstance() is called on the service manager or another UNO function that returns an interface, the returned object is wrapped, so that it appears to be a COM dispatch object. When it is passed into a call to a UNO function then the original UNO object is extracted from the wrapper and the bridge makes sure that the proper interface is passed to the function. If UNO objects are used, UNO interfaces do not have to be dealt with. Ensure that the object obtained from a call to a UNO object implements the proper interface before it is passed back into another UNO call.

Structs

Automation does not know about structs as they exist in other languages, for example, in C++. Instead, it uses Automation objects that contain a set of properties similar to the fields of a C++ struct. Setting or reading a member ultimately requires a call to IDispatch::Invoke. However in languages, such as VB, VBScript, and JScript, the interface call is obscured by the programming language. Accessing the properties is as easy as with C++ structs.

  ' VB. obj is an object that implements a UNO struct
  obj.Width= 100
  obj.Height= 100

Whenever a UNO function requires a struct as an argument, the struct must be obtained from the UNO environment. It is not possible to declare a struct. For example, assume there is an office function setSize() that takes a struct of type Size. The struct is declared as follows:

  // UNO IDL
  struct Size
  {
      long Width;
      long Height;
  }
 
  // the interface function, that will be called from script
  void XShape::setSize( Size aSize)

You cannot write code similar to the following example (VBScript):

  Class Size
      Dim Width
      Dim Height
  End Class
 
  'obtain object that implements Xshape
  
  'now set the size
  call objXShape.setSize( new Size) // wrong

The com.sun.star.reflection.CoreReflection service or the Bridge_GetStruct function that is called on the service manager object can be used to create the struct. The following example uses the CoreReflection service

  'VBScript in Windows Scripting Host
  Set objServiceManager= Wscript.CreateObject("com.sun.star.ServiceManager")
 
  'Create the CoreReflection service that is later used to create structs
  Set objCoreReflection= objServiceManager.createInstance("com.sun.star.reflection.CoreReflection")
  'get a type description class for Size
  Set classSize= objCoreReflection.forName("com.sun.star.awt.Size")
  'create the actual object
  Dim aSize
  classSize.createObject aSize
  'use aSize
  aSize.Width= 100
  aSize.Height= 12
 
  'pass the struct into the function
  objXShape.setSize aSize

The next example shows how Bridge_GetStruct is used.

  Set objServiceManager= Wscript.CreateObject("com.sun.star.ServiceManager")
  Set aSize= objServiceManager.Bridge_GetStruct("com.sun.star.awt.Size")
  'use aSize
  aSize.Width= 100
  aSize.Height= 12
 
  objXShape.setSize aSize

The Bridge_GetStruct function is provided by the service manager object that is initially created by CreateObject (Visual Basic) or CoCreateInstance[Ex] (VC++).c

The corresponding C++ examples look complicated, but ultimately the same steps are necessary. The method forName() on the CoreReflection service is called and returns a com.sun.star.reflection.XIdlClass which can be asked to create an instance using createObject():

  // create the service manager of OpenOffice
  IDispatch* pdispFactory= NULL; 
  CLSID clsFactory= {0x82154420,0x0FBF,0x11d4,{0x83, 0x13,0x00,0x50,0x04,0x52,0x6A,0xB4}}; 
  hr= CoCreateInstance( clsFactory, NULL, CLSCTX_ALL, __uuidof(IDispatch), (void**)&pdispFactory); 
 
  // create the CoreReflection service 
  OLECHAR* funcName= L"createInstance"; 
  DISPID id; 
  pdispFactory->GetIDsOfNames( IID_NULL, &funcName, 1, LOCALE_USER_DEFAULT, &id); 
 
  VARIANT param1; 
  VariantInit( &param1); 
  param1.vt= VT_BSTR; 
  param1.bstrVal= SysAllocString( L"com.sun.star.reflection.CoreReflection"); 
  DISPPARAMS dispparams= { &param1, 0, 1, 0}; 
  VARIANT result; 
  VariantInit( &result); 
  hr= pdispFactory->Invoke( id, IID_NULL, LOCALE_USER_DEFAULT, DISPATCH_METHOD, 
  &dispparams, &result, NULL, 0); 
  IDispatch* pdispCoreReflection= result.pdispVal; 
  pdispCoreReflection->AddRef(); 
  VariantClear( &result); 
 
  // create the struct's idl class object 
  OLECHAR* strforName= L"forName"; 
  hr= pdispCoreReflection->GetIDsOfNames( IID_NULL, &strforName, 1, LOCALE_USER_DEFAULT, &id); 
  VariantClear( &param1); 
  param1.vt= VT_BSTR; 
  param1.bstrVal= SysAllocString(L"com.sun.star.beans.PropertyValue"); 
  hr= pdispCoreReflection->Invoke( id, IID_NULL, LOCALE_USER_DEFAULT, 
  DISPATCH_METHOD, &dispparams, &result, NULL, 0); 
 
  IDispatch* pdispClass= result.pdispVal;
  pdispClass->AddRef();
  VariantClear( &result);
 
  // create the struct
  OLECHAR* strcreateObject= L"createObject";
  hr= pdispClass->GetIDsOfNames( IID_NULL,&strcreateObject, 1, LOCALE_USER_DEFAULT, &id)
 
  IDispatch* pdispPropertyValue= NULL;
  VariantClear( &param1);
  param1.vt= VT_DISPATCH | VT_BYREF;
  param1.ppdispVal= &pdispPropertyValue;
  hr= pdispClass->Invoke( id, IID_NULL, LOCALE_USER_DEFAULT, 
  DISPATCH_METHOD, &dispparams, NULL, NULL, 0);
 
  // do something with the struct pdispPropertyValue contained in dispparams
  // ...
 
  pdispPropertyValue->Release();
  pdispClass->Release();
  pdispCoreReflection->Release();
  pdispFactory->Release();

The Bridge_GetStruct example.

  // objectServiceManager is the service manager of the office
  OLECHAR* strstructFunc= L"Bridge_GetStruct";
  hr= objServiceManager->GetIDsOfNames( IID_NULL, &strstructFunc, 1, LOCALE_USER_DEFAULT, &id);
 
  VariantClear(&result);
  VariantClear( &param1);
  param1.vt= VT_BSTR;
  param1.bstrVal= SysAllocString(
  L"com.sun.star.beans.PropertyValue");
  hr= objServiceManager->Invoke( id, IID_NULL,LOCALE_USER_DEFAULT, DISPATCH_METHOD, 
  &dispparams, &result, NULL, 0);
 
  IDispatch* pdispPropertyValue= result.pdispVal;
  pdispPropertyValue->AddRef();
 
  // do something with the struct pdispPropertyValue
  ...

JScript:

  // struct creation via CoreReflection
  var objServiceManager= new ActiveXObject("com.sun.star.ServiceManager");
  var objCoreReflection= objServiceManager.createInstance("com.sun.star.reflection.CoreReflection");
 
  var classSize= objCoreReflection.forName("com.sun.star.awt.Size");
  var outParam= new Array();
  classSize.createObject( outParam);
  var size= outParam[0];
  //use the struct
  size.Width=111;
  size.Height=112;
  // ----------------------------------------------------
  // struct creation by bridge function
  var objServiceManager= new ActiveXObject("com.sun.star.ServiceManager");
  var size= objServiceManager.Bridge_GetStruct("com.sun.star.awt.Size");
  size.Width=111;
  size.Height=112;
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages