IDirectMusicLoader::GetObject

The IDirectMusicLoader::GetObject method retrieves the specified object from a file or resource and returns the desired interface.

HRESULT GetObject(
  LPDMUS_OBJECTDESC pDESC,
  REFIID riid,
  LPVOID FAR * ppv
);
 

Parameters

pDESC

Address of a DMUS_OBJECTDESC structure describing the object.

riid

Unique identifier of the interface. See the IID defines in Dmusici.h. All the standard interfaces have a defined identifier consisting of "IID_" plus the name of the interface. For example, the identifier of IDirectMusicTrack is IID_IDirectMusicTrack.

ppv

Address of a variable to receive a pointer to the desired interface of the object.

Return Values

If the method succeeds, the return value is S_OK or DMUS_S_PARTIALLOAD.

If it fails, the method may return one of the following error values:

Remarks

A return value of DMUS_S_PARTIALLOAD may mean that the default instrument collection file, Gm.dls, is not available.

The current version of DirectMusic does not support loading from URLs. If the dwValidData member of the DMUS_OBJECTDESC structure contains DMUS_OBJ_URL, the method returns DMUS_E_LOADER_FORMATNOTSUPPORTED.

The method does not require that all valid members of the DMUS_OBJECTDESC structure match before retrieving an object. It searches in the following order:

1. DMUS_OBJ_OBJECT
2. DMUS_OBJ_MEMORY
3. DMUS_OBJ_FILENAME and DMUS_OBJ_FULLPATH
4. DMUS_OBJ_NAME and DMUS_OBJ_CATEGORY
5. DMUS_OBJ_NAME
6. DMUS_OBJ_FILENAME

In other words, the highest priority goes to a unique GUID, followed by a resource, followed by the full file path name, followed by internal name plus category, followed by internal name, followed by local file name.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusici.h.

See Also

IDirectMusicLoader::ReleaseObject, IDirectMusicLoader::ScanDirectory, Loading Objects