The WIN$PLAYSOUND routine lets you play a .WAV file on Microsoft Windows machines (wave-form sound). You can also play sounds that the user has assigned to system events in the control panel.
WIN$PLAYSOUND is supported and can be used by applications deployed in Acucorp's Thin Client environment.
CALL "WIN$PLAYSOUND" USING SOUND-NAME, SOUND-FLAGS GIVING SOUND-STATUS
|SOUND-NAME PIC X(n)||Identifies the sound to play. This is either the name of a registered system sound or the name of a .WAV file.|
|SOUND-FLAGS numeric parameter||One or more optional values added together. The SOUND-FLAG options are described below. The option names are contained in the COPY library acugui.def.|
|SOUND-STATUS signed numeric data item|| Indicates the status of the operation as follows:
WIN$PLAYSOUND causes the sound specified in SOUND-NAME to be played. If SOUND-NAME contains the name of a system event, the sound associated with that event is played (the association is made via the Windows Control Panel). Otherwise, WIN$PLAYSOUND assumes that SOUND-NAME contains the name of a .WAV audio file.
If SOUND-NAME does not correspond to a system event and the file cannot be found, the default system sound is played. The default sound is also played when there is not enough memory available to load the specified file. If a default sound is not available, the routine does nothing and returns 0 in SOUND-STATUS.
This routine searches for the specified .WAV file in the object libraries, the working directory, and then the directories specified in the PATH environment variable. You can add .WAV files to your object library by using the COPY RESOURCE statement or CBLUTIL utility program. Specifying a SOUND-NAME of spaces stops any sound that is currently playing.
System event names are implementation dependent. The Windows API documents that the following sounds are always available:
Other system sound events are defined in the registry under Windows 98. Use regedit to look in the registry location:
The naming conventions for system sound events is implementation dependent.
The following options can be specified in SOUND-FLAGS. To use them, add together the values of the options and assign them to SOUND-FLAGS. The optional values have level 78 names associated with them. These names are defined in acugui.def.
|SND-SYNC (value 0)||This option causes the program to pause while the sound is being played. WIN$PLAYSOUND will not return until the sound has finished.|
|SND-ASYNC (value 1)||This option causes the program to continue to run while the sound is playing. Note that you can halt a sound that is playing by passing a SOUND-NAME of spaces to a subsequent call to WIN$PLAYSOUND.|
|SND-LOOP (value 8)||To work, this option must be used with the SND-ASYNC option. This option causes the sound to play continuously, restarting from the beginning when the end is reached. The sound can be stopped by passing a SOUND-NAME of spaces on a subsequent call.|
|SND-NOSTOP (value 16)||Normally, any sound playing will be stopped when a new sound is specified. With NOSTOP, if a sound is already playing, it will continue to play and WIN$PLAYSOUND will return a SOUND-STATUS value of 0.|