All COM objects implement the IUnknown interface. IUnknown defines three standard methods, of which two are a concern of this article: AddRef() and Release(). When a COM object is created, its "reference count" (the number of objects holding claim to the newly created object) is set to 1. A program never directly deletes these objects; instead, a program calls Release(), which de-increments the reference count. If the reference count reaches 0, the object self-destructs.
The benefit of this is an object will remain in memory only as long as it needs to; the lifetime of an object is managed by its reference count. A programmer cannot accidentally delete an object from memory that another module or portion of the application may be using. Only when the object's reference count goes to 0 (as a result of all involved parties calling Release() on their interface pointers) does the object automatically destroy itself.
This is, sadly, a double-edged sword; by mismanaging reference counts, you can easily get yourself in trouble, and leak memory in a very real way.
Take the following function as an example:
HRESULT StartGraph( IGraphBuilder * pIGraphBuilder )
{
IMediaControl * pIMediaControl;
hr = pIGraphBuilder->QueryInterface( IID_IMediaControl, ( void ** ) &pIMediaControl );
if( FAILED( hr ) )
return hr;
return pIMediaControl->Run(); // THIS WILL LEAK A REFERENCE COUNT
}
This is how we would normally start a filter graph in DirectShow. This code technically works, but it has a serious flaw. Because it queries the filter graph manager for the IMediaControl interface, this increments the reference count on pIGraphBuilder. However, when we return, because IMediaControl was declared locally, it goes out of scope without ever being released, thus leaving behind an extra reference count on pIGraphBuilder. The above code is leaking a reference count, which means abandoned COM objects galore!
One way to (sort of) fix the above code would be:
HRESULT StartGraph( IGraphBuilder * pIGraphBuilder )
{
IMediaControl * pIMediaControl;
HRESULT hr = pIGraphBuilder->QueryInterface( IID_IMediaControl, ( void ** ) &pIMediaControl );
if( FAILED( hr ) )
return hr;
hr = pIMediaControl->Run();
if( FAILED( hr ) )
return hr; // THIS WILL LEAK A REFERENCE COUNT!
// Release our interface....
SAFE_RELEASE( pIMediaControl );
return hr;
}
There are still major flaws with this code. We successfully release the interface before exiting the function at the end; this will automatically de-increment the reference count on the filter graph manager. However, what if the call to IMediaControl->Run() fails? Again, we leak a reference count because we fail to release pIMediaControl! We successfully queried for the interface, which adds a reference to our Filter Graph Manager, but by exiting before we've called SAFE_RELEASE() we've again leaked a reference count. We could easily add another SAFE_RELEASE() call to the middle return, but consider this: what if this method was 100 lines long? 200 lines long? What if it had elaborate loops or other conditional logic? It becomes easy to miss a release, and the code is visually convoluted by clean-up logic.
The solution to this problem is to use Smart Pointers to manage reference counting. When a COM pointer wrapped with a Smart Pointer goes out of scope, it automatically calls Release(), thus alleviating the pain of manually releasing:
#include; // For Smart Pointers!
...
HRESULT StartGraph( IGraphBuilder * pIGraphBuilder )
{
CComPtrpIMediaControl;
HRESULT hr = pIGraphBuilder->QueryInterface( IID_IMediaControl, ( void ** ) &pIMediaControl );
if( FAILED( hr ) )
return hr;
return pIMediaControl->Run();
}
Notice that we don't have to release the pointer at the end of the method; upon going out of scope, the Smart Pointer will automatically call Release().
Alternately, you can also use CComQIPtr (QI = Query Interface) for slightly cleaner code; the above could be written like so:
HRESULT StartGraph( IGraphBuilder * pIGraphBuilder )
{
CComQIPtrpIMediaControl( pIGraphBuilder );
if( !pIMediaControl )
return E_FAIL;
return pIMediaControl->Run();
}
Either method will work; the second is slightly cleaner but I prefer the former for more accurate HRESULTs.
There are still instances where you'll need to manually release a smart pointer--take the following GetPin() function for example:
//---------------------------------------------------------------//
// GetPin - returns a pin of the specified direction on the
// specified filter. Note that this will return connected or
// unconnected pins.
HRESULT GetPin( IBaseFilter * pFilter, PIN_DIRECTION PinDir, IPin ** ppPin )
{
if( ppPin == NULL || pFilter == NULL )
{
return E_POINTER;
}
CComPtrpEnum;
HRESULT hr = pFilter->EnumPins( &pEnum );
if( FAILED( hr ) )
{
return hr;
}
CComPtrpPin;
hr = pEnum->Next( 1, &pPin, 0 );
while( hr == S_OK )
{
PIN_DIRECTION ThisPinDirection;
hr = pPin->QueryDirection( &ThisPinDirection );
if( FAILED( hr ) )
{
return hr;
}
if( PinDir == ThisPinDirection )
{
// Found a match. Return the IPin pointer to the caller.
return pPin.CopyTo( ppPin );
}
// Release the pin for the next time through the loop.
pPin.Release();
hr = pEnum->Next( 1, &pPin, 0 );
}
// No more pins. We did not find a match.
if( hr == VFW_E_ENUM_OUT_OF_SYNC )
{
return VFW_E_ENUM_OUT_OF_SYNC;
}
else
{
return E_FAIL;
}
}
The above function is the same function defined in the DirectShow documentation, with several errors corrected. And, of course, no more sloppy raw COM pointers.
Note the IPin object pPin--because we're enumerating the filter for a pin, we have to manually call pPin.Release() before reusing the object. Also of note is the pPin.CopyTo() call, which is another convenient feature of smart pointers. CopyTo() should be used in the event of copying a smart pointer to a dumb pointer. However, in the above function, since the passed in pPin is either going to be a dereferenced smart pointer (which is, again, a dumb pointer) or a regular dumb pointer, the CopyTo() is appropriate.
One other feature of Smart Pointers is the overloaded assignment operator. Observe:
CComPtrpSomeFilter;
//Somewhere else
HRESULT CreateFauxFilter()
{
CComPtrpSomeOtherFilter;
HRESULT hr = pSomeOtherFilter.CoCreateInstance( CLSID_OfSomeOtherFilter );
if( FAILED( hr ) )
{
return hr;
}
else
{
// Here, we can use the "=" operator to copy one smart pointer
// to another smart pointer.
pSomeFilter = pSomeOtherFilter;
return hr;
}
}
So, pSomeFilter is assigned to pSomeOtherFilter, and when pSomeOtherFilter goes out of scope, it'll clean up any remaining reference counting issues. It's a handy way to only keep around a pointer if we know everything has occurred successfully. A common use of this is to instantiate all of your filter graphs with locally declared smart pointers, and only assign the smart pointers to your member variables at the end of the function.
You may think these are equivalent to the CopyTo() method of a CComPtr, but the assignment operator should only be used when explicitly copying one smart pointer to another. The CopyTo() should be used when copying a smart pointer to a dumb pointer.
Also, be mindful of accidentally mixing smart pointers, dumb pointers, and the assignment operator:
IBaseFilter * pDumbPointer;
CComPtrpSmartPointer;
pSmartPointer = pDumbPointer; // THIS IS OKAY (sort of)
pDumbPointer = pSmartPointer; // THIS IS VERY, VERY BAD!!
The really nasty thing about the latter assignment is that pDumbPointer will not equal NULL (thus evading many common checks for validity) and subsequent attempt to call any methods on the dumb pointer will result in Very Bad Things™. If you're mixing smart pointers with dumb pointers, consider removing the dumb pointers entirely, as the use of dumb pointers is generally a sign of a greater problem and using both is generally confusing and/or odd.
