Generates audio beeps and clicks of varying frequencies, durations, and volume levels.
HRESULT ITCAudioPlayTone(
DWORD nPitch,
DWORD nDuration,
DWORD nVolume
);
nPitch
[in] Frequency of the tone in cycles per second (Hertz). Although the computer can generate pitches in a wide frequency range, tones in the range 200 to 1600 Hz suffice for most applications. Use the helper functions ITC GetTonePitchMin and ITC GetTonePitchMax (described below in Helper Functions) to verify the available frequency range for a computer.
nDuration
[in] Duration of tone in milliseconds (ms). Use ITC GetToneDurationMin and ITC GetToneDurationMax (described below in Helper Functions) to verify the available range of durations for a specific computer. For longer durations, play multiple tones in succession.
nVolume
[in] Volume of the tone. Range is 0 to 4.
A value of 0 equals "no volume." You can use 0 to generate silent pauses between tones.
nVolume settings apply only to generated tones and have no effect on the computer's current volume setting. You can also apply the computer's currently configured volume setting to a tone by specifying ITC_TONE_VOLUME_CURRENT for nVolume.
Helper functions such as ITC GetToneVolumeNormal and ITC GetToneVolumeVeryLoud (described below in Helper Functions) may also be used to specify the volume in place of a literal numeric value.
ITC_SUCCESS
Success.
ITC_ERROR
Failure.
ITC_ERROR_FUNCTION_NOT_SUPPORTED
ITCAudioPlayTone is not supported by this computer. Use ITCIsAudioToneSupported to query this status.
If an argument is passed-in that falls outside of the range defined for that particular parameter, the min or max value (whichever applies) will be used instead, but no error code will be returned. To access min and max ranges for each parameter, use the helper functions described in the next section.
Tones are played in a synchronous or blocking manner. This means, for instance, that a 500 ms tone blocks the calling thread for half a second while the tone is being generated. This approach simplifies the use of back-to-back tone sequences, since two or more overlapping tones cannot be played simultaneously. If non-blocking behavior is desired in order to meet application performance goals, call ITCAudioPlayTone from a thread other than the application's main work thread.
These helper functions are provided to return computer-specific pitch, duration, and volume values that can be passed into ITCAudioPlayTone:
DWORD ITC_GetTonePitchMin(void) ; DWORD ITC_GetTonePitchMax(void) ; DWORD ITC_GetTonePitchClick(void) ; DWORD ITC_GetTonePitchLow(void) ; DWORD ITC_GetTonePitchVeryLow(void) ; DWORD ITC_GetTonePitchHigh(void) ; DWORD ITC_GetTonePitchVeryHigh(void) ; DWORD ITC_GetToneDurationMin(void) ; DWORD ITC_GetToneDurationMax(void) ; DWORD ITC_GetToneDurationClick(void) ; DWORD ITC_GetToneDurationBeep(void) ; DWORD ITC_GetToneVolumeMin(void) ; DWORD ITC_GetToneVolumeMax(void) ; DWORD ITC_GetToneVolumeOff(void) ; DWORD ITC_GetToneVolumeLow(void) ; DWORD ITC_GetToneVolumeNormal(void) ; DWORD ITC_GetToneVolumeLoud(void) ; DWORD ITC_GetToneVolumeVeryLoud(void);