Microsoft DirectX 8.0

CSourceStream Class

CSourceStream class hierarchy

Output pin for the CSource filter class.

Declaration: Source.h

For information on using this class, see CSource. This class inherits the CAMThread class, which provides a worker thread for streaming data from the pin. The CSourceStream class implements the following helper methods to send requests to the thread:

The first request to the thread must be Init. The Exit request terminates the thread. In practice, it is not necessary to call any of these methods directly, because the pin's Active and Inactive methods call them as needed.

The class also provides several "handler" methods:

These do nothing in the base class, but the derived class can override them.

Protected Member Variables
m_pFilterPointer to the filter that contains this pin.
Protected Methods
OnThreadCreateCalled when the streaming thread is initialized. Virtual.
OnThreadDestroyCalled when the streaming thread is about to exit. Virtual.
OnThreadStartPlayCalled at the start of the DoBufferProcessingLoop method. Virtual.
ActiveNotifies the pin that the filter is now active.
InactiveNotifies the pin that the filter is no longer active.
GetRequestWaits for the next thread request.
CheckRequestChecks if there is a thread request, without blocking.
ThreadProcThread procedure. Virtual.
DoBufferProcessingLoopGenerates media data and delivers it to the downstream input pin. Virtual.
CheckMediaTypeDetermines if the pin accepts a specific media type. Virtual.
GetMediaTypeRetrieves a preferred media type. Virtual.
Public Methods
CSourceStreamConstructor method.
~CSourceStreamDestructor method. Virtual.
InitInitializes the streaming thread.
ExitSignals the streaming thread to exit.
RunSignals the streaming thread to run.
PauseSignals the streaming thread to become active.
StopSignals the streaming thread to stop.
Pure Virtual Methods
FillBufferFills a media sample with data.
IPin Methods
QueryId Retrieves an identifier for the pin.

CSourceStream.m_pFilter

CSourceStream Class

Pointer to the filter that contains this pin.

Syntax

CSource *m_pFilter;

CSourceStream::Active

CSourceStream Class

Notifies the pin that the filter is now active. Overrides the CBasePin::Active method. If the pin is connected, this method starts the streaming thread.

Syntax

HRESULT Active(void);

Return Value

Returns an HRESULT value. Possible values include those listed in the following table.

S_FALSEPin is already active.
S_OKSuccess.
E_FAIL Could not start the thread.

CSourceStream::CheckMediaType

CSourceStream Class

Determines if the pin accepts a specific media type. Implements the pure virtual CBasePin::CheckMediaType method.

Syntax

virtual HRESULT CheckMediaType(
    CMediaType *pMediaType
);

Parameters

pMediaType
Pointer to a CMediaType object that contains the proposed media type.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKThis pin supports this media type.
E_FAILThe pin does not support this media type.

Remarks

By default, the pin supports a single media type. This method retrieves the supported type by calling the single-parameter version of the GetMediaType method, and compares it to the proposed type. If your pin supports more than one media type, override this method.

CSourceStream::CheckRequest

CSourceStream Class

Checks if there is a thread request, without blocking.

Syntax

BOOL CheckRequest(
    Command *pCom
);

Parameters

pCom
Pointer to a variable that receives the value passed in the last call to the CAMThread::CallWorker method.

Return Value

Returns TRUE if there is a pending request, or FALSE otherwise.

Remarks

This method overrides the CAMThread::CheckRequest method to perform type-checking. The CSourceStream class defines the following enumerated type for the pCom parameter:

enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};

CSourceStream::CSourceStream

CSourceStream Class

Constructor method.

Syntax

CSourceStream(
    TCHAR *pObjectName,
    HRESULT *phr,
    CSource *pms,
    LPCWSTR pName
);

Parameters

pObjectName
Pointer to a string containing the debug name of the pin.
phr
Pointer to a variable that receives an HRESULT value indicating the success or failure of the method. Initialize the value to S_OK before creating the object. The value is changed only if an error occurs.
pms
Pointer to the CSource filter that created this pin.
pName
Pointer to a string that contains the name of the pin.

Remarks

The string given in the pObjectName parameter is used strictly for debugging purposes. For more information, see CBaseObject.

The string given in the pName parameter is the name returned by the IPin::QueryPinInfo method. This name is not used for the pin identifier that the QueryId method returns. Instead, QueryId calculates a pin identifier based on the pin number. (Pin identifiers support graph persistence. For more information, see IPin::QueryId.)

CSourceStream::~CSourceStream

CSourceStream Class

Destructor method.

Syntax

~CSourceStream(void);

CSourceStream::DoBufferProcessingLoop

CSourceStream Class

Generates media data and delivers it to the downstream input pin.

Syntax

virtual HRESULT DoBufferProcessingLoop(void);

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSEThread received a stop request.
S_OKStream ended, or downstream filter is not accepting samples.

Remarks

This method implements the main loop that processes data and delivers it downstream. Each time through the loop, the method retrieves an empty media sample from the allocator. It passes the sample to the FillBuffer method. The FillBuffer method—which the derived class must implement—then generates media data and moves it into the sample buffer.

The loop ends when any of the following occurs:

The DoBufferProcessingLoop method handles the end-of-stream notification. If an error occurs, it sends an EC_ERRORABORT event to the filter graph manager.

CSourceStream::Exit

CSourceStream Class

Signals the streaming thread to exit.

Syntax

HRESULT Exit(void);

Return Value

Returns S_OK or E_UNEXPECTED.

Remarks

The Inactive method calls this method.

CSourceStream::FillBuffer

CSourceStream Class

