Miles Sound System SDK 7.2a

AIL_extract_DLS

The function AIL_extract_DLS extracts and decompresses the DLS data from a loaded MLS file or merged XMIDI file.

S32 AIL_extract_DLS(
  void const * data,
  U32 size,
  void * *XMI,
  U32 *XMI_size,
  void * *dls,
  U32 *dlssize,
  AILLENGTHYCB callback
);

In Parameters

data: points to a file image containing an MLS file, or an XMIDI file with embedded DLS data.
size: is the length of the data.
callback: should be set to the address of the callback function which is invoked at several stages of the decompression process. See AILLENGTHYCB for a description of this callback.

Out Parameters

XMI: should be the address of a " void* " pointer that will return with the pointer to the new XMIDI file image. This parameter can be NULL if you don't need it.
XMI_size: should be the address of an unsigned 32-bit integer that will return with the size of the new XMIDI file image. This parameter can be NULL if you don't need it.
dls: should be the address of a " void* " pointer that will return with the pointer to the new uncompressed DLS file image. This parameter can be NULL if you don't need it.
dlssize: should be the address of an unsigned 32-bit integer that will return with the size of the new uncompressed DLS file image. This parameter can be NULL if you don't need it.

Returns

1, if the call was successful, or 0 if the call failed.

Discussion

This function returns copies of the XMIDI and DLS data - that is, you must call AIL_mem_free_lock on the returned XMIDI and DLS pointers. If you want to obtain direct pointers to the XMIDI and DLS chunks inside the original file image, you can use the AIL_find_DLS function.

A good way to decide whether to use AIL_extract_DLS or AIL_find_DLS is whether the DLS data is compressed. If the data is uncompressed, then you can pass it directly to AIL_DLS_load_memory, so AIL_find_DLS can be used. If the data is compressed, then you must decompress it with AIL_extract_DLS before handing it off to AIL_DLS_load_memory. You can determine whether the data is compressed or not with the AIL_file_type function.

Group: Utility Services
Related Functions: AILLENGTHYCB, AIL_DLS_load_file, AIL_DLS_load_memory, AIL_compress_DLS, AIL_extract_DLS, AIL_file_type, AIL_filter_DLS_with_XMI, AIL_find_DLS, AIL_mem_free_lock, AIL_merge_DLS_with_XMI
Related Basic Types: S32, U32, void *, void const *
Related FAQs: How do I play an XMIDI file with a DLS instrument set?