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:
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:
- 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 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") );
}
}
Header: Declared in dmusici.h.
See Also
IDirectMusicSegmentState8::GetObjectInPath, Retrieving Objects from an Audiopath