CPullPin Class

The CPullPin class is provided to allow a filter downstream from the source to create a thread and pull a media stream from an asynchronous source filter that supports the IAsyncReader interface. Typically this class is implemented on the input pin of a parser filter, since the Microsoft® DirectShow® asynchronous reader filter just reads a media stream from a file and provides no parsing.

Protected Data Members

m_pAlloc

Pointer to the IMemAllocator interface used by the connection.

Member Functions

Active	Instructs the pin to start pulling data from the asynchronous reader.
AlignDown	Aligns a LONGLONG value down to the next LONG boundary.
AlignUp	Aligns a LONGLONG value up to the next LONG boundary.
Connect	Initiates a connection from this pin to the asynchronous reader.
CPullPin	Constructs a CPullPin object.
Disconnect	Breaks a connection to the asynchronous reader.
Duration	Retrieves the total duration of the media stream.
GetReader	Retrieves the asynchronous reader interface.
Inactive	Instructs the pin to stop pulling data from the asynchronous reader.
Seek	Sets the start and stop times of the media stream.

Overridable Member Functions

BeginFlush	Flushes this pin and all downstream pins.
DecideAllocator	Proposes an allocator for use by the asynchronous reader.
EndFlush	Signals end of flushing operation.
EndOfStream	Sends end-of-stream notification downstream.
OnError	Handles run-time errors that caused pulling to stop.
Receive	Handles the arrival of data from the asynchronous reader.

CPullPin::Active

---

CPullPin Class

Instructs the pin to start pulling data from the asynchronous reader.

Syntax

HRESULT Active(void);

Return Value

Returns an HRESULT value.

Remarks

The reader interface must be retrieved and the allocator decided before calling this member function. This is handled by the CPullPin::Connect member function.

CPullPin::AlignDown

---

CPullPin Class

Aligns a LONGLONG value down to the next LONG boundary.

Syntax

LONGLONG AlignDown(
    LONGLONG ll,
    LONG lAlign
    ); 

Parameters

ll

Element to be aligned.

lAlign

Alignment boundary.

Return Value

Returns the ll value aligned to lAlign.

Remarks

Aligning downward is a truncation operation.

CPullPin::AlignUp

---

CPullPin Class

Aligns a LONGLONG value up to the next LONG boundary.

Syntax

LONGLONG AlignUp(
    LONGLONG ll,
    LONG lAlign
    );

Parameters

ll

Element to be aligned.

lAlign

Alignment boundary.

Return Value

Returns an HRESULT value.

CPullPin::BeginFlush

---

CPullPin Class

Override to flush this pin and all downstream pins.

Syntax

virtual HRESULT BeginFlush(void);

Return Value

Returns an HRESULT value.

Remarks

This member function is called by the CPullPin::Seek member function before pausing the thread prior to a seeking operation. You must implement this member function to call the IPin::BeginFlush method on the connected downstream pin.

CPullPin::Connect

---

CPullPin Class

Initiates a connection from this pin to the asynchronous reader.

Syntax

HRESULT Connect(
    IUnknown *pUnk,
    IMemAllocator *pAlloc,
    BOOL bSync
    );

Parameters

pUnk

Pointer to the object to query for existence of asynchronous reader (IAsyncReader).

pAlloc

Pointer to the optional allocator to propose as preferred allocator if necessary.

bSync

Set to TRUE if the reader uses synchronous rather than asynchronous reads.

Return Value

Returns S_OK if successfully connected to the IAsyncReader interface from the object specified by pUnk.

CPullPin::CPullPin

---

CPullPin Class

Constructs a CPullPin object.

Syntax

CPullPin(void);

Return Value

No return value.

CPullPin::DecideAllocator

---

CPullPin Class

Negotiates an allocator to use with the asynchronous reader.

Syntax

virtual HRESULT DecideAllocator(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *pProps
    );

Parameters

pAlloc

