Grabber::removeListener Method

This method unregisters a callback handler object for the specified events.

Syntax:

bool removeListener( GrabberListener* pListener, DWORD callback = -1 );

Parameter		Description


pListener		Specifies a pointer to a GrabberListener derived callback handler object that is to be unregistered.
callback		Specifies the events that may not be handled by the specified callback handler anymore. To combine two or more listener types, use a binary OR operation. It defaults to -1. -1 is the combination of all possible GrabberListener::tListenerTypes.

Return value:

true, if the callback handler that was specified in pListener could be unregistered successfully. This is only possible, if no callbacks for the specified events are currently being processed. If callbacks are being processed, the grabber stores the remove request for the handler and returns false. As soon as all pending callbacks are finished, the stored remove request is processed.

Remarks:

If an application tries to unregister a callback handler for all events for which it was registered, it may only destroy the callback handler, if removeListener returns true. If false is returned, the application has to wait until the remove request is carried out by calling Grabber::isListenerRegistered in a loop. It is important to do a Sleep(0) in the loop, otherwise the loop would put too much load on the processor and the pending callbacks may not get CPU time. This would cause a deadlock. As soon as Grabber::isListenerRegistered returns true, the callback handler may be destroyed.

Sample:

This example shows how to register a callback handler that is derived from GrabberListener for a set of events. It shows also how to unregister the object for the event for which it was registered. Finally, it shows how to delete the callback handler object in a safe way.

Grabber *grabber      = new DShowLib::Grabber();
CListener *pcListener = new CListener();    // Create the GrabberListener object.
// CListener is derived from
// GrabberListener.

// Register the pcListener object to the Grabber's GrabberListener objects list.
grabber->addListener( pcListener, DShowLib::GrabberListener::eFRAMEREADY|
DShowLib::GrabberListener::eOVERLAYCALLBACK );

grabber->startLive( true );            // Start the grabber
// Events are handled now

fflush(stdin);
printf("Press [enter] to stop!");
getchar();

// The GrabberListener object must be unregistered for the events
// for which is was registered, before it can be deleted.
// First, unregister it for the frame ready event.
grabber->removeListener(pcListener, DShowLib::GrabberListener::eFRAMEREADY);
// Second, unregister it for the overlay callback event.
grabber->removeListener(pcListener, DShowLib::GrabberListener::eOVERLAYCALLBACK);

// Wait until all remove requests have been processed
while( grabber->isListenerRegistered( pcListener, eALL) )
{
Sleep( 0 ); // Wait
}

// Now, the application can be sure that the CListener methods
// are no longer called by the Grabber. It is now safe to delete the
// CListener object.
delete pcListener;

grabber->stopLive();            // Stop the grabber
delete grabber;

<< Grabber