The sndPlaySound function has the following syntax:
BOOL sndPlaySound(lpszSoundName, wFlags)
The parameter lpszSoundName is an LPCSTR and points to a null-terminated string containing the name of the sound to be played. This name can be a keyname in the [sounds] section of the WIN.INI file or it can be the filename of a WAVE file. Optionally, lpszSoundName can be a far pointer to an in-memory image of a WAVE file, which can be Clipboard data in CF_WAVE format or a resource that has been loaded into memory. See “Playing WAVE Resources,” later in this section, for details on using in-memory WAVE file images.
The wFlags parameter specifies optional flags that affect how the sound is played. If the SND_SYNC flag is specified, the sound is played synchronously— sndPlaySound doesn't return until playback is complete. If the SND_ASYNC flag is specified, the sound is played asynchronously—sndPlaySound returns as soon as the sound begins playing. If neither of these flags is specified, the sound is played synchronously.
As an example, the following statement plays the C:\SOUNDS\BELLS.WAV file:
sndPlaySound("C:\\SOUNDS\\BELLS.WAV", SND_SYNC);
If the specified file does not exist, or will not fit into the available physical memory, sndPlaySound plays the default system sound specified by the SystemDefault entry in the [sounds] section of the WIN.INI file. If there is no SystemDefault entry, sndPlaySound fails without producing any sound. If you don't want the default system sound to play, specify the SND_NODEFAULT flag, as shown in the following example:
sndPlaySound("C:\\SOUNDS\\BELLS.WAV", SND_SYNC | SND_NODEFAULT);
If you specify the SND_LOOP and SND_ASYNC flags for the wFlags parameter, the sound will continue to play repeatedly; for example:
sndPlaySound("C:\\SOUNDS\\BELLS.WAV", SND_LOOP | SND_ASYNC);
If you want to loop a sound, you must play it asynchronously. You cannot use the SND_SYNC flag with the SND_LOOP flag. A looped sound will continue to play until sndPlaySound is called to play another sound. To stop playing a sound (looped or asynchronous) without playing another sound, use the following statement:
sndPlaySound(NULL, 0);
You can also build WAVE files into an application as resources and use sndPlaySound to play these sounds by specifying the SND_MEMORY flag. The SND_MEMORY flag indicates the lpszSoundName parameter is a pointer to an in-memory image of the WAVE file. To include a WAVE file as a resource in an application, add the following entry to the application's resource script (.RC) file:
soundName WAVE c:\sounds\bells.wav
The name “soundName” is a placeholder for a name that you create to refer to this WAVE resource. WAVE resources are loaded and accessed just like other user- defined Windows resources. The function in the following example plays a specified WAVE resource.
/* Plays a specified WAVE resource */
BOOL PlayResource(LPSTR lpName)
{
HANDLE hResInfo, hRes;
LPSTR lpRes;
BOOL bRtn;
/* Find the WAVE resource */
hResInfo = FindResource(hInst, lpName, "WAVE");
if (!hResInfo) return FALSE;
/* Load the WAVE resource */
hRes = LoadResource(hInst, hResInfo);
if (!hRes) return FALSE;
/* Lock the WAVE resource and play it */
lpRes = LockResource(hRes);
if (lpRes) {
bRtn = sndPlaySound(lpRes, SND_MEMORY | SND_SYNC |
SND_NODEFAULT);
UnlockResource(hRes);
}
else
bRtn = 0;
/* Free the WAVE resource and return success or failure */
FreeResource(hRes);
return bRtn;
}
To play a WAVE resource using this function, pass the function a far pointer to a string containing the name of the resource, as shown in the following example:
PlayResource("soundName");
The sndPlaySound function will also play waveform sounds referred to by a key-name in the [sounds] section of WIN.INI. This allows users to assign their own sounds to system alerts and warnings, or to user actions, such as a mouse button click. For example, the [sounds] section of WIN.INI might look like this:
[sounds]
SystemDefault=C:\SOUNDS\BUMMER.WAV, Says BUMMER
SystemAsterisk=C:\SOUNDS\WHALES.WAV, Whale sounds
SystemExclamation=C:\SOUNDS\LASER.WAV, Laser gun sounds
SystemHand=C:\SOUNDS\OHOH.WAV, Says OH-OH
SystemQuestion=C:\SOUNDS\JIBERISH.WAV, Person mumbling
SystemStart=C:\SOUNDS\CHORD.WAV, Plays a chord
MouseClick=C:\SOUNDS\CLICK.WAV, Recording of a clicking sound
To play a sound identified by a WIN.INI entry, call sndPlaySound with the lpszSoundName parameter pointing to a string containing the name of the entry that identifies the sound. For example, to play the sound associated with the “MouseClick” entry in the [sounds] section of WIN.INI, and wait for the sound to complete before returning, use the following statement:
sndPlaySound("MouseClick", SND_SYNC);
If the specified WIN.INI entry or the waveform file it identifies does not exist, or if the sound will not fit into the available physical memory, sndPlaySound plays the default system sound specified by the SystemDefault entry. If there is no SystemDefault entry, sndPlaySound fails without producing any sound. If you don't want the default system sound to play, specify the SND_NODEFAULT flag when you call sndPlaySound, as in the following example:
sndPlaySound("MouseClick", SND_SYNC | SND_NODEFAULT);
Note:
The sndPlaySound function always searches the [sounds] section of WIN.INI for a keyname matching lpszSoundName before attempting to load a file with this name. The [sounds] section of WIN.INI includes an optional string following the waveform filename for descriptive text about the sound in the file. This descriptive text is displayed in the Sound Option from the Control Panel.