4.3 Calling conventions

All internal MIDAS Sound System functions use the same calling conventions and a similar method for returning data. This simplifies programming, as all functions behave consistently, and ensures that error codes get handled properly.

4.3.1 Error codes

All functions in MIDAS Sound System return an error code. There is no exception to this, and all other data is returned using pointers (see below). This simplifies error handling, and makes sure error codes always get handled properly. In addition, when MIDAS is compiled with DEBUG mode on, the error handling functions can supply detailed information about the errors that happened, such as which function originally caused the error and what functions called it.

4.3.2 Returning data

As the return value of the function is always reserved for the error code, all other data will need to be returned by using pointers. All MIDAS functions that return data will accept as their last arguments pointers to the variables that will hold the return values. Make sure you always pass these functions legal pointers as the return variables even if you don't need the return values -- memory corruption may occur otherwise.

For example, to query the current volume on channel 3 in the default Sound Device, you can use:

unsigned vol;
...
midasSD->GetVolume(3, &vol);
...

Note that in a real-life program you also need to handle the returned error code.

[TODO:OS-Specific] MS-DOS Note! Code using MIDAS needs to have the compiler ''SS==DS'' -assumption disabled. This is because the stack used by the timer interrupt (and thus most of MIDAS code plus any user callbacks) might be different from the main program stack, and the compiler should therefore not generate code that uses data segment variables via the stack segment. Because of this, any pointers that you pass to MIDAS functions need to point to data segment variables -- in other words, in the example above,

unsigned vol;

needs to be changed to

static unsigned vol;

to ensure the local variable gets placed in data segment. Pointers to global variables can naturally be used without any modifications.