IDirectMusicAudioPath8::GetObjectInPath

Microsoft DirectX 9.0 SDK Update (October 2004)

IDirectMusicAudioPath8::GetObjectInPath

The GetObjectInPath method retrieves an interface for an object in the audiopath.

Syntax

RESULT GetObjectInPath(
  DWORD dwPChannel,
  DWORD dwStage,
  DWORD dwBuffer,
  REFGUID guidObject,
  DWORD dwIndex,
  REFGUID iidInterface,
  void ** ppObject
);

Parameters

dwPChannel

Performance channel to search, or DMUS_PCHANNEL_ALL to search all channels. The first channel is numbered 0. (See Remarks.)

dwStage

Stage in the audiopath. Can be one of the values in the following table.

Value	Description
DMUS_PATH_AUDIOPATH_GRAPH	Get the audiopath toolgraph. One is created if none exists.
DMUS_PATH_AUDIOPATH_TOOL	Get a tool from the audiopath toolgraph.
DMUS_PATH_BUFFER	Get a DirectSound buffer.
DMUS_PATH_BUFFER_DMO	Get a DMO in a buffer.
DMUS_PATH_MIXIN_BUFFER	Get a global mix-in buffer.
DMUS_PATH_MIXIN_BUFFER_DMO	Get a DMO in a global mix-in buffer.
DMUS_PATH_PERFORMANCE	Get the performance.
DMUS_PATH_PERFORMANCE_GRAPH	Get the performance toolgraph. One is created if none exists.
DMUS_PATH_PERFORMANCE_TOOL	Get a tool from the performance toolgraph.
DMUS_PATH_PORT	Get the synthesizer.
DMUS_PATH_PRIMARY_BUFFER	Get the primary buffer.

dwBuffer

Index of the buffer (if dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER), or index of the buffer in which the DMO resides (if dwStage is DMUS_PATH_BUFFER_DMO or DMUS_PATH_MIXIN_BUFFER_DMO).

guidObject

Class identifier of the object, or GUID_All_Objects to search for an object of any class. This parameter is ignored if only a single class of object can exist at the stage specified by dwStage, and can be set to GUID_NULL.

dwIndex

Index of the object within a list of matching objects. Set to 0 to find the first matching object. If dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER, this parameter is ignored, and the buffer index is specified by dwBuffer.

iidInterface

Identifier of the desired interface, such as IID_IDirectMusicTool.

ppObject

Address of a variable that receives a pointer to the requested interface.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the error values shown in the following table.

Return code

Remarks

The value in dwPChannel must be 0 for any stage that is not channel-specific. Objects in the following stages are channel-specific and can be retrieved by setting a channel number or DMUS_PCHANNEL_ALL in dwPChannel:

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT

The precedence of the parameters in filtering out unwanted objects is as follows:

dwStage.
guidObject. If this value is not GUID_All_Objects, only objects whose class identifier equals guidObject are searched. However, this parameter is ignored for stages where only a single class of object can exist, such as DMUS_PATH_AUDIOPATH_GRAPH.
dwPChannel. If the stage is channel-specific and this value is not DMUS_PCHANNEL_ALL, only objects on the channel are searched.
dwBuffer. This is used only if dwStage is DMUS_PATH_BUFFER, DMUS_PATH_MIXIN_BUFFER, DMUS_PATH_BUFFER_DMO, or DMUS_PATH_MIXIN_BUFFER_DMO.
dwIndex.

If a matching object is found but the interface specified by iidInterface cannot be obtained, the method fails.

The following example function shows how to enumerate the buffers in an audiopath:

void DumpAudioPathBuffers(
    IDirectMusicAudioPath *pDirectMusicAudioPath)
{
  DWORD dwBuffer = 0;
  IDirectSoundBuffer *pDirectSoundBuffer;
 
  while (S_OK == pDirectMusicAudioPath->GetObjectInPath( 
      DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, dwBuffer,
      GUID_NULL, 0, IID_IDirectSoundBuffer, 
      (void**) &pDirectSoundBuffer))
  {
    // Do something with pDirectSoundBuffer.
    // . . .
    dwBuffer++;
    pDirectSoundBuffer->Release();
  }
}

Requirements

Header: Dmusici.h
Library: Dmime.dll, Dmimed.dll

See Also