Getting Information about UNO Objects

OpenOffice.org Developer's Guide

Professional UNO

< Previous Section

Next Section >

• Introduction
• API Concepts

• Data Types

• Simple Types
• The Any Type
• Interfaces
• Services
• Structs
• Predefined Values
• Sequences
• Modules
• Exceptions
• Singletons

• Understanding the API Reference

• UNO Concepts

• UNO Interprocess Connections

• Starting OpenOffice.org in Listening Mode
• Importing a UNO Object
• Characteristics of the Interprocess Bridge
• Opening a Connection
• Creating the Bridge
• Closing a Connection
• Example: A Connection Aware Client

• Service Manager and Component Context

• Service Manager
• Component Context

• Using UNO Interfaces
• Properties
• Collections and Containers
• Event Model
• Exception Handling
• Lifetime of UNO objects

• acquire() and release()
• The XComponent Interface
• Children of the XEventListener Interface
• Weak Objects and References
• Differences Between the Lifetime of C++ and Java Objects

• Object Identity

• UNO Language Bindings

• Java Language Binding

• Getting a Service Manager
• Transparent Use of Office UNO Components
• Handling Interfaces
• Type Mappings

• Mapping of Sequence Types
• Mapping of Enum Types
• Mapping of Struct Types
• Mapping of Exception Types
• Mapping of Interface Types
• Mapping of UNOIDL
• Mapping of Services
• Mapping of Singletons
• Inexact approximation of UNO Value Semantics

• C++ Language Binding

• Establishing Interprocess Connections
• Transparent Use of Office UNO Components
• Type Mappings

• Mapping of Struct Types
• Mapping of Interface Types
• Mapping of Sequence Types
• Mapping of Services
• Mapping of Singletons

• Using Weak References
• Exception Handling in C++

• OpenOffice.org Basic

• Handling UNO Objects

• Instantiating UNO Services
• Getting Information about UNO Objects

• Mapping of UNO and Basic Types

• Mapping of Simple Types
• Mapping of Sequences and Arrays
• Mapping of Structs
• Mapping of Enums and Constant Groups

• Case Sensitivity
• Exception Handling
• Listeners

• Automation Bridge

• The Service Manager Component
• Using UNO from Automation

• Calling Functions and Accessing Properties
• Return Values
• Usage of Types

• Using Automation Objects from UNO
• Type Mappings

• Default Mappings

• Mapping of Simple Types
• Mapping of Hyper and Decimal
• Mapping of String
• Mapping of Interfaces and Structures
• Mapping of Sequence
• Mapping of Type

• Conversion Mappings
• Client-Side Conversions
• Value Objects
• Exceptions and Errorcodes

• Automation Objects with UNO Interfaces
• DCOM
• The Bridge Services
• Unsupported COM Features

• CLI Language Binding

• The Language Binding DLLs
• Type Mapping

• Type Name Decoration
• Type Mappings
• Additional Structures

• Lifetime Management and Obtaining Interfaces
• Writing Client Programs

• The Override Problem
• Important Interfaces and Implementations

< Previous Page

Next Page >

The Basic RTL retrieves information about UNO objects. There are functions to evaluate objects during runtime and object properties used to inspect objects during debugging.

Checking for interfaces during runtime

Although Basic does not support the queryInterface concept like C++ and Java, it can be useful to know if a certain interface is supported by a UNO Basic object or not. The function HasUnoInterfaces() detects this.

The first parameter HasUnoInterfaces() expects is the object that should be tested. Parameter(s) of one or more fully qualified interface names can be passed to the function next. The function returns True if all these interfaces are supported by the object, otherwise False.

  Sub Main
    Dim oSimpleFileAccess
    oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
  
  Dim bSuccess
      Dim IfaceName1$, IfaceName2$, IfaceName3$
      IfaceName1$ = "com.sun.star.uno.XInterface"
      IfaceName2$ = "com.sun.star.ucb.XSimpleFileAccess2"
      IfaceName3$ = "com.sun.star.container.XPropertySet"
      
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$ )
      MsgBox bSuccess ' Displays True because XInterface is supported
      
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$, IfaceName2$ )
      MsgBox bSuccess ' Displays True because XInterface
      ' and XSimpleFileAccess2 are supported
  
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName3$ )
      MsgBox bSuccess ' Displays False because XPropertySet is NOT supported
    
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$, IfaceName2$, IfaceName3$ )
      MsgBox bSuccess ' Displays False because XPropertySet is NOT supported
  End Sub

Testing if an object is a struct during runtime

