DirectMusicAudioPath8.GetObjectInPath

The GetObjectInPath method retrieves an object in the audiopath.

object.GetObjectInPath( _
  lPChannel As Long, _
  lStage As CONST_DMUSIC_PATH, _
  lBuffer As Long, 
  guidObject As String, _
  lIndex As Long, _
  iidInterface As String _
) As Unknown

Parts

object

Resolves to a DirectMusicAudioPath8 object.

lPChannel

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

lStage

Stage in the path. One of the constants from the CONST_DMUSIC_PATH enumeration. See Remarks.

lBuffer

If lStage is DMUS_PATH_BUFFER_DMO or DMUS_PATH_MIXIN_BUFFER_DMO, specifies the index of the buffer in which that DMO resides. If lStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER, specifies the index of the buffer. Otherwise must be 0.

guidObject

Class identifier of the object, such as CLSID_DirectMusicPerformance, 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 lStage, and can be set to GUID_NULL.

lIndex

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

iidInterface

Identifier of the desired class. This can be a GUID in string form, or one of the identifiers in the AUDIOSTRINGCONSTANTS module, such as IID_DirectSoundPrimaryBuffer.

Return Values

Returns an object of the class specified in iidInterface.

Error Codes

If the method fails, an error is raised. Possible values of Err.Number include the following:

Remarks

The value in lPChannel 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 lPChannel:

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. lStage.
2. guidObject. If this value is not GUID_All_Objects, only objects whose class identifier equals guidObject are searched. However, this parameter is ignored if only a single class of object can be found at the specified stage.
3. lPChannel. If the stage is channel-specific and this value is not DMUS_PCHANNEL_ALL, only objects on the channel are searched.
4. lBuffer. This is used only if lStage is DMUS_PATH_BUFFER, DMUS_PATH_MIXIN_BUFFER, DMUS_PATH_BUFFER_DMO, or DMUS_PATH_MIXIN_BUFFER_DMO.
5. lIndex.

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

Not all types of objects that can be retrieved by this method are supported in DirectX for Visual Basic. For example, it would be meaningless to pass DMUS_PATH_PERFORMANCE_TOOL in lStage, because tools are not supported.

See Also

Retrieving Objects from an Audiopath