Miles Sound System SDK 7.2a

AIL_file_read

The function AIL_file_read loads a data file into the specified memory address, optionally allocating the memory as well.

void * AIL_file_read(
  char const * filename,
  void *dest
);

In Parameters

filename: specifies the data file that you'd like to read.

Out Parameters

dest: specifies the address of where you'd like the data loaded. If you pass in NULL for this parameter, then MSS will allocate the memory to hold the data file with AIL_mem_alloc_lock. You can also pass in the flag "FILE_READ_WITH_SIZE" for the dest parameter. This flag also tells MSS to allocate the memory to hold the data file, but, in addition, it will place the size of the data in the first four bytes of the buffer. This saves an extra call to the AIL_file_size function.

Returns

If *dest was NULL, then this function will return the pointer to the new memory block. If *dest was an address, then this function will just return *dest. If an error occurred, then this function will return NULL - use AIL_file_error and AIL_last_error to get the specific error.

Discussion

If you use this function to allocate the memory for you, then you must free the pointer it returns with AIL_mem_free_lock or your application will leak.

Under DOS and MacOS 9, this function must not be invoked from an interrupt-based callback function.

Example files that use this function: DEMO.C

Group: Memory and File Services
Related Functions: AIL_file_error, AIL_file_fss_read, AIL_file_size, AIL_file_write, AIL_last_error, AIL_mem_alloc_lock, AIL_mem_free_lock, AIL_set_file_async_callbacks, AIL_set_file_callbacks
Related Basic Types: char const *, void, void *
Related FAQs: How careful do I have to be when shutting down?, How do I play a digital sound?, How do I play an XMIDI file with a DLS instrument set?, How do I play an XMIDI or MIDI file?