## 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::Active

CPullPin Class

Instructs 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::AlignDown

CPullPin Class

Aligns 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::AlignUp

CPullPin Class

Aligns 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::BeginFlush

CPullPin Class

Override 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::Connect

CPullPin Class

Initiates 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::CPullPin

CPullPin Class

Constructs a CPullPin object.

CPullPin(void);

##### Return Values

No return value.

###

CPullPin::DecideAllocator

CPullPin Class

Negotiates 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::Disconnect

CPullPin Class

Breaks 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::Duration

CPullPin Class

Retrieves 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::EndFlush

CPullPin Class

Override 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::EndOfStream

CPullPin Class

Override 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::GetReader

CPullPin Class

Returns the asynchronous reader.

IAsyncReader* GetReader(void);

##### Return Values

Returns a reference-counted IAsyncReader interface.

###

CPullPin::Inactive

CPullPin Class

Instructs 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::OnError

CPullPin Class

Override 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::Receive

CPullPin Class

Override 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::Seek

CPullPin Class

Sets 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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.