Programmable tone generator

Collaboration diagram for Programmable tone generator:

Modules
	Programmable tone detector
	More information on the libvpb programmable tone detector is available here.

Classes
struct	VPB_TONE
	Tone definition structure. More...

Enumerations
enum	VPB_TONE_ID {   VPB_TONE_DIAL , VPB_TONE_RINGING , VPB_TONE_BUSY , VPB_TONE_CONGESTION ,   VPB_TONE_UNOBTAINABLE , VPB_TONE_CALLWAITING , VPB_TONE_STUTTERDIAL , VPB_TONE_ID_MAX }
	Symbolic identifiers for predefined, localised tones. More...

Tone generation
int WINAPI	vpb_playtone_async (int handle, const VPB_TONE &vpb_tone)
	Start a user defined tone playing and return immediately.
int WINAPI	vpb_playtone_async (int handle, const VPB_TONE *vpb_tone)
	Start a user defined tone playing and return immediately.
int WINAPI	vpb_playtone_async (int handle, VPB_TONE_ID tone_id)
	Start a locale specific predefined tone playing and return immediately.
int WINAPI	vpb_playtone_sync (int handle, const VPB_TONE &vpb_tone)
	Play a user defined tone, return when playback completes.
int WINAPI	vpb_playtone_sync (int handle, const VPB_TONE *vpb_tone)
	Play a user defined tone, return when playback completes.
int WINAPI	vpb_playtone_sync (int handle, VPB_TONE_ID tone_id)
	Play a locale specific predefined tone, return when playback completes.
int WINAPI	vpb_tone_terminate (int handle)
	Terminate a currently playing tone (user defined or dtmf).

Dial string aliases
int WINAPI	vpb_settone (char ident, const VPB_TONE *tone)
	Enables user to (re)define the tone associated with a dial string character.
int WINAPI	vpb_gettone (char ident, VPB_TONE *tone)
	Get the parameters of the tone represented in dial strings by ident.
int WINAPI	vpb_playtone_state (int handle)
	Returns state of play tone (1= playing, 0 = not playing)

Detailed Description

Todo:

Add appropriate bits of the sgml documentation here.

Enumeration Type Documentation

VPB_TONE_ID

enum VPB_TONE_ID

Symbolic identifiers for predefined, localised tones.

Enumerator
VPB_TONE_DIAL	Normal dial tone.
VPB_TONE_RINGING	Normal ringing tone.
VPB_TONE_BUSY	Called number busy tone.
VPB_TONE_CONGESTION	Network congestion tone.
VPB_TONE_UNOBTAINABLE	Invalid number signal.
VPB_TONE_CALLWAITING	Call waiting signal.
VPB_TONE_STUTTERDIAL	Voicemail pending signal.
VPB_TONE_ID_MAX	Indicates the number of defined tone id's.

Function Documentation

vpb_gettone()

int WINAPI vpb_gettone	(	char	ident,
		VPB_TONE *	tone
	)

Get the parameters of the tone represented in dial strings by ident.

Parameters

ident	The dial string character to retrieve tone data for.
tone	The returned VPB_TONE parameters for ident.

Returns

VPB_OK if all went well.

Exceptions

various

exceptions may be thrown in the event of error.

vpb_playtone_state()

int WINAPI vpb_playtone_state

(

int

handle

)

Returns state of play tone (1= playing, 0 = not playing)

Warning

It is dangerous to rely on the value returned by this method except as an unreliable hint, the state of the tone generator may have already changed again by the time it returns. Any following code should be well behaved whatever the state of the tone generator really is.

Deprecated:

This method may be removed in future releases.

References IDLE, VPBREG::toneg, vpb_c, and Comm::vpbreg().

vpb_settone()

int WINAPI vpb_settone	(	char	ident,
		const VPB_TONE *	tone
	)

Enables user to (re)define the tone associated with a dial string character.

Parameters

ident	The dial string character to use for this tone.
tone	The VPB_TONE structure that defines this tone.

Any occurrence of ident in a dial string sent via vpb_dial_sync() or similar functions will subsequently use the tone defined here.

Returns

VPB_OK if all went well.

Exceptions

various

exceptions may be thrown in the event of error.

Note

This must be called after vpb_open() if you wish to redefine the default tones, else your settings for those will be overwritten.

References VPB_TONE::freq1, VPB_TONE::freq2, VPB_TONE::freq3, VPB_TONE::level1, VPB_TONE::level2, and VPB_TONE::level3.

vpb_tone_terminate()

int WINAPI vpb_tone_terminate

(

int

handle

)

Terminate a currently playing tone (user defined or dtmf).

Parameters

handle

The handle of the port to stop tone playback for.

Returns

VPB_OK if all went well.

Exceptions

various

exceptions may be thrown if things go badly.

Note

No completion notification will be sent for tones that are explicitly terminated using this function.

References Stop(), VPBREG::toneg, vpb_c, and Comm::vpbreg().

Referenced by vpb_reset().