Next: 3 Module playback Up: 2 Configurationinitialization and Previous: 5.2 Data types

# 5.3 Functions

This section describes all functions available for MIDAS initialization, configuration and system control. This includes error handling.

## 2.3.1 MIDASstartup

    BOOL MIDASstartup(void)

Prepares MIDAS Sound System for initialization and use.

### Input

None.

### Description

This function sets all MIDAS configuration variables to default values and prepares MIDAS for use. It must be called before any other MIDAS function, including MIDASinit and MIDASsetOption, is called. After this function has been called, MIDASclose can be safely called at any point and any number of times, regardless of whether MIDAS has been initialized or not. After calling this function, you can use MIDASsetOption to change MIDAS configuration before initializing MIDAS with MIDASinit.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption, MIDASinit, MIDASclose

## 2.3.2 MIDASgetLastError

    int MIDASgetLastError(void)

Gets the MIDAS error code for last error.

### Input

None.

### Description

This function can be used to read the error code for most recent failure. When a MIDAS API function returns an error condition, this function can be used to determine the actual cause of the error, and this error can then be reported to the user or ignored, depending on the kind of response needed. Use MIDASgetErrorMessage to get a textual message corresponding to an error code.

This function can be called at any point after MIDASstartup has been called.

### Return value

MIDAS error code for the most recent error.

### Operating systems

All

### See also

MIDASgetErrorMessage

## 2.3.3 MIDASgetErrorMessage

    char *MIDASgetErrorMessage(int errorCode)

Gets an error message corresponding to an error code.

### Input

errorCode
  The error code from MIDASgetLastError

### Description

This function returns a textual error message corresponding to a MIDAS error code. It can be used for displaying an error message to the user. Use MIDASgetLastError to determine the error code.

This function can be called at any point after MIDASstartup has been called.

### Return value

Error message string corresponding to the error code.

### Operating systems

All

### See also

MIDASgetLastError

## 2.3.4 MIDASinit

    BOOL MIDASinit(void)

Initializes MIDAS Sound System.

### Input

None.

### Description

This function initializes all MIDAS Sound System components, and sets up the API. Apart from configuration functions, this function must be called before any other MIDAS functions are used.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption, MIDASclose

## 2.3.5 MIDASclose

    BOOL MIDASclose(void)

Uninitializes MIDAS Sound System.

### Input

None.

### Description

This function uninitializes all MIDAS Sound System components, deallocates all resources allocated, and shuts down all MIDAS processing. This function must always be called before exiting under MS-DOS and is also strongly recommended under other operating systems. After this function has been called, no MIDAS function may be called unless MIDAS is initialized again.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASinit

## 2.3.6 MIDASdetectSD

    BOOL MIDASdetectSD(void)

Attempts to detect the Sound Device to use.

### Input

None.

### Description

This function attempts to detect the Sound Device that should be used. It is called internally by MIDASinit, and should not normally be called by user programs. Note that the function returns TRUE even if it fails to detect a Sound Device.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASinit

## 2.3.7 MIDASsetOption

    BOOL MIDASsetOption(int option, int value)

Sets a MIDAS option.

### Input

option
  Option number (see `enum` MIDASoptions above)
value
  New value for option

### Description

This function sets a value to a MIDAS option. The different number codes for different options are described above. All MIDAS configuration options must be set with this function before MIDASinit is called.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASinit

## 2.3.8 MIDASopenChannels

    BOOL MIDASopenChannels(int numChans)

Opens Sound Device channels for sound and music output.

### Input

numChans
  Number of channels to open

### Description

This function opens a specified number of channels for digital sound and music output. The channels opened can be used for playing streams, samples and modules. When MIDASplayModule is used to play modules, it will use the last possible channels for the module, so that the first `(numChans - number-of-channels-in-module)` channels are available for effects and streams.

If this function has not been called before MIDASplayModule is called, MIDASplayModule will open the channels it needs for module playback. However, if this function has been called, but the number of channels opened is inadequate for the module, MIDASplayModule will return an error and refuse to play the module.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDAScloseChannels, MIDASplayModule

## 2.3.9 MIDAScloseChannels

    BOOL MIDAScloseChannels(void)

Closes Sound Device channels opened with MIDASopenChannels.

### Input

None.

### Description

This function closes Sound Device channels that were opened with MIDASopenChannels. Note that you may not use this function to close channels that were opened by MIDASplayModule -- MIDASstopModule will do that automatically.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASopenChannels, MIDASplayModule, MIDASstopModule

## 2.3.10 MIDASstartBackgroundPlay

    BOOL MIDASstartBackgroundPlay(DWORD pollRate)

Starts playing music and sound in the background.

### Input

pollRate
  Polling rate (number of polls per second), 0 for default

### Description

This function starts playing sound and music in the background. pollRate controls the target polling rate -- number of polls per second. Polling might not be done at actually the set rate, although usually it will be faster. Under Win32 and Linux, a new thread will be created for playing. Under MS-DOS this function is currently ignored, and background playback starts immediately when MIDAS is initialized.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All, but see MS-DOS note above.

### See also

MIDASstopBackgroundPlay, MIDASpoll

## 2.3.11 MIDASstopBackgroundPlay

    BOOL MIDASstopBackgroundPlay(void)

Stops playing sound and music in the background.

### Input

None.

### Description

This function stops music and sound background playback that has been started with MIDASstartBackgroundPlay. Under Win32 and Linux, this function also destroys the thread created for playback. Under MS-DOS this function is currently ignored, and background playback starts immediately when MIDAS is initialized.

If background playback has been started with MIDASstartBackgroundPlay, this function bf must be called before the program exits.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All, but see MS-DOS note above.

### See also

MIDASstartBackgroundPlay, MIDASpoll

## 2.3.12 MIDASpoll

    BOOL MIDASpoll(void)

Polls the MIDAS sound and music player.

### Input

None.

### Description

This function can be used to poll MIDAS sound and music player manually. It plays music forward, mixes sound data, and sends it to output. When using manual polling, make sure you call MIDASpoll often enough to make sure there are no breaks in sound output -- at least two times during buffer length, preferably four times or more. Under multitasking operating systems such as Win32 and Linux, this may be difficult, so very short buffer sizes can't be used reliably.

Also note that currently this function is not available under MS-DOS. Under MS-DOS, playback is always done in background using the system timer (IRQ 0).

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32, Linux

### See also

MIDASstartBackgroundPlay, MIDASstopBackgroundPlay

## 2.3.13 MIDASgetVersionString

    char *MIDASgetVersionString(void)

Gets the current MIDAS version as a string.

### Input

None.

### Description

This function can be used to determine the MIDAS version being loaded. It returns a text string description of the version. Version numbers are usually of form ``x.y.z'', where ``x'' is the major version number, ``y'' minor version number and ``z'' patch level. In some occasions, ``z'' can be replaced with a textual message such as ``rc1'' for Release Candidate 1. All MIDAS versions with the major and minor version numbers equal have a compatible DLL API, and can be used interchangeably.

### Return value

MIDAS Sound System version number as a string.

### Operating systems

Win32, Linux

### See also

Next: 3 Module playback Up: 2 Configurationinitialization and Previous: 5.2 Data types