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.

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

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.

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.

Syntax

HRESULT BeginFlush(void);

Return Value

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.

Syntax

HRESULT EndFlush(void);

Return Value

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.

Syntax

HRESULT Length(

  LONGLONG *pTotal,

  LONGLONG *pAvailable

  );

Parameters

pTotal
Pointer to the total allocated length.
pAvailable
Pointer to the available length.

Return Value

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.

Syntax

HRESULT Request(

  IMediaSample *pSample,

  DWORD dwUser

  );

Parameters

pSample
Pointer to the media sample being requested.
dwUser
[in] User context.

Return Value

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

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.

Syntax

HRESULT RequestAllocator(

  IMemAllocator *pPreferred,

  ALLOCATOR_PROPERTIES *pProps,

  IMemAllocator **ppActual

  );

Parameters

pPreferred
[in] Pointer to the preferred allocator.
pProps
[in] Pointer to the preferred allocator properties (size, count, and alignment).
ppActual
[out] Address of a pointer to the actual allocator used.

Return Value

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

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.

Syntax

HRESULT SyncRead(

  LONGLONG llPosition,

  LONG lLength,

  BYTE *pBuffer

  );

Parameters

llPosition
[in] Absolute file position.
lLength
[in] Number of bytes required.
pBuffer
[out] Pointer to where the data is written.

Return Value

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

VFW_E_BADALIGN An invalid alignment was specified.
HRESULT_FROM_WIN32 Microsoft® 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.

Syntax

HRESULT SyncReadAligned(

  IMediaSample *pSample

  );

Parameters

pSample
Pointer to the sample to read.

Return Value

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

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.

Syntax

HRESULT WaitForNext(

  DWORD dwTimeout,

  IMediaSample **ppSample,

  DWORD *pdwUser

  );

Parameters

dwTimeout
[in] Time-out in milliseconds; can be zero or INFINITE.
ppSample
[out] Address of a pointer to the completed sample.
pdwUser
[out] Pointer to the user context.

Return Value

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

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.

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.

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

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.