IAMDevMemoryControl Interface

The IAMDevMemoryControl interface controls and identifies the on-board memory of codecs. A device memory control object supports this interface. This object is aggregated with an IMemAllocator object that is used in the connection. Typically, filters will call the IAMDevMemoryAllocator::GetDevMemoryObject method to obtain a pointer to this interface.

Implement this interface with the IAMDevMemoryAllocator interface when pins need to have greater control of memory allocation.

Use this interface to synchronize the completion of writing data to a memory allocator, and to get the device ID of the on-board memory allocator.

Methods in Vtable Order

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

IAMDevMemoryControl methods Description

QueryWriteSync Checks if the memory supported by the allocator requires the use of the WriteSync method.
WriteSync Used to synchronize with the completed write operation by returning when any data being written to the specified allocator region is fully written into the memory.
GetDevId Retrieves the device ID of the on-board memory allocator.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMDevMemoryControl methods	Description
QueryWriteSync	Checks if the memory supported by the allocator requires the use of the WriteSync method.
WriteSync	Used to synchronize with the completed write operation by returning when any data being written to the specified allocator region is fully written into the memory.
GetDevId	Retrieves the device ID of the on-board memory allocator.

IAMDevMemoryControl::GetDevId

IAMDevMemoryControl Interface

Retrieves the device ID of the on-board memory allocator.

Syntax

HRESULT GetDevId(
  DWORD *pdwDevId
  );

Parameters

pdwDevId
[out] Pointer to the device ID.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method retrieves a unique ID that the hardware filter can use to verify that the specified allocator passed uses its on-board memory (because there can be more than one). The ID will be the same one as used to create the allocator object (using CoCreateInstance). For another filter to be able to use the on-board memory, it must have the same device ID as the on-board memory allocator.

IAMDevMemoryControl::QueryWriteSync

IAMDevMemoryControl Interface

Checks if the memory supported by the allocator requires the use of the IAMDevMemoryControl::WriteSync method.

Syntax

HRESULT QueryWriteSync(void);

Return Value

Returns S_OK if the method is required, or S_FALSE otherwise.

Remarks

Not all on-board memory needs to have WriteSync called to synchronize with the completed write. This method is used to check if the call is necessary.

IAMDevMemoryControl::WriteSync

IAMDevMemoryControl Interface

Used to synchronize with the completed write. This method returns when any data being written to the particular allocator region is fully written into the memory.

Syntax

HRESULT WriteSync(void);

Return Value

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

E_FAIL A time-out has occurred without this method confirming that data was written.
S_OK The data was successfully written into memory.
VFW_E_NOT_COMMITTED The allocator hasn't called the IMemAllocator::Commit method.

Remarks

This method guarantees that all prior write operations to allocated memory have succeeded. Subsequent memory write operations require another call to WriteSync.
This method is implementation dependent, and is used (when necessary) to synchronize memory write operations to the memory. The driver of the on-board memory provides the implementation.
The IAMDevMemoryControl interface is typically found on memory that is accessed through a Peripheral Component Interconnect (PCI) bridge. (A PCI is a local bus for personal computers that provides a high-speed data path between the processor and peripheral devices.) Memory behind a PCI bridge must be synchronized after a memory write operation completes, if another device will access that memory from behind the PCI bridge. This is because the host access to the memory is buffered through the PCI bridge FIFO (first in first out), and the host will assume the write is completed before the bridge actually writes the data. A subsequent action by a device behind the bridge, such as a SCSI controller, might read the memory before the write is completed, if the IAMDevMemoryControl::WriteSync method is not called.

E_FAIL	A time-out has occurred without this method confirming that data was written.
S_OK	The data was successfully written into memory.
VFW_E_NOT_COMMITTED	The allocator hasn't called the IMemAllocator::Commit method.