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. |
Starts the flushing operation.
HRESULT BeginFlush(void);
Returns an HRESULT value.
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.
Completes the flushing operation.
HRESULT EndFlush(void);
Returns an HRESULT value.
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.
Retrieves the stream's total length, and the currently available length.
HRESULT Length(
LONGLONG* pTotal,
LONGLONG* pAvailable
);
Returns an HRESULT value.
Read operations beyond the available length but within the total length will normally succeed, but they might block for a long period of time.
Queues a request for data.
HRESULT Request(
IMediaSample* pSample,
DWORD dwUser
);
Returns an HRESULT value.
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.
Retrieves the actual allocator to be used.
HRESULT RequestAllocator(
IMemAllocator* pPreferred,
ALLOCATOR_PROPERTIES* pProps,
IMemAllocator ** ppActual
);
Returns an HRESULT value.
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.
Performs a synchronous read.
HRESULT SyncRead(
LONGLONG llPosition,
LONG lLength,
BYTE* pBuffer
);
Returns an HRESULT value.
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.
Performs a synchronous read of the data.
HRESULT SyncReadAligned(
IMediaSample* pSample
);
Returns an HRESULT value.
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.
Blocks until the next read requested through IAsyncReader::Request completes or the time-out occurs.
HRESULT WaitForNext(
DWORD dwTimeout,
IMediaSample** ppSample,
DWORD * pdwUser
);
Returns an HRESULT value.
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.