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

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