neuray API Programmer's Manual

mi::base::IInterface Class Reference

[Interface Framework Technology]

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:

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();
        }
mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0x1acd50a4, 0xbc89, 0x4712, 0x97, 0xd, 0x79, 0xf2, 0x99, 0x8b, 0x4, 0x12 \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ...\>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0x67fd848e, 0xce43, 0x4675, 0x8b, 0x14, 0xb2, 0x54, 0xd, 0xd2, 0x29, 0x63 \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0x80cf9612, 0x3fd4, 0x4ed0, 0xb1, 0x63, 0xc0, 0xd9, 0x84, 0xe2, 0x6, 0xaa \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0x84c2d806, 0x6e1f, 0x402d, 0xb2, 0xa, 0x2f, 0xcf, 0x47, 0xd1, 0xf, 0x2e \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0x8913c078, 0xeba2, 0x4e0b, 0x83, 0x44, 0x1, 0xcb, 0x2b, 0x57, 0x67, 0x3c \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0x9a9ceafe, 0x876b, 0x4647, 0xbc, 0xae, 0xb6, 0x4, 0x9c, 0x7b, 0x9, 0xfc \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ...\>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< 0xbe270827, 0xad68, 0x4044, 0x94, 0x6e, 0x9d, 0x41, 0x4d, 0xf, 0x75, 0x65 \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations.

Public Typedefs

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 Uuid get_iid() const =0
Returns the interface ID of the most derived interface.
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 Uint32 release() const =0
Decrements the reference count. More...
virtual Uint32 retain() const =0
Increments the reference count. 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...

Typedefs

typedef Uuid_t< 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> mi::​base::​IInterface::IID

Declares the interface ID (IID) of this interface. A local type in each interface type, which is distinct and unique for each interface. The type has a default constructor and the constructed value represents the universally unique identifier (UUID) for this interface. The local type is readily convertible to a mi::base::Uuid.

Member Functions

static bool mi::​base::​IInterface::compare_iid( const Uuid& iid) [inline, static]

Compares the interface ID iid against the interface ID of this interface.

Returns

true if iid == mi::base::IInterface::IID() , and false otherwise.

virtual Uuid mi::​base::​IInterface::get_iid() const [pure virtual]

Returns the interface ID of the most derived interface.

virtual const IInterface* mi::​base::​IInterface::get_interface( const Uuid& interface_id) const [pure virtual]

Acquires a const interface from another. If this interface supports the interface with the passed interface_id, then the method returns a non-NULL const mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

Parameters

interface_id
Interface ID of the interface to acquire.

template< class T>

const T* mi::​base::​IInterface::get_interface() const [inline]

Acquires a const interface from another. If this interface supports the interface T, then the method returns a non-NULL const pointer to the interface T. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to apply static_cast to the returned pointer, since the return type already is a const pointer to the type T specified as template parameter.

virtual IInterface* mi::​base::​IInterface::get_interface( const Uuid& interface_id) [pure virtual]

Acquires a mutable interface from another. If this interface supports the interface with the passed interface_id, then the methods returns a non-NULL mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

Parameters

interface_id
Interface ID of the interface to acquire.

template< class T>

T* mi::​base::​IInterface::get_interface() [inline]

Acquires a mutable interface from another. If this interface supports the interface T, then the method returns a non-NULL pointer to the interface T. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to apply static_cast to the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

virtual Uint32 mi::​base::​IInterface::release() const [pure virtual]

Decrements the reference count. Decrements the reference count of the object referenced through this interface and returns the new reference count. If the reference count dropped to zero, the object will be deleted. The operation is thread-safe.

Returns

The new, decremented reference count.

virtual Uint32 mi::​base::​IInterface::retain() const [pure virtual]

Increments the reference count. Increments the reference count of the object referenced through this interface and returns the new reference count. The operation is thread-safe.

Returns

The new, incremented reference count.