IFXUnknown

This is the virtual base class from which all IFXCom-Lite objects are derived. It provides for the basic functions of (1) determining how many clients are using an object, (2) destroying the object when nobody is using it anymore, and (3) providing a means to query the object and determine whether it supports specific additional functionality.

IFXCom objects (which implement the IFXUnknown interface) must be created using the IFXCreateComponent global function, documented below.

Each client using an IFXCom object must AddRef the object to indicate that they are using it, and then call Release when they are done with it. Every AddRef must have a corresponding Release. When the last client releases the object, the object will destroy itself. The only exceptions to AddReffing an object are directly following a call to QueryInterface or IFXCreateComponent; both of these perform an implicit AddRef internally, before returning an interface pointer.

Some rules for addreffing and releasing:

  1. Do not AddRef an interface pointer before passing it to a function.

  2. Do not AddRef an interface pointer when receiving it as a return value from a function.

  3. Do AddRef an interface pointer when assigning it to another pointer. This includes assignment to member variables, as well as when passing a pointer back out as a return value from a function call (as in the case of QueryInterface.)

  4. Every AddRef must be matched by a Release.

  5. It is good practice to set a pointer to NULL after releasing it, to prevent accidental use of a Released pointer

An example:

function foo(IFXUnknown * pUnk, IFXInterfaceB ** ppInterfaceB)

{

FXInterfaceA * pInterfaceA;

FXInterfaceB * pInterfaceB;

pUnk->QueryInterface(CID_INTERFACE_A, IID_INTERFACE_A, &pInterfaceA);

IFXCreateComponent(CID_IFXInterfaceB, IID_IFXInterfaceB, &pInterfaceB);

*ppInterfaceB = pInterfaceB;

pInterfaceB->AddRef(); // because we just copied the pointer

pInterfaceB->DoSomethingWith(pInterfaceA);

pInterfaceB->Release(); // matches IFXCreateComponent

pInterfaceB = NULL; // good practice following a Release

pInterfaceA->Release(); // matches QueryInterface

pInterfaceA = NULL; // good practice following a Release

}

Method Interface

Description

AddRef

Increments the reference count

Release

Decrements the reference count

QueryInterface

Returns an interface pointer


IFXUnknown::AddRef()

Parameters:

None

Return Values:

Returns the reference count after AddReffing.


IFXUnknown::Release()

Parameters:

None

Return Values:

Returns the reference count after releasing.

Comments:

When a call to this method results in a reference count of zero, the component will delete itself, and any pointers to it will no longer be valid.


IFXUnknown::QueryInterface(IFXREFIID interfaceId, void ** ppInterface);

Parameters:

interfaceId

The IFXREFIID (IID) that identifies the desired interface

ppInterface

Handle to the interface, which upon success will be initialized to point to the interface

Return Values

Comments:

QueryInterface performs an implicit AddRef() if successful.

 

§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.