infra: Clean up project setup
[jog] / PlaySound.txt
CommitLineData
341e3c74 1PlaySound
2
3 The PlaySound function plays a sound specified by the given filename,
4 resource, or system event. (A system event may be associated with a
5 sound in the registry or in the WIN.INI file.)
6
7 BOOL PlaySound(
8 LPCSTR pszSound,
9 HMODULE hmod,
10 DWORD fdwSound
11 );
12
13 Parameters
14
15 pszSound
16 A string that specifies the sound to play. If this parameter is
17 NULL, any currently playing waveform sound is stopped. To stop
18 a non-waveform sound, specify SND_PURGE in the fdwSound
19 parameter.
20
21 Three flags in fdwSound (SND_ALIAS, SND_FILENAME, and
22 SND_RESOURCE) determine whether the name is interpreted as an
23 alias for a system event, a filename, or a resource
24 identifier. If none of these flags are specified, PlaySound
25 searches the registry or the WIN.INI file for an association
26 with the specified sound name. If an association is found, the
27 sound event is played. If no association is found in the
28 registry, the name is interpreted as a filename.
29
30 hmod
31 Handle to the executable file that contains the resource to be
32 loaded. This parameter must be NULL unless SND_RESOURCE is
33 specified in fdwSound.
34
35 fdwSound
36 Flags for playing the sound. The following values are defined.
37
38 Value Meaning
39
40 SND_APPLICATION The sound is played using an
41 application- specific association.
42
43 SND_ALIAS The pszSound parameter is a system-event
44 alias in the registry or the WIN.INI
45 file. Do not use with either
46 SND_FILENAME or SND_RESOURCE.
47
48 SND_ALIAS_ID The pszSound parameter is a predefined
49 sound identifier.
50
51 SND_ASYNC The sound is played asynchronously and
52 PlaySound returns immediately after
53 beginning the sound. To terminate an
54 asynchronously played waveform sound,
55 call PlaySound with pszSound set to
56 NULL.
57
58 SND_FILENAME The pszSound parameter is a filename.
59
60 SND_LOOP The sound plays repeatedly until
61 PlaySound is called again with the
62 pszSound parameter set to NULL. You must
63 also specify the SND_ASYNC flag to
64 indicate an asynchronous sound event.
65
66 SND_MEMORY A sound event's file is loaded in
67 RAM. The parameter specified by pszSound
68 must point to an image of a sound in
69 memory.
70
71 SND_NODEFAULT No default sound event is used. If the
72 sound cannot be found, PlaySound returns
73 silently without playing the default
74 sound.
75
76 SND_NOSTOP The specified sound event will yield to
77 another sound event that is already
78 playing. If a sound cannot be played
79 because the resource needed to generate
80 that sound is busy playing another
81 sound, the function immediately returns
82 FALSE without playing the requested
83 sound.
84
85 If this flag is not specified, PlaySound
86 attempts to stop the currently playing
87 sound so that the device can be used to
88 play the new sound.
89
90 SND_NOWAIT If the driver is busy, return
91 immediately without playing the sound.
92
93 SND_PURGE Sounds are to be stopped for the calling
94 task. If pszSound is not NULL, all
95 instances of the specified sound are
96 stopped. If pszSound is NULL, all sounds
97 that are playing on behalf of the
98 calling task are stopped.
99
100 You must also specify the instance
101 handle to stop SND_RESOURCE events.
102
103 SND_RESOURCE The pszSound parameter is a resource
104 identifier; hmod must identify the
105 instance that contains the resource.
106
107 SND_SYNC Synchronous playback of a sound
108 event. PlaySound returns after the sound
109 event completes.
110
111
112 Return Values
113
114 Returns TRUE if successful or FALSE otherwise.
115
116 Remarks
117
118 The sound specified by pszSound must fit into available physical
119 memory and be playable by an installed waveform-audio device
120 driver. PlaySound searches the following directories for sound files:
121 the current directory; the Windows directory; the Windows system
122 directory; directories listed in the PATH environment variable; and
123 the list of directories mapped in a network. For more information
124 about the directory search order, see the documentation for the
125 OpenFile function.
126
127 If it cannot find the specified sound, PlaySound uses the default
128 system event sound entry instead. If the function can find neither
129 the system default entry nor the default sound, it makes no sound and
130 returns FALSE.
131
132 Windows 95/98/Me: PlaySoundW is supported by the Microsoft Layer for
133 Unicode. To use this, you must add certain files to your application,
134 as outlined in Microsoft Layer for Unicode on Windows 95/98/Me
135 Systems.
136
137 Requirements
138
139 Windows NT/2000/XP: Included in Windows NT 3.1 and later.
140 Windows 95/98/Me: Included in Windows 95 and later.
141 Header: Declared in Mmsystem.h; include Windows.h.
142 Library: Use Winmm.lib.
143 Unicode: Implemented as Unicode and ANSI versions on Windows
144 NT/2000/XP. Also supported by Microsoft Layer for Unicode.
145
146 See Also
147
148 Waveform Audio Overview, Waveform Functions