As described in the section Mapping of Structs above, structs are handled differently from objects, because they are treated as values. Use the IsUnoStruct() function to check it the UNO Basic object represents an object or a struct. This function expects one parameter and returns True if this parameter is a UNO struct, otherwise False. Example:

  Sub Main
      Dim bIsStruct
          ' Instantiate a service
      Dim oSimpleFileAccess
      oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
      bIsStruct = IsUnoStruct( oSimpleFileAccess )
      MsgBox bIsStruct ' Displays False because oSimpleFileAccess is NO struct
                       ' Instantiate a Property struct
      Dim aProperty As New com.sun.star.beans.Property
      bIsStruct = IsUnoStruct( aProperty )
      MsgBox bIsStruct ' Displays True because aProperty is a struct
      bIsStruct = IsUnoStruct( 42 )
      MsgBox bIsStruct ' Displays False because 42 is NO struct
  End Sub

Testing objects for identity during runtime

To find out if two UNO Apache OpenOffice Basic objects refer to the same UNO object instance, use the function EqualUnoObjects(). Basic is not able to apply the comparison operator = to arguments of type object, for example, If Obj1 = Obj2 Then will produce a runtime error.

  Sub Main
      Dim bIdentical
      Dim oSimpleFileAccess, oSimpleFileAccess2, oSimpleFileAccess3
          ' Instantiate a service
      oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
      oSimpleFileAccess2 = oSimpleFileAccess ' Copy the object reference
      bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess2 )
      MsgBox bIdentical ' Displays True because the objects are identical
          ' Instantiate the service a second time
      oSimpleFileAccess3 = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
      bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess3 )
      MsgBox bIdentical ' Displays False, oSimpleFileAccess3 is another instance
  
      bIdentical = EqualUnoObjects( oSimpleFileAccess, 42 )
      MsgBox bIdentical ' Displays False, 42 is not even an object
          ' Instantiate a Property struct
      Dim aProperty As New com.sun.star.beans.Property
      Dim aProperty2
      aProperty2 = aProperty ' Copy the struct
      bIdentical = EqualUnoObjects( aProperty, aProperty2 )
      MsgBox bIdentical ' Displays False because structs are values
          ' and so aProperty2 is a copy of aProperty
  End Sub

Basic hides interfaces behind Apache OpenOffice Basic objects that could lead to problems when developers are using API structures. It can be difficult to understand the API reference and find the correct method of accessing an object to reach a certain goal.

To assist during development and debugging, every UNO object in Apache OpenOffice Basic has special properties that provide information about the object structure. These properties are all prefixed with Dbg_ to emphasize their use for development and debugging purposes. The type of these properties is String. To display the properties use the MsgBox function.

Inspecting interfaces during debugging

The Dbg_SupportedInterfaces lists all interfaces supported by the object. In the following example, the object returned by the function GetProcessServiceManager() described in the previous section is taken as an example object.

  oServiceManager = GetProcessServiceManager()
  MsgBox oServiceManager.Dbg_SupportedInterfaces

This call displays a message box:

Dbg_SupportedInterfaces Property

The list contains all interfaces supported by the object. For interfaces that are derived from other interfaces, the super interfaces are indented as shown above for com.sun.star.container.XSet, which is derived from com.sun.star.container.XEnumerationAccess based upon com.sun.star.container.XElementAccess.

If the text "(ERROR: Not really supported!)" is printed behind an interface name, the implementation of the object usually has a bug, because the object pretends to support this interface (per com.sun.star.lang.XTypeProvider, but a query for it fails. For details, see UNO Reflection API).

Inspecting properties during debugging

The Dbg_Properties lists all properties supported by the object through com.sun.star.beans.XPropertySet and through get and set methods that could be mapped to Basic object properties:

  oServiceManager = GetProcessServiceManager()
  MsgBox oServiceManager.Dbg_Properties

This code produces a message box like the following example:

Dbg_Properties

Inspecting Methods During Debugging

The Dbg_Methods lists all methods supported by an object. Example:

  oServiceManager = GetProcessServiceManager()
  MsgBox oServiceManager.Dbg_Methods

This code displays:

Dbg_Methods

The notations used in Dbg_Properties and Dbg_Methods refer to internal implementation type names in Basic. The Sbx prefix can be ignored. The remaining names correspond with the normal Basic type notation. The SbxEMPTY is the same type as Variant. Additional information about Basic types is available in the next chapter.

Basic uses the com.sun.star.lang.XTypeProvider interface to detect which interfaces an object supports. Therefore, it is important to support this interface when implementing a component that should be accessible from Basic. For details, see Writing UNO Components.

Inspector tools

Using these Dbg_ properties is a very crude method to discover the contents of an API objects. Use instead Xray tool or MRI tool.

The list of elements may be inconveniently long for MsgBox display. Code is available to write all Dbg_ elements to a new Writer document. See Apache OpenOffice Macros > Tools > Debug > WritedbgInfo. The Tools library must be loaded to use this routine:

GlobalScope.BasicLibraries.LoadLibrary( "Tools" )
Call Tools.WritedbgInfo(MyObject)

Content on this page is licensed under the Public Documentation License (PDL).