CBaseStreamControl.CheckStreamState method

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The CheckStreamState method determines whether a media sample should be delivered or discarded.

Syntax

enum CheckStreamState(
   IMediaSample *pSample
);

Parameters

pSample

Pointer to the sample's IMediaSample interface.

Return value

Returns one of the following values.

Return code	Description
STREAM_DISCARDING	Discard this sample.
STREAM_FLOWING	Deliver this sample.

Remarks

Call this method when your pin receives a sample. Deliver the sample only if the return value is STREAM_FLOWING. If the return value is STREAM_DISCARDING, discard the sample.

If the pin discards any samples, it should mark the next sample that it delivers as a discontinuity, by calling the IMediaSample::SetDiscontinuity method.

If your filter implements the IAMDroppedFrames interface to count how many frames it drops, do not count a discarded frame as a dropped frame.

When the return value is STREAM_DISCARDING, the method blocks until the reference time reaches the sample's start time. This prevents your pin from discarding samples too quickly. If the filter is paused, the wait time is infinite, until the filter runs, stops, or flushes data. (Filter state changes and streaming happen on separate threads, so this does not cause any deadlock.)

The CBaseStreamControl::StreamControlState enumeration is defined as follows:

enum StreamControlState{ 
    STREAM_FLOWING = 0x1000,
    STREAM_DISCARDING
};

Examples

The following example assumes that the pin uses a member variable named m_fLastSampleDiscarded to keep track of discontinuities.

CMyPin::Receive(IMediaSample *pSample)
{
    if (!pSample) return E_POINTER;

    int iStreamState = CheckStreamState(pSample);
    if (iStreamState == STREAM_FLOWING) 
    {
        if (m_fLastSampleDiscarded)
            pSample->SetDiscontinuity(TRUE);
        m_fLastSampleDiscarded = FALSE;
        /* Deliver the sample. */
    } 
    else 
    {
        m_fLastSampleDiscarded = TRUE;  
       // Discard this sample. Do not deliver it.
    }
}

Requirements

Requirement	Value
Header	Strmctl.h (include Streams.h)
Library	Strmbase.lib (retail builds); Strmbasd.lib (debug builds)

See also

CBaseStreamControl Class