IDirectMusicLoader8::LoadObjectFromFile

^{IDirectMusicLoader8::LoadObjectFromFile}

The LoadObjectFromFile method retrieves an object from a file and returns the specified interface. This method can be used instead of IDirectMusicLoader8::GetObject when the object is in a file.

Syntax

HRESULT LoadObjectFromFile(
  REFGUID rguidClassID, 
  REFIID iidInterfaceID, 
  WCHAR *pwzFilePath, 
  void ** ppObject
);

Parameters

rguidClassID

Unique identifier for the class of object. For a list of standard loadable classes, see IDirectMusicLoader8.

iidInterfaceID

Unique identifier of the interface. See DirectMusic Interface GUIDs.

pwzFilePath

Name of the file that contains the object. The path can be fully qualified or relative to the search directory. (See Remarks.)

ppObject

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.

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

Remarks

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.

When pwzFilePath is an unqualified file name or a relative path, the loader searches first in the current directory, then in the Windows search path, and finally in the directory set by the last call to IDirectMusicLoader8::SetSearchDirectory.

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.

Requirements

  Header: Declared in dmusici.h.

See Also

• IDirectMusicLoader8 Interface
• IDirectMusicLoader8::GetObject
• IDirectMusicLoader8::SetSearchDirectory
• Loading an Object from a File