IUnknown Struct Reference

Inheritance diagram for IUnknown:

Detailed Description

Enables clients to get pointers to other interfaces on a given object through the queryInterface method, and manage the existence of the object through the addRef and releaseRef methods. All other interfaces are inherited, directly or indirectly, from IUnknown.

IUnknown on Windows OS is compatible with Microsoft COM IUnknown interface.

Public Member Functions
virtual ErrCode INTERFACE_FUNC	queryInterface (const IntfID &intfID, void **obj)=0
	Returns another interface which is supported by the object and increments the reference count. More...
virtual int INTERFACE_FUNC	addRef ()=0
	Increments the reference count for an interface on an object. More...
virtual int INTERFACE_FUNC	releaseRef ()=0
	Decrements the reference count for an interface on an object. More...

Member Function Documentation

addRef()

virtual int INTERFACE_FUNC addRef ( )

pure virtual

Increments the reference count for an interface on an object.

Returns

Reference count after the increment.

You should call this method whenever you make a copy of an interface pointer.

An object uses a per-interface reference-counting mechanism to ensure that the object does not outlive references to it. You use addRef to stabilize a copy of an interface pointer. You can also call it when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling releaseRef on it.

queryInterface()

virtual ErrCode INTERFACE_FUNC queryInterface ( const IntfID &  intfID, void **  obj  )

pure virtual

Returns another interface which is supported by the object and increments the reference count.

Parameters

	intfID	Interface ID of requested interface.
[out]	obj	Pointer to the new interface.

Returns

OPENDAQ_SUCCESS if succeeded, error code otherwise.

Provides a fundamental mechanism by which an object can express the functionality it provides.

Every interface is derived from IUnknown, so every interface has an implementation of queryInterface. Regardless of the implementation, this method queries an object using the ID of the interface to which the caller wants a pointer. If the object supports that interface, queryInterface retrieves a pointer to the interface, while also calling addRef. Otherwise, it returns the OPENDAQ_ERR_NOINTERFACE error code.

Example:

IUnknown* obj = ...;
 
IBaseObject* baseObj;
auto errCode = obj->queryInterface(IBaseObject::Id, reinterpret_cast<void**>(&baseObj)), OPENDAQ_SUCCESS);
if (OPENDAQ_FAILED(errCode))
    throw SomeException();
// ... do something with baseObj
baseObj->releaseRef();

releaseRef()

virtual int INTERFACE_FUNC releaseRef ( )

pure virtual

Decrements the reference count for an interface on an object.

Returns

Reference count after the decrement.

Call this method when you no longer need to use an interface pointer.

When the reference count on an object reaches zero, releaseRef causes the interface pointer to free itself. When the released pointer is the only (formerly) outstanding reference to an object the implementation must free the object.