Share via

IDirectMusicLoader::GetObject

  • Article

This 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 can return one of the following error values:

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

Remarks

A return value of DMUS_S_PARTIALLOAD can 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 an internal name plus category, followed by an internal name, followed by a local file name.

Requirements

OS Versions: Windows CE .NET 4.0 and Windows CE .NET 4.1.
Header: Dmusici.h.
Link Library: Dmusic.lib.

See Also

IDirectMusicLoader::ReleaseObject | IDirectMusicLoader::ScanDirectory | DMUS_OBJECTDESC

 Last updated on Monday, April 12, 2004

© 1992-2002 Microsoft Corporation. All rights reserved.