CDLSLoader

CDLSLoader

Purpose: Loads DLS, WAV and segment files. Frees the collections objects from memory.
Remark: The returns values are based on the DirectX9 constants except DM_FAILED
The functions raise a CDMusicException exception type with the error data.
Member functions:

Function: Initialize
Declaration: HRESULT CDLSLoader::Initialize()
Purpose: Instantiate the Loader DirectMusic COM object
Parameters: none

Returns:

S_OK

Succeeds

Throws:

REGDB_E_CLASSNOTREG

The specified class is not registered in the registration database or the register is corrupt

Top Index

Function: LoadDLS
Declaration: HRESULT CDLSLoader::LoadDLS(LPSTR lpFileName,CCollection &pCollection)
Purpose: Loads DLS files into Collections objects given the NULL terminated string of the file path
Parameters:

lpFileName [in]: NULL terminated file path.
pCollection [out]: Reference to the CCollection object

Remarks: If NULL is passed to the lpFileName parameter, the built-in GM/GS set is loaded

Returns:

S_OK

Succeeds

Throws:

DMUS_E_LOADER_FAILEDOPEN	File open failed because the file does not exist or is locked
DMUS_E_LOADER_FAILEDCREATE	The object could not be found or created
DMUS_E_LOADER_FORMATNOTSUPPORTED	The object cannot be loaded because the data format is not supported
REGDB_E_CLASSNOTREG	The object class is not registered
DM_FAILED	Error, see DirectMidi causes
DMUS_E_LOADER_NOCLASSID	No class identifier was supplied in the object description
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL	The method did not succeed
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY	Insufficient memory to complete the task

Top Index

Function: LoadDLSFromResource
Declaration: HRESULT CDLSLoader::LoadDLSFromResource(LPTSTR strResource,LPTSTR strResourceType,CCollection &pCollection)
Purpose: Loads DLS files into Collections objects from resources given the resource identificator
Parameters:

strResouce [in]: Specifies the name of the resource
strResourceType [in]: Specifies the resource type
pCollection [in]: Reference to the CCollection object

Returns:

S_OK

Succeeds

Throws:

DMUS_E_LOADER_FAILEDOPEN	File open failed because the file does not exist or is locked
DMUS_E_LOADER_FAILEDCREATE	The object could not be found or created
DMUS_E_LOADER_FORMATNOTSUPPORTED	The object cannot be loaded because the data format is not supported
REGDB_E_CLASSNOTREG	The object class is not registered
DM_FAILED	Error, see DirectMidi causes
DMUS_E_LOADER_NOCLASSID	No class identifier was supplied in the object description
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL	The method did not succeed
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY	Insufficient memory to complete the task

Top Index

Function: LoadSegment
Declaration: HRESULT CDLSLoader::LoadSegment(LPTSTR lpstrFileName,CSegment &Segment,BOOL bIsMIDIFile)
Purpose: Loads WAV, MID and SGT files into CSegment objects given the NULL terminated string of the file path
Parameters:

lpFileName [in]: NULL terminated file path.
Segment [out]: Reference to the CSegment object
bIsMIDIFile [in]: Specifies if it's a MIDI file or not (Do not set this parameter if the file might contain DLS instrument data. Doing so causes the DLS instruments to be ignored and standard GM instruments to be used)

Remarks: This method can load compressed .WAV file formats such as GSM 6.10, MP3 if availabe in the system.

Returns:

S_OK

Succeeds

Throws:

DMUS_E_LOADER_FAILEDOPEN	File open failed because the file does not exist or is locked
DMUS_E_LOADER_FAILEDCREATE	The object could not be found or created
DMUS_E_LOADER_FORMATNOTSUPPORTED	The object cannot be loaded because the data format is not supported
REGDB_E_CLASSNOTREG	The object class is not registered
DM_FAILED	Error, see DirectMidi causes
DMUS_E_LOADER_NOCLASSID	No class identifier was supplied in the object description
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL	The method did not succeed
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
DMUS_E_TRACK_NOT_FOUND	There is no track of the requested type
DMUS_E_SET_UNSUPPORTED	Setting the parameter is not supported
E_OUTOFMEMORY	Insufficient memory to complete the task

Function: LoadSegmentFromResource
Declaration: HRESULT CDLSLoader::LoadSegmentFromResource(TCHAR *strResource,TCHAR *strResourceType,CSegment &Segment,BOOL bIsMidiFile)
Purpose: Loads WAV, MID and SGT files into CSegment objects from resources
Parameters:

strResouce [in]: Specifies the name of the resource
strResourceType [in]: Specifies the resource type
Segment [in]: Reference to the CSegment object
bIsMIDIFile [in]: Specifies if it's a MIDI file or not (Do not set this parameter if the file might contain DLS instrument data. Doing so causes the DLS instruments to be ignored and standard GM instruments to be used)

Returns:

S_OK

Succeeds

Throws:

DMUS_E_LOADER_FAILEDOPEN	File open failed because the file does not exist or is locked
DMUS_E_LOADER_FAILEDCREATE	The object could not be found or created
DMUS_E_LOADER_FORMATNOTSUPPORTED	The object cannot be loaded because the data format is not supported
REGDB_E_CLASSNOTREG	The object class is not registered
DM_FAILED	Error, see DirectMidi causes
DMUS_E_LOADER_NOCLASSID	No class identifier was supplied in the object description
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL	The method did not succeed
DMUS_E_TRACK_NOT_FOUND	There is no track of the requested type
DMUS_E_SET_UNSUPPORTED	Setting the parameter is not supported
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY	Insufficient memory to complete the task

Top Index

Function: LoadWaveFile
Declaration: HRESULT CDLSLoader::LoadWaveFile(LPTSTR lpstrFileName,CSampleInstrument &pSampleInstrument,BOOL bReadAlways)
Purpose: Loads a wave file (.WAV) into a CSampleInstrument object
Parameters:

lpstrFileName [in]: NULL terminated MBCS/UNICODE string containing the path and filename of a .WAV file
pSampleInstrument [in]: A reference to a CSampleInstrument object
bReadAlways [in]: Specifies the access mode to the wave data. Can be one of the followings values:
DM_LOAD_FROM_FILE: The file is always read when the .wav file and raw data are required
DM_USE_MEMORY: The .wav file is read once and the raw data is stored in memory

Returns:

S_OK

Succeeds

Throws:

E_OUTOFMEMORY	Problem allocating the CWaveFile object
E_FAIL	The method did not succeed

Top Index

Function: SetSearchDirectory
Declaration: HRESULT CDLSLoader::SetSearchDirectory(LPTSTR pszPath,BOOL fClear)
Purpose: Sets a search path for finding files
Parameters:

pszPath [in]: MBCS/UNICODE string containing the path to search
fClear [in]: If TRUE, clears all information about objects before setting the directory. This prevents the loader from accessing objects in a previous directory when those objects have the same name. However, objects are not removed from the cache

Returns:

S_OK

Succeeds

Throws:

E_OUTOFMEMORY	Insufficient memory to complete the task
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
DMUS_E_LOADER_BADPATH	The file path is invalid
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: UnloadCollection
Declaration: HRESULT CDLSLoader::UnloadCollection(CCollection &pCollection)
Purpose: Unloads a CCollection object from memory
Parameters:

pCollection [in]: Reference to the CCollection object

Returns:

S_OK	Succeeds
DM_FAILED	Error, see DirectMidi causes

Throws:

E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
S_FALSE	The object has already been released or cannot be found in the cache

Top Index