Miles Sound System SDK 7.2a

AIL_digital_handle_reacquire

The function AIL_digital_handle_reacquire attempts to reacquire hardware digital handle (either the HWAVEOUT handle, the DirectSound object, or the Sound Manager buffer) from the system.

S32 AIL_digital_handle_reacquire(
  HDIGDRIVER dig
);

In Parameters

dig: indicates the driver to try to reacquire.

Returns

Non-zero on success. Zero if the digital handle was still in use by the system, or if a voice output filter (e.g., DirectSound3D or EAX) is in use.

Discussion

On Windows, this function is usually used with the AIL_digital_handle_release function in the WM_ACTIVATEAPP message processing code to allow other applications to play digital sound.

On MacOS, other applications can always still play audio - that is, Sound Manager can still be used by other applications when Miles is using it.

This function will automatically restart any samples that were playing when AIL_digital_handle_release was called.

Important! Note that this function can fail if the digital handle is still in use, and that there is a slight delay from when a digital handle is freed to when that handle becomes available again. So, if you place this call in your WM_ACTIVATEAPP message handling code, you will have to retry the reacquire periodically if the call fails.

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

This function is not supported under the MS-DOS, Xbox, Wii, Sony PS2 or Sony PS3 versions of MSS.

Under Windows, this function will fail, returning zero, if a per-voice hardware provider such as a DirectSound3D or EAX output filter is in use. Because the system can't guarantee that we'll be able to reassign hardware voices to all active HSAMPLEs, supporting automatic release/reacquire capability isn't practical when we're not doing the mixing ourselves. In general, we strongly recommend that your application maintain its own 'shadow' state for its playing HSAMPLEs. Use MSS to render your application's audio state -- not to store it. The examms.cpp demo program offers a useful illustration of this technique. It can shut down and reopen its HDIGDRIVER, restoring its complete playback state from application-owned structures without using AIL_digital_handle_release or AIL_digital_handle_reacquire at all.

Group: Digital Audio Services
Related Functions: AIL_digital_handle_reacquire, AIL_digital_handle_release, AIL_open_input
Related Basic Types: HDIGDRIVER, S32