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.

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

Top of Page