Microsoft DirectX 8.0 (C++)

IDirectMusicAudioPath8::GetObjectInPath

Retrieves an interface for an object in the audiopath.

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 path. Can be one of the following values.
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. For information on DMO interfaces, see IDirectSoundBuffer8::GetObjectInPath.
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
If dwStage is DMUS_PATH_BUFFER_DMO or DMUS_PATH_MIXIN_BUFFER_DMO, the index of the buffer in which that DMO resides. If dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER, the index of the buffer. Otherwise must be 0.
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 following error values:

DMUS_E_NOT_FOUND
E_INVALIDARG
E_OUTOFMEMORY
E_NOINTERFACE
E_POINTER

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
DMUS_PATH_SEGMENT_TOOL

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

  1. dwStage.
  2. 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.
  3. dwPChannel. If the stage is channel-specific and this value is not DMUS_PCHANNEL_ALL, only objects on the channel are searched.
  4. 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.
  5. dwIndex.

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

The following sample shows how to enumerate the buffers in an audiopath. The _stprintf function is declared in Tchar.h.

void DumpAudioPathBuffers(
        IDirectMusicAudioPath *pDirectMusicAudioPath)
{
    TCHAR tcstrText[256];
    DWORD dwBuffer = 0;
    IDirectSoundBuffer *pDirectSoundBuffer;
 
    while(S_OK == pDirectMusicAudioPath->GetObjectInPath( 
        DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, dwBuffer,
        GUID_NULL, 0, IID_IDirectSoundBuffer, 
        (void**) &pDirectSoundBuffer))
    {
        _stprintf( tcstrText, _T("Found buffer %x.\n"),
                pDirectSoundBuffer);
        OutputDebugString( tcstrText );
        dwBuffer++;
        pDirectSoundBuffer->Release();
    }
 
    if( dwBuffer == 0 )
    {
        OutputDebugString( _T("No buffers in audiopath.\n") );
    }
}

Requirements

  Header: Declared in dmusici.h.

See Also

IDirectMusicSegmentState8::GetObjectInPath, Retrieving Objects from an Audiopath