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 |
| 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
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