mi::base::IInterface Class Reference

The basic extensible interface. More...

#include <iinterface.h>

Inheritance diagram for mi::base::IInterface:

Public Types
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Public Member Functions
virtual Uint32	retain () const =0
	Increments the reference count. More...
virtual Uint32	release () const =0
	Decrements the reference count. More...
virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...
template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...
virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...
template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...
virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Static Public Member Functions
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID iid against the interface ID of this interface. More...

Detailed Description

The basic extensible interface.

The mi::base::IInterface class is a pure virtual class with no members, a so-called interface. It is used as the common base class of interface hierarchies. The purpose of this class is the management of object lifetime through reference counting, see mi::base::IInterface::retain() and mi::base::IInterface::release(), and the proper dynamic-cast like access to derived and otherwise related interfaces, see mi::base::IInterface::get_interface(const Uuid&).

In addition to these methods, the class mi::base::IInterface has an inner type mi::base::IInterface::IID, which is readily convertible to the type mi::base::Uuid. The type mi::base::IInterface::IID has a default constructor which creates a value that contains the universally unique identifier (UUID a.k.a. GUID) of this interface. Each interface has such a local type mi::base::IInterface::IID with a distinct and unique value. The value can be passed to the mi::base::IInterface::get_interface(const Uuid&) methods, introduced below, and this is the mode in which it is normally used.

See also

• mi::base::Handle for a smart-pointer class automating the reference counting
• mi::base::Interface_declare for a helper class for deriving new interfaces
• mi::base::Interface_implement for a helper class for implementing interfaces

Include File:

#include <mi/base/iinterface.h>

Example:

Assume you have an interface pointer iptr for an allocator object with the corresponding interface mi::base::IAllocator. You cannot directly cast the pointer to the corresponding interface pointer. Instead you need to use the mi::base::IInterface::get_interface(const Uuid&) method with the corresponding interface ID (IID) value of type mi::base::Uuid, cast the result and release the interface after you are done using it. You can obtain the necessary IID value by instantiating the IID type that is locally embedded in each interface.

If you are not sure whether iptr refers to an object supporting an mi::base::IAllocator interface you must check that the result of the mi::base::IInterface::get_interface(const Uuid&) method call is not NULL.

mi::base::IInterface* iptr = ...;
mi::base::IAllocator* allocator = static_cast<mi::base::IAllocator*>(
                                      iptr->get_interface( mi::base::IAllocator::IID()));
// check that the iptr object supports the mi::base::IAllocator interface
if ( allocator) {
    ... // use allocator
    allocator->release();
}

Alternatively, you can use the more convenient and type-safe template version that eliminates the need for the subsequent static_cast.

mi::base::IInterface* iptr = ...;
mi::base::IAllocator* allocator = iptr->get_interface<mi::base::IAllocator>();
// check that the iptr object supports the mi::base::IAllocator interface
if ( allocator) {
    ... // use allocator
    allocator->release();
}