IAsyncReader::RequestAllocator method (strmif.h)

Article
07/27/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The RequestAllocator method requests an allocator during the pin connection.

Syntax

HRESULT RequestAllocator(
  [in]  IMemAllocator        *pPreferred,
  [in]  ALLOCATOR_PROPERTIES *pProps,
  [out] IMemAllocator        **ppActual
);

Parameters

[in] pPreferred

Pointer to the IMemAllocator interface on the input pin's preferred allocator, or NULL.

[in] pProps

Specifies the address of an ALLOCATOR_PROPERTIES structure, allocated by the caller. The caller should fill in any allocator properties that the input pin requires, and set the remaining members to zero.

[out] ppActual

Address of a variable that receives an IMemAllocator interface pointer.

Return value

Returns an HRESULT value. Possible values include the following.

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

Remarks

The downstream input pin should call this method during the connection process. If the pin has a preferred allocator, specify it in the pPreferred parameter. Specify any buffer requirements, such as buffer size or alignment, in the pProps parameter. The output pin chooses the allocator and returns a pointer to it in the ppActual parameter.

The output pin is not required to honor the input pin's requests. If the input pin has any absolute requirements, it should call the IMemAllocator::GetProperties method on the returned allocator. It can fail the connect if the allocator properties are not suitable. Once the connection is established, the input pin must use the allocator chosen by the output pin.

The input pin is responsible for committing and decommitting the allocator.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)
Library	Strmiids.lib