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:
Do not AddRef an interface pointer before passing it to a function.
Do not AddRef an interface pointer when receiving it as a return value from a function.
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.)
Every AddRef must be matched by a Release.
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 |
|
Increments the reference count |
|
|
Decrements the reference count |
|
|
Returns an interface pointer |
Parameters:
None
Return Values:
Returns the reference count after AddReffing.
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.
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 |
Comments:
QueryInterface performs an implicit AddRef() if successful.
§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.