IXACTCue::GetChannelMap

Retrieves the current channel map.

HRESULT GetChannelMap(
  LPXACTCHANNELMAP pChannelMap,
  DWORD BufferSize,
  LPDWORD pRequiredSize
);

Parameters

pChannelMap
[out, optional] Pointer to an XACTCHANNELMAP structure that receives the channel map.
BufferSize
[in, optional] Size, in bytes, of the channel map.
pRequiredSize
[out, optional] Size, in bytes, of the buffer required to store the channel map.

Return Values

Returns S_OK if successful, an error code otherwise.

Remarks

This function must be called twice, first to determine the size of the buffer required to receive the channel map, and then to retrieve the channel map.

To allocate a buffer of the size required to receive the channel map
  1. Set pChannelMap to NULL.
  2. Set BufferSize to 0.
  3. Declare a temporary variable to pass its address as pRequiredSize.
  4. Call GetChannelMap with these settings.

  5. Allocate a memory block of the size (in bytes) returned in pRequiredSize.

To retrieve the channel map
  1. Set pChannelMap to the address of the memory block allocated in the prior procedure.
  2. Set BufferSize to the value returned in pRequiredSize by the prior procedure.
  3. Set pRequiredSize to NULL.
  4. Call GetChannelMap with these settings.
  5. The channel map returned in pChannelMap can then be referenced as an XACTCHANNELMAP structure

It is not valid to call GetChannelMap with BufferSize set to a nonzero value that is smaller than the size returned in pRequiredSize.

Example

The following example shows correct procedure for using GetChannelMap.

// Query how much memory is needed for the channel map
DWORD dwChannelMapBufferSize;
pCue->GetChannelMap( NULL, 0, &dwChannelMapBufferSize );

// Now allocate the memory with our version of malloc()
LPXACTCHANNELMAP pChannelMap = (LPXACTCHANNELMAP) MyMalloc (dwChannelMapBufferSize) ;

// Retrieve the channel map for the cue
pCue->GetChannelMap( pChannelMap, dwChannelMapBufferSize, NULL );

Requirements

Header: Declared in Xact.h.

See Also

IXACTCue