Pointer to the allocator to propose as the preferred allocator (optional). Pass NULL if you aren't proposing an allocator.

pProps

Pointer to the size, count, and alignment of the allocator (optional). Pass zero if not requesting the allocator properties.

Return Value

Returns S_OK if successful, VFW_E_BADALIGN if eProps contains an invalid alignment property, E_OUTOFMEMORY if there is not enough memory available to create an allocator, and E_NOINTERFACE if the created IMemAllocator interface is invalid.

Remarks

This member function calls the IAsyncReader::RequestAllocator method to negotiate an allocator.

CPullPin::Disconnect

---

CPullPin Class

Breaks a connection to the asynchronous reader.

Syntax

HRESULT Disconnect(void);

Return Value

Returns NOERROR if there is no connection.

Remarks

This member function disconnects any connection to an asynchronous file reader made in the CPullPin::Connect method.

CPullPin::Duration

---

CPullPin Class

Retrieves the total duration of the media stream.

Syntax

HRESULT Duration(
    REFERENCE_TIME *ptDuration
    );

Parameters

ptDuration

Pointer to the duration measured in bytes multiplied by UNIT (10,000,000).

Return Value

Returns an HRESULT value.

CPullPin::EndFlush

---

CPullPin Class

Override to signal the end of a flushing operation.

Syntax

virtual HRESULT EndFlush(void) PURE;

Return Value

Returns an HRESULT value.

Remarks

This member function is called by the CPullPin::Seek member function after pausing the thread prior to a seeking operation. You must implement this member function to call the IPin::EndFlush method on the connected downstream pin.

CPullPin::EndOfStream

---

CPullPin Class

Override to send an end-of-stream notification downstream.

Syntax

virtual HRESULT EndOfStream(void) PURE;

Return Value

Returns an HRESULT value.

Remarks

This member function is called during processing of received samples when the end of the stream is reached. You must implement this member function to call the IPin::EndOfStream method on the connected downstream pin.

CPullPin::GetReader

---

CPullPin Class

Retrieves the asynchronous reader.

Syntax

IAsyncReader* GetReader(void); 

Return Value

Returns a reference-counted IAsyncReader interface.

CPullPin::Inactive

---

CPullPin Class

Instructs the pin to stop pulling data from the asynchronous reader.

Syntax

HRESULT Inactive(void);

Return Value

Returns an HRESULT value.

Remarks

This member function calls the IAsyncReader::BeginFlush method, ends the thread, calls the IAsyncReader::EndFlush method and then decommits the allocator.

CPullPin::OnError

---

CPullPin Class

Override to handle run-time errors that caused pulling to stop.

Syntax

virtual void OnError(
    HRESULT hr
    ) PURE;

Parameters

hr

HRESULT value of the trapped error.

Return Value

No return value.

Remarks

These errors are returned from the upstream filter (the asynchronous reader), which will have already reported errors to the filter graph manager. This member function must be implemented since it is called by several CPullPin member functions when trapping errors.

CPullPin::Receive

---

CPullPin Class

Override this member function to handle the arrival of data from the asynchronous reader.

Syntax

virtual HRESULT Receive(
    IMediaSample *pSample
    ) PURE;

Parameters

pSample

[in] Pointer to a media sample.

Return Value

Returns an HRESULT value. Returning a value other than S_OK will stop the data.

Remarks

You must implement this member function in your derived class. This member function is called whenever a new sample arrives while processing the sample stream. It should be written in the same manner as the IMemInputPin::Receive method on an input pin.

CPullPin::Seek

---

CPullPin Class

Sets the start and stop times of the media stream.

Syntax

HRESULT Seek(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop
    );

Parameters

tStart

Start time (defaults to zero).

tStop

Stop time (defaults to the value of CPullPin::Duration).

Return Value

Returns an HRESULT value.

Remarks

If the filter graph is running (active), the media rendering will start immediately at the new position defined by tStart.

---

 Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.