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

# 7.3 Functions

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

## 2.3.1 MIDASclose

    BOOL MIDASclose(void)

Uninitializes MIDAS Digital Audio System.

### Input

None.

### Description

This function uninitializes all MIDAS Digital Audio 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 Digital Audio System configuration. It queries the sound card to use and desired sound quality and output mode from the user. The setup entered can be saved do disk with MIDASsaveConfig and loaded back with MIDASloadConfig, or written to registry with MIDASwriteConfigRegistry and read back with MIDASreadConfigRegistry. 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 clicking Cancel, 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 cancelled the setup.

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

### Return value

TRUE if successful, FALSE if not (the user cancelled the configuration, or an error occurred)

### Operating systems

MS-DOS, Win32

### See also

MIDASsaveConfig, MIDASloadConfig, MIDASsetOption, MIDASgetOption, MIDASinit, MIDASwriteConfigRegistry, MIDASreadConfigRegistry

## 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 MIDASgetOption

    DWORD MIDASgetOption(int option)

Gets a MIDAS option.

### Input

option
  Option number (see `enum` MIDASoptions above)

### Description

This function reads the current value of a MIDAS option. The different number codes for different options are described above.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption

## 2.3.6 MIDASinit

    BOOL MIDASinit(void)

Initializes MIDAS Digital Audio System.

### Input

None.

### Description

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

If this function fails with no apparent reason, it is very probable that some other application is using the sound card hardware or the user has badly mis-configured MIDAS. Therefore, if this function fails, it is recommended to give the user a possibility to close other applications and retry, continue with no sound (set option MIDAS_OPTION_FORCE_NO_SOUND), or possibly re-configure MIDAS.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption, MIDASclose

## 2.3.7 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, Win32

### See also

MIDASconfig, MIDASsaveConfig

## 2.3.8 MIDASreadConfigRegistry

    BOOL MIDASreadConfigRegistry(DWORD key, char *subKey);

Reads MIDAS configuration from a registry key.

### Input

key
  A currently open registry key, for example H_KEY_CURRENT_USER
subKey
  The name of the subkey of key that contains the configuration

### Description

This function reads the MIDAS configuration from a registry key. The configuration must have been written there with MIDASwriteConfigRegistry. MIDASsetOption can be used afterwards to chance, for example, the output mode, and MIDASconfig to prompt the user for new settings.

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

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32

### See also

MIDASconfig, MIDASwriteConfigRegistry

## 2.3.9 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, Win32

### See also

MIDASconfig, MIDASloadConfig

## 2.3.10 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.11 MIDASstartup

    BOOL MIDASstartup(void)

Prepares MIDAS Digital Audio System for initialization and use.

### Input

None.

### Description

This function sets all MIDAS Digital Audio System 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, or call MIDASconfig to prompt the user for configuration options.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASsetOption, MIDASinit, MIDASclose

## 2.3.12 MIDASwriteConfigRegistry

    BOOL MIDASwriteConfigRegistry(DWORD key, char *subKey);

Writes the MIDAS configuration to a registry key.

### Input

key
  A currently open registry key, for example H_KEY_CURRENT_USER
subKey
  The name of the subkey of key where the configuration will be written. They key does not need to exist.

### Description

This function saves the current MIDAS configuration, usually entered with MIDASconfig to a registry key. The configuration can then be read with MIDASreadConfigRegistry.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

Win32

### See also

MIDASconfig, MIDASreadConfigRegistry

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