IDirectMusicLoader8::GetObject

^{IDirectMusicLoader8::GetObject}

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

Syntax

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 DirectMusic Interface GUIDs.

ppv

Address of a variable that receives 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.

DMUS_S_PARTIALLOAD is returned if any referenced object cannot be found, such as a style referenced in a segment. The loader might fail to find the style if it is referenced by name but IDirectMusicLoader8::ScanDirectory has not been called for styles. DMUS_S_PARTIALLOAD might also mean that the default instrument collection file, Gm.dls, is not available.

If it fails, the method can return one of the error values shown in the following table.

Remarks

For file objects, it is simpler to use the IDirectMusicLoader8::LoadObjectFromFile method.

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. The dwValidData flags are evaluated in the following order:

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

In other words, the highest priority goes to a unique GUID, followed by a stream pointer, 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.

Do not load data from untrusted sources. Loading DirectMusic data files causes objects to be constructed, with the possibility that excessive demand on resources will lead to degradation of performance or system failure.

Requirements

  Header: Declared in dmusici.h.

See Also

• IDirectMusicLoader8 Interface
• IDirectMusicLoader8::LoadObjectFromFile
• IDirectMusicLoader8::ReleaseObject
• IDirectMusicLoader8::ScanDirectory
• Loading Audio Data