Edit

Share via

ISpatialAudioMetadataReader::ReadNextItemCommand method (spatialaudiometadata.h)

  • Article

Reads metadata commands and value data for the current item.

Syntax

HRESULT ReadNextItemCommand(
  [out] BYTE   *commandID,
  [in]  void   *valueBuffer,
  [in]  UINT32 maxValueBufferLength,
  [out] UINT32 *valueBufferLength
);

Parameters

[out] commandID

Receives the command ID for the current command.

[in] valueBuffer

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.

[in] maxValueBufferLength

The maximum size of a command value.

[out] valueBufferLength

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
SPTLAUD_MD_CLNT_E_NO_ITEMS_OPEN
 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.
E_INVALIDARG
 One of the provided pointers is not valid.

Remarks

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.

Requirements

Requirement Value
Target Platform Windows
Header spatialaudiometadata.h

See also

ISpatialAudioMetadataReader