IAsyncReader Interface

The IAsyncReader interface allows multiple overlapped reads from different positions in the media stream. This interface is supported by source filters.

Note that during connection an output pin supporting the IAsyncReader should check whether its QueryInterface method is called asking for the IAsyncReader interface. If it is not, then the output pin should fail the connect unless it establishes some other transport to use during the connection.

When to Implement

Implement this interface on a pin if your filter reads data of media type MEDIATYPE_Stream from some source.

When to Use

A parser, such as an Apple® QuickTime® parser filter, can use this interface to read from a filter that reads from a file, the network, or memory.

Methods in Vtable Order

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IAsyncReader methods	Description
RequestAllocator	Retrieves the actual allocator to be used.
Request	Queues a request for data.
WaitForNext	Blocks until the next sample is completed or the time-out occurs.
SyncReadAligned	Performs an aligned synchronized read.
SyncRead	Performs a synchronized read.
Length	Retrieves the total length of the stream, and the currently available length.
BeginFlush	Causes all outstanding reads to return.
EndFlush	Ends the flushing operation.

---

IAsyncReader::BeginFlush

IAsyncReader Interface

Starts the flushing operation.

HRESULT BeginFlush(void);

Return Values

Returns S_OK if successful, S_FALSE otherwise.

Remarks

Causes all outstanding reads to return, possibly with a failure code (VFW_E_TIMEOUT), indicating that the outstanding reads were canceled. Between IAsyncReader::BeginFlush and IAsyncReader::EndFlush calls, IAsyncReader::Request calls will fail and IAsyncReader::WaitForNext calls will always complete immediately.

---

IAsyncReader::EndFlush

IAsyncReader Interface

Completes the flushing operation.

HRESULT EndFlush(void);

Return Values

Returns S_OK if successful, S_FALSE otherwise.

Remarks

Between IAsyncReader::BeginFlush and IAsyncReader::EndFlush calls, IAsyncReader::Request calls will fail and IAsyncReader::WaitForNext calls will always complete immediately. This method is called so the source thread can wait in the IAsyncReader::WaitForNext method again.

---

IAsyncReader::Length

IAsyncReader Interface

Retrieves the stream's total length, and the currently available length.

HRESULT Length(
  LONGLONG* pTotal,
  LONGLONG* pAvailable
  );

Parameters

pTotal

Total allocated length.

pAvailable

Available length.

Return Values

Returns S_OK if successful, E_UNEXPECTED if the file has not been opened.

Remarks

Read operations beyond the available length but within the total length will normally succeed, but they might block for a long period of time.

---

IAsyncReader::Request

IAsyncReader Interface

Queues a request for data.

HRESULT Request(
  IMediaSample* pSample,
  DWORD dwUser
  );

Parameters

pSample

Media sample being requested.

dwUser

[in] User context.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

Value	Meaning
VFW_E_BADALIGN	An invalid alignment was specified.
VFW_E_MEDIA_TIME_NOT_SET	Time has not been set.
HRESULT_FROM_WIN32	Request for data past end of file.
NOERROR	No error.
S_OK	Success.

Remarks

Media sample start and stop times contain the requested absolute byte position (start-inclusive and stop-exclusive). This method might fail if the sample is not obtained from an agreed allocator or if the start or stop position does not match the agreed alignment. The samples allocated from the source pin's allocator might fail IMediaSample::GetPointer until after returning from IAsyncReader::WaitForNext.

The stop position must be aligned, which means it might exceed duration. On completion, the stop position will be corrected to the unaligned actual data.

The dwUser parameter is used by the caller to identify the sample that returned from the IAsyncReader::WaitForNext method. It has no meaning within IAsyncReader but could be used to track individual sample information.

---

IAsyncReader::RequestAllocator

IAsyncReader Interface

Retrieves the actual allocator to be used.

HRESULT RequestAllocator(
  IMemAllocator* pPreferred,
  ALLOCATOR_PROPERTIES* pProps,
  IMemAllocator ** ppActual
  );

Parameters

pPreferred

[in] Preferred allocator.

pProps

[in] Preferred allocator properties (size, count, and alignment).

ppActual

[out] Actual allocator used.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

Value	Meaning
E_FAIL	Failure to initialize an allocator.
VFW_E_BADALIGN	An invalid alignment was specified.
S_OK	Allocator was returned.

Remarks

The preferred allocator and preferred allocator properties must be passed in. This method returns the actual allocator to be used.

IMemAllocator::GetProperties should be called on the returned allocator to learn the alignment and prefix chosen. This allocator will not be committed and decommitted by the asynchronous reader, only by the consumer. This method must be called before calling IAsyncReader::Request.

---

IAsyncReader::SyncRead

IAsyncReader Interface

Performs a synchronous read.

HRESULT SyncRead(
  LONGLONG llPosition,
  LONG lLength,
  BYTE* pBuffer
  );

Parameters

llPosition

[in] Absolute file position.

lLength

[in] Number of bytes required.

pBuffer

[out] Where the data is written.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

Value	Meaning
VFW_E_BADALIGN	An invalid alignment was specified.
HRESULT_FROM_WIN32	Win32 error.
S_FALSE	Size changed (probably due to end of file).
S_OK	Success.

Remarks

The SyncRead method works in a stopped state as well as in a running state. The read is not necessarily aligned. This method fails if the read is beyond the actual total length.

---

IAsyncReader::SyncReadAligned

IAsyncReader Interface

Performs a synchronous read of the data.

HRESULT SyncReadAligned(
  IMediaSample* pSample
  );

Parameters

pSample

Sample to read.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

Value	Meaning
VFW_E_BADALIGN	An invalid alignment was specified.
HRESULT_FROM_WIN32	Win32 error.
S_FALSE	Size changed (probably due to end of file).
S_OK	Success.

Remarks

The sample passed in must have been acquired from the agreed allocator. The start and stop positions must be aligned equivalent to an IAsyncReader::Request/IAsyncReader::WaitForNext pair, but may avoid the need for a thread on the source filter.

---

IAsyncReader::WaitForNext

IAsyncReader Interface

Blocks until the next read requested through IAsyncReader::Request completes or the time-out occurs.

HRESULT WaitForNext(
  DWORD dwTimeout,
  IMediaSample** ppSample,
  DWORD * pdwUser
  );

Parameters

dwTimeout

[in] Time-out in milliseconds; can be zero or INFINITE.

ppSample

[out] Completed sample.

pdwUser

User context.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

Value	Meaning
VFW_E_TIMEOUT	A time-out has expired.
VFW_E_WRONG_STATE	The operation could not be performed because the filter is in the wrong state.
E_FAIL	Failure.
S_OK	Success.

Remarks

Samples may not be returned in order. If there is a read error of any sort, a notification will already have been sent by the source filter, and HRESULT will be an error. If ppSample is not null, a request has been completed with the result code returned.

The pdwUser parameter returns the caller's context DWORD corresponding to the sample returned.

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

Top of Page