Fills a media sample with data.

Syntax

virtual HRESULT FillBuffer(
    IMediaSample *pSample
) PURE;

Parameters

pSample
Pointer to the sample's IMediaSample interface.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSEEnd of stream
S_OKSuccess

Remarks

The derived class must implement this method.

The media sample given to this method has no time stamps. The derived class should call the IMediaSample::SetTime method to set the time stamps. If appropriate for the media type, the derived class should also set the media times, by calling the IMediaSample::SetMediaTime method. For more information, see Time and Clocks in DirectShow.

CSourceStream::GetMediaType

CSourceStream Class

Retrieves a preferred media type.

Syntax

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

virtual HRESULT GetMediaType(
    CMediaType *pMediaType
);

Parameters

iPosition
Zero-based index value.
pMediaType
Pointer to a CMediaType object that receives the media type.

Return Value

Returns one of the HRESULT values shown in the following table.
S_OKSuccess.
VFW_S_NO_MORE_ITEMSIndex out of range.
E_INVALIDARGIndex less than zero.
E_UNEXPECTEDUnexpected error.

Remarks

There are two versions of this method. One version overrides the CBasePin::GetMediaType method and takes an index value as a parameter. The other version is designed to retrieve a single media type, so it lacks the index parameter.

The single-parameter method returns E_UNEXPECTED. The two-parameter method checks that the iPosition parameter is 1, and then calls the single-parameter version. Depending on the number of media types the pin supports, you must override one of these methods:

CSourceStream::GetRequest

CSourceStream Class

Waits for the next thread request.

Syntax

Command GetRequest(void);

Return Value

Returns the next thread request.

Remarks

This method overrides the CAMThread::GetRequest method. The return value is cast to the following enumerated type:

enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};

CSourceStream::Inactive

CSourceStream Class

Notifies the pin that the filter is no longer active. Overrides the CBasePin::Inactive method. If the streaming thread is active, this method stops it and waits for the thread to exit.

Syntax

HRESULT Inactive(void);

Return Value

Returns S_OK or another HRESULT value.

CSourceStream::Init

CSourceStream Class

Initializes the streaming thread.

Syntax

HRESULT Init(void);

Return Value

Returns S_OK, or another HRESULT value.

Remarks

This method must be the first thread request sent to the ThreadProc method. The Active method calls this method.

CSourceStream::OnThreadCreate

CSourceStream Class

Called when the streaming thread is initialized.

Syntax

virtual HRESULT OnThreadCreate(void);

Return Value

Returns S_OK.

Remarks

The thread procedure, ThreadProc, calls this method when it first receives an Init request. The method does nothing in the base class. The derived class can override this method to perform thread initializations. If the derived class returns an error code, the thread exits with an error.

CSourceStream::OnThreadDestroy

CSourceStream Class

Called when the streaming thread is about to exit.

Syntax

virtual HRESULT OnThreadDestroy(void);

Return Value

Returns S_OK.

Remarks

The thread procedure, ThreadProc, calls this method before it exits. The method does nothing in the base class; it is available for the derived class to override. If the derived class returns an error code, the thread exits with an error.

CSourceStream::OnThreadStartPlay

CSourceStream Class

Called at the start of the DoBufferProcessingLoop method.

Syntax

virtual HRESULT OnThreadStartPlay(void);

Return Value

Returns S_OK.

Remarks

This method does nothing in the base class; it is available for the derived class to override.

CSourceStream::Pause

CSourceStream Class

Signals the streaming thread to become active.

Syntax

HRESULT Pause(void);

Return Value

Returns S_OK or E_UNEXPECTED.

Remarks

The Active method calls this method. When the ThreadProc method receives this request, it calls the DoBufferProcessingLoop method.

CSourceStream::QueryId

CSourceStream Class

Retrieves an identifier for the pin.

Syntax

HRESULT QueryId(
    LPWSTR *Id
);

Parameters

Id
Pointer to a variable that receives a string containing the pin identifier.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.
VFW_E_NOT_FOUNDPin was not found on the filter.

Remarks

This method implements the IPin::QueryId method. To construct an identifier string, the pin calls the CSource::FindPinNumber method with itself as the parameter. The FindPinNumber method returns the pin number, indexed from zero. QueryId increments the return value by one and converts the result to a string. For example, the first pin becomes "1"; the second pin becomes "2"; and so forth.

If this method returns VFW_E_NOT_FOUND, it indicates that the filter's array of pins is invalid, presumably caused by a bug in the filter.

CSourceStream::Run

CSourceStream Class

Signals the streaming thread to run.

Syntax

HRESULT Run(void);

Return Value

Returns S_OK or E_UNEXPECTED.

Remarks

In the base class, this method has the same effect as the Pause request, and is not used.

CSourceStream::Stop

CSourceStream Class

Signals the streaming thread to stop.

Syntax

HRESULT Stop(void);

Return Value

Returns S_OK or E_UNEXPECTED.

Remarks

The Inactive method calls this method.

CSourceStream::ThreadProc

CSourceStream Class

Thread procedure. Implements the pure virtual CAMThread::ThreadProc method.

Syntax

virtual DWORD ThreadProc(void);

Return Value

Returns 0 if the thread completed successfully or 1 otherwise. If the return value is 1, the thread's resources might still be allocated.

Remarks

This method waits indefinitely for thread requests, by calling the CAMThread::GetRequest method. If it receives a Run or Pause request, it calls the DoBufferProcessingLoop method. The DoBufferProcessingLoop method pushes data until it receives a Stop request. The thread procedure exits when it receives an Exit request.