Difference between revisions of "Documentation/DevGuide/ProUNO/Bridge/Mapping of Interfaces and Structures"
OOoWikiBot (Talk | contribs) m (Robot: Changing Category:Professional UNO) |
|||
(4 intermediate revisions by 3 users not shown) | |||
Line 8: | Line 8: | ||
|NextPage=Documentation/DevGuide/ProUNO/Bridge/Mapping of Sequence | |NextPage=Documentation/DevGuide/ProUNO/Bridge/Mapping of Sequence | ||
}} | }} | ||
+ | {{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Bridge/{{SUBPAGENAME}}}} | ||
{{DISPLAYTITLE:Mapping of Interfaces and Structures}} | {{DISPLAYTITLE:Mapping of Interfaces and Structures}} | ||
+ | |||
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. | 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: | 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: | ||
− | + | <syntaxhighlight lang="idl"> | |
//UNO IDL methods | //UNO IDL methods | ||
XFoo getFoo(); | XFoo getFoo(); | ||
void doSomething(XBar arg); | void doSomething(XBar arg); | ||
− | + | </syntaxhighlight> | |
− | 'VB | + | |
+ | <syntaxhighlight lang="vb"> | ||
+ | ' VB | ||
Dim objUno As Object | Dim objUno As Object | ||
Set objUno = objOtherUnoObject.getFoo() | Set objUno = objOtherUnoObject.getFoo() | ||
Line 24: | Line 28: | ||
'Therefore we can use objUno in this call: | 'Therefore we can use objUno in this call: | ||
call objOtherUnoObject.doSomething(objUno) | call objOtherUnoObject.doSomething(objUno) | ||
+ | </syntaxhighlight> | ||
If Automation objects are called from UNO, then the called methods may return other Automation objects, either as <code>IUnknown*</code> or <code>IDispatch*</code>. These can then be used as arguments in later calls to Automation objects or you can perform calls on them. In case of <code>IUnknown</code>, this is only possible if the object also supports <code>IDispatch</code>. To make calls from UNO, the <idls>com.sun.star.uno.XInterface</idls> must first be queried for <idls>com.sun.star.script.XInvocation</idls>. When a method returns <code>IDispatch</code>, then on UNO side a <idls>com.sun.star.script.XInvocation</idls> is received and can be called immediately. | If Automation objects are called from UNO, then the called methods may return other Automation objects, either as <code>IUnknown*</code> or <code>IDispatch*</code>. These can then be used as arguments in later calls to Automation objects or you can perform calls on them. In case of <code>IUnknown</code>, this is only possible if the object also supports <code>IDispatch</code>. To make calls from UNO, the <idls>com.sun.star.uno.XInterface</idls> must first be queried for <idls>com.sun.star.script.XInvocation</idls>. When a method returns <code>IDispatch</code>, then on UNO side a <idls>com.sun.star.script.XInvocation</idls> 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 <code>IUnknown</code> or <code>IDispatch</code> pointer. This is dependent upon what the parameter type is. Remember, calls can only be performed on Automation objects. Therefore <code>IUnknown</code> and <code>IDispatch</code> are the only possible COM interfaces. If the expected parameter is a <code>VARIANT</code>, then it will contain an <code>IUnknown*</code> if the Automation object was passed as <code>IUnknown*</code> into the UNO environment. It will contain an <code>IDispatch*</code> if the object was passed as <code>IDispatch*</code>. For example: | When these interfaces are passed back as arguments to a call to an Automation object, then the bridge passes the original <code>IUnknown</code> or <code>IDispatch</code> pointer. This is dependent upon what the parameter type is. Remember, calls can only be performed on Automation objects. Therefore <code>IUnknown</code> and <code>IDispatch</code> are the only possible COM interfaces. If the expected parameter is a <code>VARIANT</code>, then it will contain an <code>IUnknown*</code> if the Automation object was passed as <code>IUnknown*</code> into the UNO environment. It will contain an <code>IDispatch*</code> if the object was passed as <code>IDispatch*</code>. For example: | ||
− | + | <syntaxhighlight lang="idl"> | |
//MIDL | //MIDL | ||
HRESULT getUnknown([out,retval] IUnknown ** arg); | HRESULT getUnknown([out,retval] IUnknown ** arg); | ||
Line 36: | Line 41: | ||
HRESULT setDispatch([in] IDispatch * arg); | HRESULT setDispatch([in] IDispatch * arg); | ||
HRESULT setVariant([in] VARIANT arg); | HRESULT setVariant([in] VARIANT arg); | ||
− | + | <syntaxhighlight lang="oobas"> | |
− | 'StarBasic | + | |
+ | <syntaxhighlight lang="oobas"> | ||
+ | ' StarBasic | ||
Dim objUnknown As Object | Dim objUnknown As Object | ||
Dim objDispatch As Object | Dim objDispatch As Object | ||
Line 52: | Line 59: | ||
objAutomation.setVariant objUnknown 'VARTYPE is VT_Unknown | objAutomation.setVariant objUnknown 'VARTYPE is VT_Unknown | ||
objAutomation.setVariant objDispatch 'VARTYPE is VT_DISPATCH | objAutomation.setVariant objDispatch 'VARTYPE is VT_DISPATCH | ||
+ | </syntaxhighlight> | ||
For the purpose of receiving events (listener) it is possible to implement UNO interfaces as dispatch objects [[Documentation/DevGuide/ProUNO/Bridge/Automation Objects with UNO Interfaces|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. | For the purpose of receiving events (listener) it is possible to implement UNO interfaces as dispatch objects [[Documentation/DevGuide/ProUNO/Bridge/Automation Objects with UNO Interfaces|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 <idls>com.sun.star.uno.XInterface</idls> if the object was passed as <code>IUnknown</code> or the any contains an <idls>com.sun.star.script.XInvocation</idls> if the object was passed as <code>IDispatch</code>. If, for example, the UNO interface <code>XFoo</code> is implemented as a dispatch object, an instance to UNO as Any parameter is passed, and the Any contains XFoo rather then <idls>com.sun.star.script.XInvocation</idls>, then the dispatch object must be placed in a Value Object ([[Documentation/DevGuide/ProUNO/Bridge/Value Objects|Value Objects]]). For example: | If the Automation object is passed as argument for an any, then the any will contain an <idls>com.sun.star.uno.XInterface</idls> if the object was passed as <code>IUnknown</code> or the any contains an <idls>com.sun.star.script.XInvocation</idls> if the object was passed as <code>IDispatch</code>. If, for example, the UNO interface <code>XFoo</code> is implemented as a dispatch object, an instance to UNO as Any parameter is passed, and the Any contains XFoo rather then <idls>com.sun.star.script.XInvocation</idls>, then the dispatch object must be placed in a Value Object ([[Documentation/DevGuide/ProUNO/Bridge/Value Objects|Value Objects]]). For example: | ||
− | + | <syntaxhighlight lang="idl"> | |
//UNO method | //UNO method | ||
void foo([in] any) | void foo([in] any) | ||
− | + | </syntaxhighlight> | |
+ | |||
+ | <syntaxhighlight lang="oobas"> | ||
'objUno contains an interface with the method foo. | 'objUno contains an interface with the method foo. | ||
'It expects that the argument with of type any contains an XFoo | 'It expects that the argument with of type any contains an XFoo | ||
Line 70: | Line 80: | ||
objUno.foo objValueObject | objUno.foo objValueObject | ||
+ | </syntaxhighlight> | ||
Null pointers are converted to null pointers of the required type. That is, if an <code>IDispatch</code> 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 (<code>IDispatch</code>, or <code>IUnknown</code>) was supplied, then the UNO method receives a struct that was default constructed. | Null pointers are converted to null pointers of the required type. That is, if an <code>IDispatch</code> 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 (<code>IDispatch</code>, or <code>IUnknown</code>) was supplied, then the UNO method receives a struct that was default constructed. | ||
Line 75: | Line 86: | ||
{{PDL1}} | {{PDL1}} | ||
− | [[Category:Documentation/ | + | [[Category:Documentation/Developer's Guide/Professional UNO]] |
Latest revision as of 15:01, 23 December 2020
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:
//MIDL 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 objUno.foo 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). |