Next: 3 System control Up: 2 Configurationinitialization and Previous: 6.2 Data types

# 6.3 Functions

This section describes all functions available for MIDAS initialization and configuration.

## 2.3.1 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.2 MIDASconfig

    BOOL MIDASconfig(void)

Runs manual MIDAS setup.

### Input

None.

### Description

This function runs the manual MIDAS MS-DOS setup. It prompts the user for the sound card to use, its hardware setup, and the desired output mode. The setup entered can be saved do disk with MIDASsaveConfig, and loaded back with MIDASloadConfig. These functions can be used to create a simple external setup program, or just save the settings between two runs of the program. After this function has been called, MIDASsetOption can be used to change the output mode options, to, for example, force mono output.

This function returns TRUE if the setup was completed successfully, FALSE if not. The setup can fail for two reasons: either the user aborted it by pressing escape, or an error occured. As errors during the setup are extremely unlikely, it is safe to simply exit the program if this function returns FALSE. MIDASgetLastError can be used to check if an error occured -- if the return value is zero, the user just pressed Escape.

This function must be called before MIDASinit, but after MIDASstartup.

### Return value

TRUE if successful, FALSE if not (the user pressed escape, or an error occured)

### Operating systems

MS-DOS

### See also

MIDASsaveConfig, MIDASloadConfig, MIDASsetOption, MIDASinit

## 2.3.3 MIDASdetectSoundCard

    BOOL MIDASdetectSoundCard(void)

Attempts to detect the sound card to use.

### Input

None.

### Description

[MS-DOS only]

This function attempts to detect the sound card that should be used. It will set up MIDAS to use the detected card, and return TRUE if a sound card was found, FALSE if not. If this function returns FALSE, you should run MIDASconfig to let the user manually select the sound card. Note that you can use MIDAS even if no sound card has been selected - MIDAS will just not play sound in that case.

If no sound card has been manually set up, MIDASinit will automatically detect it, or use No Sound if none is available. Therefore this function does not have to be called if manual setup will not be used.

Note that, as there is no way to safely autodetect the Windows Sound System cards under MS-DOS, MIDAS will not attempt to detect them at all. If you do not provide a manual setup possibility to your program (via MIDASconfig), WSS users will not be able to get any sound. The computer may also have several sound cards, and the user may wish not to use the one automatically detected by MIDAS. Therefore it is a very good idea to include an optional manual sound setup to all programs.

This discussion naturally applies to MS-DOS only, under Win32 and Linux MIDAS uses the sound card through the system audio devices, and no sound card selection or setup is necessary.

### Return value

TRUE if a sound card was detected, FALSE if not.

### Operating systems

MS-DOS

### See also

MIDASconfig, MIDASinit

## 2.3.4 MIDASgetDisplayRefreshRate

    DWORD MIDASgetDisplayRefreshRate(void)

Gets the current display refresh rate.

### Input

None.

### Description

This function tries to determine the current display refresh rate. It is used with MIDASsetTimerCallbacks to set a display-synchronized timer callback. It returns the current display refresh rate in milliHertz (ie. 1000*Hz, 50Hz becomes 50000, 70Hz 70000 etc), or 0 if it could not determine the refresh rate. The refresh rate may be unavailable when running under Win95 or a similar OS, or when the VGA card does return Vertical Retraces correctly (as some SVGA cards do in SVGA modes). Therefore it is important to check the return value, and substitute some default value if it is zero.

Unlike most other MIDAS functions, this function must be called before MIDASinit is called, as the MIDAS timer may interfere with the measurements.

Note that the display refresh rate is display mode specific. Therefore you need to set up the display mode with which you want to use display-synchronized timer callbacks before calling this function. Also, if your application uses several display modes, you must get the display refresh rate for each mode separately, and remove and restart the display-synchronized timer callbacks at each mode change.

This function is only available in MS-DOS.

### Return value

The current display refresh rate, in milliHertz, or 0 if unavailable.

### Operating systems

MS-DOS

### See also

MIDASsetTimerCallbacks

## 2.3.5 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.6 MIDASloadConfig

    BOOL MIDASloadConfig(char *fileName)

Load MIDAS setup from disk.

### Input

fileName
  Setup file name

### Description

This function loads MIDAS setup from disk. The setup must have been saved with MIDASsaveConfig. MIDASsetOption can be used afterwards to change, for example, the output mode.

This function must be called before MIDASinit, but after MIDASstartup.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

MS-DOS

### See also

MIDASconfig, MIDASsaveConfig

## 2.3.7 MIDASsaveConfig

    BOOL MIDASsaveConfig(char *fileName)

Saves the MIDAS setup to a file.

### Input

fileName
  Setup file name

### Description

This function saves the MIDAS setup entered with MIDASconfig to a file on disk. It can be then loaded with MIDASloadConfig.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

MS-DOS

### See also

MIDASconfig, MIDASloadConfig

## 2.3.8 MIDASsetOption

    BOOL MIDASsetOption(int option, DWORD 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.9 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

Next: 3 System control Up: 2 Configurationinitialization and Previous: 6.2 Data types