ISpatialAudioMetadataReader::ReadNextItemCommand method (spatialaudiometadata.h)

Reads metadata commands and value data for the current item.


HRESULT ReadNextItemCommand(
  BYTE   *commandID,
  void   *valueBuffer,
  UINT32 maxValueBufferLength,
  UINT32 *valueBufferLength



Receives the command ID for the current command.


A pointer to a buffer which receives data specific to the command as specified by the metadata format definition. The buffer must be at least maxValueBufferLength to ensure all commands can be successfully retrieved.


The maximum size of a command value.


The size, in bytes, of the data written to the valueBuffer parameter.

Return value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return code Description
The ISpatialAudioMetadataItems has not been opened for reading with a call to Open or the object has been closed for writing with a call to Close.
One of the provided pointers is not valid.


Before calling ReadNextItem, you must open the ISpatialAudioMetadataReader for reading by calling Open after the object is created and after Close has been called. You must also call ReadItemCountInFrames and then call ReadNextItem before calling ReadNextItem.

The ISpatialAudioMetadataReader keeps an internal pointer to the current position within the total range of frames contained by the ISpatialAudioMetadataItems with which the reader is associated. Each call to this method causes the pointer to be advanced by the number of frames specified in the readFrameCount parameter.

The process for reading commands and the associated values is recursive. After each call to ReadItemCountInFrames, call ReadNextItem to get the number of commands in the next item. After every call to ReadNextItem, call ReadNextItemCommand to read each command for the item. Repeat this process until the entire frame range of the ISpatialAudioMetadataItems has been read.


Target Platform Windows
Header spatialaudiometadata.h

See also