| BOOL PlaySound(lpszName, hModule, dwFlags) | |||
| LPSTR lpszName; | |||
| HANDLE hModule; | |||
| DWORD dwFlags; |
The PlaySound function plays a waveform sound.
The function can play wave resources from a module, or wave files named explicitly or via an alias in the [sounds] section of the WIN.INI file.
lpszName
A pointer to the name of the resource, file, or alias of the sound to be played.
hModule
If lpszName is the name of a resource, this parameter supplies the handle of the module from which the resource is to be loaded.
dwFlags
Specifies the nature of lpszName and how the sound should be played.
| Value | Meaning |
| SND_ALIAS | ||
| The lpszName parameter is an entry in the [sounds] section of WIN.INI of the form: alias=pathname. May not be used with either SND_FILENAME or SND_RESOURCE. | ||
| SND_FILENAME | ||
| The lpszName parameter is the name of a wave file. May not be used with either SND_ALIAS or SND_RESOURCE. | ||
| SND_RESOURCE | ||
| The lpszName parameter is the name of a resource. May not be used with either SND_ALIAS or SND_FILENAME. | ||
| SND_ASYNC | ||
| Specifies that the sound should be played asynchronously. The call to PlaySound will return as soon as the sound is started. May not be used with SND_SYNC. | ||
| SND_SYNC | ||
| Specifies that the sound should be played synchronously. The call to PlaySound will not return until the sound has completed playing. May not be used with SND_ASYNC. | ||
| SND_NODEFAULT | ||
| This flag may be used in conjunction with the SND_ALIAS flag to prevent the default system sound being played if the alias supplied by the lpszName parameter cannot be found. | ||
| SND_NOWAIT | ||
| When this flag is set, the call to PlaySound will fail if no suitable wave device is available to play the sound. | ||
If the function is successful, the return value is TRUE.
If the function fails, the return value is FALSE. More detailed information can be obtained by calling the GetLastError function.
Note that if the SND_ASYNC flag is set, a return value of TRUE indicates only that the thread has started which will attempt to play the sound. There is no indication that the sound will actually be played.
The PlaySound function provides a simple mechanism to play wave files and wave files built into an application as resources of type WAVE. To add a wave file to an application, the resource file should have an entry of this form:
SoundName WAVE ding.wav
The resource can then be played by calling:
PlaySound("SoundName", hModule, SND_RESOURCE);
Note that for all cases, the application must have enough memory quota to map the entire file into memory. This limits the file size which can be played to about 250 k bytes.
When playing an alias name from WIN.INI, the default action is to search for the given name, and, if it is not found, to search for the SystemDefault entry and play that sound. If the application does not want the default sound to be played, it should set the SND_NODEFAULT flag.