Index Topic Contents | |||
Previous Topic: CPosPassThru Class Next Topic: CQueue Class |
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
Name Description m_pAlloc Pointer to the IMemAllocator interface used by the connection. Member Functions
Name Description 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
Name Description 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 Class
CPullPin::ActiveInstructs the pin to start pulling data from the asynchronous reader.
HRESULT Active(void);
Return Values
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 Class
CPullPin::AlignDownAligns a LONGLONG value down to the next LONG boundary.
LONGLONG AlignDown(
LONGLONG ll,
LONG lAlign
);Parameters
- ll
- Element to be aligned.
- lAlign
- Alignment boundary.
Return Values
Returns the ll value aligned to lAlign.
Remarks
Aligning downward is a truncation operation.
CPullPin Class
CPullPin::AlignUpAligns a LONGLONG value up to the next LONG boundary.
LONGLONG AlignUp(
LONGLONG ll,
LONG lAlign
);Parameters
- ll
- Element to be aligned.
- lAlign
- Alignment boundary.
Return Values
Returns an HRESULT value.
CPullPin Class
CPullPin::BeginFlushOverride to flush this pin and all downstream pins.
virtual HRESULT BeginFlush(void);
Return Values
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 Class
CPullPin::ConnectInitiates a connection from this pin to the asynchronous reader.
HRESULT Connect(
IUnknown* pUnk,
IMemAllocator* pAlloc,
BOOL bSync
);Parameters
- pUnk
- Object to query for existence of asynchronous reader (IAsyncReader).
- pAlloc
- Optional allocator to propose as preferred allocator if necessary.
- bSync
- Set TRUE if the reader uses synchronous rather than asynchronous reads.
Return Values
Returns S_OK if successfully connected to the IAsyncReader interface from the object specified by pUnk.
CPullPin Class
CPullPin::CPullPinConstructs a CPullPin object.
CPullPin(void);
Return Values
No return value.
CPullPin Class
CPullPin::DecideAllocatorNegotiates an allocator to use with the asynchronous reader.
virtual HRESULT DecideAllocator(
IMemAllocator* pAlloc,
ALLOCATOR_PROPERTIES * pProps
);Parameters
- pAlloc
- Allocator to propose as the preferred allocator (optional). Pass NULL if you aren't proposing an allocator.
- pProps
- Size, count, and alignment of the allocator (optional). Pass 0 if not requesting the allocator properties.
Return Values
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 Class
CPullPin::DisconnectBreaks a connection to the asynchronous reader.
HRESULT Disconnect(void);
Return Values
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 Class
CPullPin::DurationRetrieves the total duration of the media stream.
HRESULT Duration(
REFERENCE_TIME* ptDuration
);Parameters
- ptDuration
- Duration measured in bytes multiplied by UNIT (10,000,000).
Return Values
Returns an HRESULT value.
CPullPin Class
CPullPin::EndFlushOverride to signal the end of a flushing operation.
virtual HRESULT EndFlush(void) PURE;
Return Values
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 Class
CPullPin::EndOfStreamOverride to send an end-of-stream notification downstream.
virtual HRESULT EndOfStream(void) PURE;
Return Values
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 Class
CPullPin::GetReaderReturns the asynchronous reader.
IAsyncReader* GetReader(void);
Return Values
Returns a reference-counted IAsyncReader interface.
CPullPin Class
CPullPin::InactiveInstructs the pin to stop pulling data from the asynchronous reader.
HRESULT Inactive(void);
Return Values
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 Class
CPullPin::OnErrorOverride to handle run-time errors that caused pulling to stop.
virtual void OnError(
HRESULT hr
) PURE;Parameters
- hr
- HRESULT value of the trapped error.
Return Values
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 Class
CPullPin::ReceiveOverride this member function to handle the arrival of data from the asynchronous reader.
virtual HRESULT Receive(
IMediaSample * pSample
) PURE;Parameters
- pSample
- [in] Pointer to a media sample.
Return Values
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 Class
CPullPin::SeekSets the start and stop times of the media stream.
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 Values
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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.