CSource Class

CSource class hierarchy

The CSource class and its corresponding class, CSourceStream, simplify the construction of source filters that produce continuous streams of data comparable to the way the CTransformFilter class assists in the creation of transform filters.

The CSource class provides a wrapper for the CBaseFilter class that performs the pin management and works with the CSourceStream class to provide the pins.

To use the CSource class to build a filter:

Derive your filter-level class from the CSource class. Provide a CreateInstance member function in it to create a new object of the class.
Provide a means of adding objects that are derived from the CSourceStream class to support the output pins during construction of the class. You can either create them yourself during construction or provide the developer with a means of creating them later.

For an example of using the CSource class, see the Ball sample in the Samples\Multimedia\DShow\Src\Ball subdirectory of the DirectX Media Software Development Kit (SDK).

This class does not help build an asynchronous file reader source filter, which requires support of an IAsyncReader interface and a downstream parser filter that supports the CPullPin class.

Protected Data Members

m_cStateLock Locks this data member to serialize access to the filter state.
m_iPins Number of pins on this filter; updated by the CSource::AddPin and CSource::RemovePin member functions.
m_paStreams Array of streams associated with this filter.

Member Functions

AddPin Adds a pin to the source filter.
CSource Constructs a CSource object.
FindPinNumber Retrieves the number of the pin through the IPin parameter.
GetPin Retrieves a pointer to a specified pin.
GetPinCount Retrieves the number of pins contained by the filter.
pStateLock Retrieves a pointer to the filter-critical section.
RemovePin Removes a pin from the source filter.

Implemented IBaseFilter Methods

FindPin Retrieves a pointer to the pin with the specified identifier.

CSource::AddPin

CSource Class

Adds a pin to the source filter.

Syntax

HRESULT AddPin(
    CSourceStream *pStream
    );

Parameters

pStream
Pointer to the CSourceStream object associated with the pin.

Return Value

Returns S_OK if successful, or E_OUTOFMEMORY if no memory is available.

CSource::CSource

CSource Class

Initializes the CSource object.

Syntax

CSource(
    TCHAR *pName,
    LPUNKNOWN lpunk,
    CLSID clsid
    );

Parameters

pName
Pointer to the debugging name of this object.
lpunk
Pointer to the controlling IUnknown interface passed to the derived class's CreateInstance function.
clsid
Class identifier of the filters.

Return Value

No return value.

Remarks

The derived class could create the pins here, unless it provides a means for the developer to do this.

CSource::FindPinNumber

CSource Class

Retrieves the number of the pin supporting a given IPin interface.

Syntax

int FindPinNumber(
    IPin *iPin
    );

Parameters

iPin
Pointer to the IPin interface of the pin to retrieve.

Return Value

Returns the pin number or –1 if no matching pin number is found.

CSource::GetPin

CSource Class

Retrieves a pointer to the specified pin.

Syntax

CBasePin *GetPin(
    int n
    );

Parameters

n
Pin number of the requested pin.

Return Value

Returns the pointer to the pin or NULL if the index is out of range.

Remarks

This member function is specified in CBaseFilter and is implemented here. Note that this pin interface will not have been reference counted when obtained.

CSource::GetPinCount

CSource Class

Retrieves the number of pins contained by the filter.

Syntax

int GetPinCount(void);

Return Value

Returns the pin count.

Remarks

This member function is specified in CBaseFilter and is implemented here.

CSource::pStateLock

CSource Class

Retrieves a pointer to the filter-critical section.

Syntax

CCritSec* pStateLock(void);

Return Value

Returns the critical section.

Remarks

Locking consists of holding the filter-critical section by calling the pStateLock member function and using the returned object to serialize access to functions. Typically, this lock can be held by a function when the worker thread might want to hold it. Therefore, to access a shared state from the worker thread, add another critical-section object. The exception occurs during the processing loop of the thread when it is safe to retrieve the filter-critical section from within CSourceStream::FillBuffer.

CSource::RemovePin

CSource Class

Removes a pin from the source filter.

Syntax

HRESULT RemovePin(
    CSourceStream *pStream
    );

Parameters

pStream
Pointer to the CSourceStream object associated with the pin.

Return Value

Returns S_OK if successful or S_FALSE if unsuccessful.

Remarks

The pStream parameter is not deleted. This member function adjusts pin locations in the m_paStreams array.

m_cStateLock	Locks this data member to serialize access to the filter state.
m_iPins	Number of pins on this filter; updated by the CSource::AddPin and CSource::RemovePin member functions.
m_paStreams	Array of streams associated with this filter.

AddPin	Adds a pin to the source filter.
CSource	Constructs a CSource object.
FindPinNumber	Retrieves the number of the pin through the IPin parameter.
GetPin	Retrieves a pointer to a specified pin.
GetPinCount	Retrieves the number of pins contained by the filter.
pStateLock	Retrieves a pointer to the filter-critical section.
RemovePin	Removes a pin from the source filter.