ISampleGrabber::SetCallback

  • Article
 
Microsoft DirectShow 9.0

ISampleGrabber::SetCallback

The SetCallback method specifies a callback method to call on incoming samples.

Syntax

  HRESULT SetCallback(
  ISampleGrabberCB *pCallback,
  long WhichMethodToCallback
);

Parameters

pCallback

Pointer to an ISampleGrabberCB interface containing the callback method, or NULL to cancel the callback.

WhichMethodToCallback

Index specifying the callback method. Must be one of the following values.

Value Description
0 The Sample Grabber filter calls the ISampleGrabberCB::SampleCB method, passing it a pointer to the original media sample.
1 The Sample Grabber filter calls the ISampleGrabberCB::BufferCB method, passing it a pointer to a copy of the data in the media sample.

Return Value

Returns one of the following values.

Return code Description
E_INVALIDARG Samples are not being buffered.
S_OK Success.

Remarks

If the sample is a Microsoft® DirectDraw® surface, the surface is locked during the callback. The Win16 lock (also called Win16Mutex) might be locked as well. Both of these locks create the potential for deadlock. If the callback thread waits for a thread that is trying to call a DirectDraw API, it can cause deadlock. In addition, if the Win16 lock is being held, deadlock can result if the callback holds a critical section or waits for another thread to complete any activity.

Therefore, the callback should not perform any actions with the potential to block, such as holding a critical section or waiting on another thread. Also, do not call any GDI or USER32.DLL APIs that might cause a window to move. For more information about the Win16 lock, see Knowledge Base article Q125867, Understanding Win16Mutex.

The data processing thread blocks until the callback method returns. If the callback does not return quickly, it can interfere with playback.

The filter does not invoke the callback function for preroll samples, or for samples in which the dwStreamId member of the AM_SAMPLE2_PROPERTIES structure is anything other than AM_STREAM_MEDIA.

Requirements

Header: Include Qedit.h. This header file is not compatible with Microsoft® Direct3D® headers later than version 7.

Library: Use strmiids.lib.

See Also