chiark - git - mdw - jog/blob - PlaySound.txt

   1 PlaySound
   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