Loading...
Searching...
No Matches
Programmable tone generator
Public API functions » Port initialisation » Card information » Port control » Event handling » Audio play and record » Error handling
Collaboration diagram for Programmable tone generator:

## Topics

| 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 ToneGen::IDLE, and vpb_c.

## 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 ToneGen::Stop(), and vpb_c.

Referenced by vpb_reset().