Difference between revisions of "Documentation/DevGuide/ProUNO/C++/Mapping of Interface Types"

Latest revision as of 13:06, 23 December 2020

A value of a UNO interface type (which is a null reference or a reference to an object implementing the given interface type) is mapped to the template class:

  template< class t >
  com::sun::star::uno::Reference< t >

The template is used to get a type safe interface reference, because only a correctly typed interface pointer can be assigned to the reference. The example below assigns an instance of the desktop service to the rDesktop reference:

  // the xSMgr reference gets constructed somehow
  {
      ...
      // construct a deskop object and acquire it
      Reference< XInterface > rDesktop = xSMgr->createInstance(
      OUString::createFromAscii("com.sun.star.frame.Desktop”));
      ...
      // reference goes out of scope now, release is called on the interface
  }

The constructor of Reference calls acquire() on the interface and the destructor calls release() on the interface. These references are often called smart pointers. Always use the Reference template consistently to avoid reference counting bugs.

The Reference class makes it simple to invoke queryInterface() for a certain type:

  // construct a deskop object and acquire it
  Reference< XInterface > rDesktop = xSMgr->createInstance( 
      OUString::createFromAscii("com.sun.star.frame.Desktop"));
 
  // query it for the XFrameLoader interface
  Reference< XFrameLoader > rLoader( rDesktop , UNO_QUERY );
 
  // check, if the frameloader interface is supported
  if( rLoader.is() )
  {
      // now do something with the frame loader
      ...
  }

The UNO_QUERY is a dummy parameter that tells the constructor to query the first constructor argument for the XFrameLoader interface. If the queryInterface() returns successfully, it is assigned to the rLoader reference. You can check if querying was successful by calling is() on the new reference.

Methods on interfaces can be invoked using the operator ->:

 xSMgr->createInstance(...);

The operator ->() returns the interface pointer without acquiring it, that is, without incrementing the refcount.

If you need the direct pointer to an interface for some purpose, you can also call get() at the reference class.

You can explicitly release the interface reference by calling clear() at the reference or by assigning a default constructed reference.

You can check if two interface references belong to the same object using the operator ==.