Wav audio support

Collaboration diagram for Wav audio support:

Modules
	DTMF digit collection
	Caller id

Classes
struct	VPB_VLOG
	Additional data that may be included in a wav file. More...

Macros
#define	VPB_VLOG_CHUNK   0x4000
	May be added to the Wave file mode to include a VPB_VLOG chunk when recording.

Typedefs
typedef std::vector< const Country * >	Country::List
	Container type for a list of pointers to Country structures.

Functions
	VpbException::VpbException (const char *format,...) __attribute__((format(printf
	Construct an exception object with a printf format message string.
	VpbException::~VpbException () throw ()
	Destructor.
	VPB_CID::VPB_CID ()
	Default constructor.
void	VPB_CID::clear ()
	Clear all data members their initialisation state.

Variables
char	VPB_CARD_INFO::model [10]
	Model.
char	VPB_CARD_INFO::date [16]
	Manufacture Date.
char	VPB_CARD_INFO::rev [8]
	Revision.
char	VPB_CARD_INFO::sn [10]
	Serial Number.
VPB_EVT_TYPE	VPB_EVENT::type
	The event type.
int	VPB_EVENT::handle
	The handle of the port that generated the event.
int	VPB_EVENT::data
	Optional data.
unsigned long	VPB_EVENT::data1
	Optional long data.
int	VPB_EVENT::lenextra
	Support for user defined event data.
void *	VPB_EVENT::extra
	Support for user defined event data.
const char *	VPB_PLAY::term_digits
	A string of DTMF digits that can terminate playback.
const char *	VPB_RECORD::term_digits
	A string of DTMF digits that can terminate recording.
unsigned int	VPB_RECORD::time_out
	Max ms to record for. If 0, recording will not time out.
unsigned int	VPB_TONE_MAP::tone_id
unsigned int	VPB_TONE_MAP::call_id
unsigned int	VPB_TONE_MAP::terminate
unsigned int	VPB_CALL::dialtones
unsigned int	VPB_CALL::dialtone_timeout
unsigned int	VPB_CALL::ringback_timeout
unsigned int	VPB_CALL::inter_ringback_timeout
unsigned int	VPB_CALL::answer_timeout
VPB_TONE_MAP	VPB_CALL::tone_map [VPB_MAX_TONE_MAP]
unsigned short	VPB_TONE::freq1
	frequency of first tone in Hz
unsigned short	VPB_TONE::freq2
	frequency of second tone in Hz
unsigned short	VPB_TONE::freq3
	frequency of third tone in Hz
float	VPB_TONE::level1
	first tone level in dB, -inf to 0dB
float	VPB_TONE::level2
	second tone level in dB, -inf to 0dB
float	VPB_TONE::level3
	third tone level in dB, -inf to 0dB
unsigned long	VPB_TONE::ton
	on time in ms, if 0 tone is continuous
unsigned long	VPB_TONE::toff
	off time in ms
VPB_TONE *	VPB_TONE::next
	Pointer to the next tone in a sequence. More...
uint16_t	VPB_STRAN::type
	VPB_TIMER, VPB_RISING, or VPB_FALLING
uint16_t	VPB_STRAN::tfire
	timer mode only
uint16_t	VPB_STRAN::tmin
	minimum tone on/off time (non timer) in ms
uint16_t	VPB_STRAN::tmax
	maximum tone on/off time (non timer) in ms
uint16_t	VPB_DETECT::nstates
	number of cadence states
uint16_t	VPB_DETECT::tone_id
	unique ID number for this tone
uint16_t	VPB_DETECT::ntones
	number of tones (1 or 2)
uint16_t	VPB_DETECT::freq1
	freq of first tone (Hz)
uint16_t	VPB_DETECT::bandwidth1
	bandwidth of first tone (Hz)
uint16_t	VPB_DETECT::freq2
	freq of first tone (Hz)
uint16_t	VPB_DETECT::bandwidth2
	bandwidth of second tone (Hz)
int16_t	VPB_DETECT::minlevel1
	min amp of 1st tone ref 0dBm0
int16_t	VPB_DETECT::minlevel2
	min amp of 2nd tone ref 0dbm0
int16_t	VPB_DETECT::twist
	Allowable difference in tone powers. More...
int16_t	VPB_DETECT::snr
	min signal to noise ratio to accept tone
uint16_t	VPB_DETECT::glitch
	short transitions of glitch ms ignored
VPB_STRAN	VPB_DETECT::stran [VPB_MS]
	cadence state transition table
const char *	Country::name
	Country name.
int	Country::code
	Country code.
int	Country::ring_cadence
	Default ring cadence.
uint16_t	Country::flash_time
	Generated hook flash time in ms.
uint16_t	Country::flash_min
	Min valid hook flash time in ms.
uint16_t	Country::flash_max
	Max valid hook flash time in ms.
uint16_t	Country::lv_onhook
	On hook voltage threshhold in V.
uint16_t	Country::lv_offhook
	Off hook voltage threshhold in V.
uint16_t	Country::drop_time
	Generated loop drop time in ms.
uint16_t	Country::drop_min
	Min valid loop drop time in ms.
uint16_t	Country::drop_max
	Max valid loop drop time in ms.
double	Country::fsk_mark
	Coefficient for cid generation.
double	Country::fsk_space
	Coefficient for cid generation.
VPB_TONE *	Country::tone_gen
	Pointer to an array of VPB_TONE_ID_MAX tones.
float	VPB_VOX::onlevel
float	VPB_VOX::offlevel
unsigned short	VPB_VOX::runon
short	VPB_VLOG::channel
	Channel number.
char	VPB_VLOG::inout [4]
	Call Direction.
char	VPB_VLOG::statime [16]
	Record Start Time yyyymmddHHMMSS.
char	VPB_VLOG::endtime [16]
	Record End Time yyyymmddHHMMSS.
char	VPB_VLOG::filename [256]
	Original Filename.
char	VPB_VLOG::cidn [128]
	CID number ascii.
char	VPB_VLOG::cidt [128]
	CID TEXT ascii.
char	VPB_VLOG::term [64]
	Termination reason TEXT ascii.
const char *	VPB_DIGITS::term_digits
	A list of specific digits that may terminate collection.
unsigned short	VPB_DIGITS::max_digits
	The maximum number of digits to collect.
unsigned long	VPB_DIGITS::digit_time_out
	The maximum time in ms to wait for digits.
unsigned long	VPB_DIGITS::inter_digit_time_out
	The maximum time in ms to wait for further digits once collection begins.
CidCallType	VPB_CID::call_type
	Call type designator.
char	VPB_CID::cldn [19]
	Calling line directory number.
char	VPB_CID::ra_cldn [2]
	Reason for absence of cldn, O or P.
char	VPB_CID::cn [21]
	Caller name.
char	VPB_CID::ra_cn [2]
	Reason for absence of cn, O or P.
char	VPB_CID::cdn [19]
	Called directory number.
char	VPB_CID::date_time [9]
	Time of call.
int	VPB_CID::nmss
	Network message system status, (0-255 calls waiting)
char	VPB_CID::pres [256]
	Storage for presentation layer data.
char	VPB_CID_JP::raw [130]
int	VPB_CID_JP::raw_size
char	VPB_CID_JP::otn [21]
char	VPB_CID_JP::otnra [31]
char	VPB_CID_JP::otnexp [4]
char	VPB_CID_JP::cnd [21]
char	VPB_CID_JP::cndexp [4]
int	VPB_CALL_INFO::callingplan
int	VPB_CALL_INFO::callingpres
char	VPB_CALL_INFO::callingnum [256]
char	VPB_CALL_INFO::callingname [256]
char	VPB_CALL_INFO::callingsubaddr [256]
char	VPB_CALL_INFO::calledsubaddr [256]
char	VPB_CALL_INFO::callednum [256]
int	VPB_CALL_INFO::calledplan

Error summary
const char *	VpbException::what () const throw ()
	Return the message associated with the exception.

Wave file output
void WINAPI	vpb_wave_open_write (WFILE **wav, const std::string &filename, int mode)
	Open a RIFF wave file for writing. More...
int WINAPI	vpb_wave_write (WFILE *wav, const char *buf, long n)
	Write a block of audio samples to a RIFF wave file. More...
void WINAPI	vpb_wave_close_write (WFILE *wav)
	Close a RIFF wave file after writing. More...

Wave file input
void WINAPI	vpb_wave_open_read (WFILE **wav, const std::string &filename)
	Open a RIFF wave file for reading. More...
int WINAPI	vpb_wave_read (WFILE *wav, char *buf, unsigned long n)
	Read a block of audio samples from a RIFF wave file. More...
void WINAPI	vpb_wave_close_read (WFILE *wav)
	Close a RIFF wave file after reading. More...

Miscellaneous wave file operations
size_t	vpb_wave_get_size (WFILE *wav)
	Return the size of wave file data in bytes.
AudioCompress WINAPI	vpb_wave_get_mode (WFILE *wav)
	Return the compression mode of wav.
void WINAPI	vpb_wave_set_sample_rate (WFILE *wav, unsigned short rate)
	Change the sample rate of a wav file. More...
int WINAPI	vpb_wave_seek (WFILE *wav, long offset)
	Move the wave pointer to a specified location in the samples. More...

Wave file VLOG data
int WINAPI	vpb_wave_set_vlog (WFILE *wav, VPB_VLOG *buf)
	Set VPB_VLOG information for inclusion in a wave file. More...
int WINAPI	vpb_wave_get_vlog (WFILE *wav, VPB_VLOG *buf)
	Get VPB_VLOG information from a wave file. More...

Detailed Description

Todo:

Add appropriate bits of the sgml documentation here.

Function Documentation

vpb_wave_close_read()

void WINAPI vpb_wave_close_read

(

WFILE *

wav

)

Close a RIFF wave file after reading.

Parameters

wav	The pointer returned by a call to vpb_wave_open_read().

vpb_wave_close_write()

void WINAPI vpb_wave_close_write

(

WFILE *

wav

)

Close a RIFF wave file after writing.

Parameters

wav	The pointer returned by a call to vpb_wave_open_write().

vpb_wave_get_vlog()

int WINAPI vpb_wave_get_vlog	(	WFILE *	wav,
		VPB_VLOG *	buf
	)

Get VPB_VLOG information from a wave file.

Parameters

wav	The pointer returned by a call to vpb_wave_open_*
buf	A pointer to storage for the VPB_VLOG data.

Returns

VPB_OK if successful, else a non-zero error code.

vpb_wave_open_read()

void WINAPI vpb_wave_open_read	(	WFILE **	wav,
		const std::string &	filename
	)

Open a RIFF wave file for reading.

Parameters

wav	Pointer to a pointer where encoding state may be stored. This pointer should be passed to other vpb_wave_* functions that will operate on the opened file.
filename	The full path to the file to read.

Exceptions

various

exceptions may be thrown in the event of an error.

vpb_wave_open_write()

void WINAPI vpb_wave_open_write	(	WFILE **	wav,
		const std::string &	filename,
		int	mode
	)

Open a RIFF wave file for writing.

Parameters

wav	Pointer to a pointer where encoding state may be stored. This pointer should be passed to other vpb_wave_* functions that will operate on the opened file.
filename	The full path to the file to write.
mode	The AudioCompress mode to use for the file. It may optionally be or'd with VPB_VLOG_CHUNK to record additional data in the wav file headers.

Exceptions

various

exceptions may be thrown in the event of an error.

vpb_wave_read()

int WINAPI vpb_wave_read	(	WFILE *	wav,
		char *	buf,
		unsigned long	n
	)

Read a block of audio samples from a RIFF wave file.

Parameters

wav	The pointer returned by a call to vpb_wave_open_read().
buf	The buffer to store samples in.
n	The size of the buffer in bytes.

Returns

The number of bytes actually stored in buf.

vpb_wave_seek()

int WINAPI vpb_wave_seek	(	WFILE *	wav,
		long	offset
	)

Move the wave pointer to a specified location in the samples.

Parameters

wav	The pointer returned by a call to vpb_wave_open_*.
offset	The offset from the start of the audio samples.

Returns

VPB_OK if the operation succeeded. Otherwise -1 will be returned and errno will be set to indicate the error.

vpb_wave_set_sample_rate()

void WINAPI vpb_wave_set_sample_rate	(	WFILE *	wav,
		unsigned short	rate
	)

Change the sample rate of a wav file.

Parameters

wav	The pointer returned by a call to vpb_wave_open_*.
rate	The new sampling rate to use.

vpb_wave_set_vlog()

int WINAPI vpb_wave_set_vlog	(	WFILE *	wav,
		VPB_VLOG *	buf
	)

Set VPB_VLOG information for inclusion in a wave file.

Parameters

wav	The pointer returned by a call to vpb_wave_open_write().
buf	The VPB_VLOG data to include.

Returns

VPB_OK if successful, else a non-zero error code.

vpb_wave_write()

int WINAPI vpb_wave_write	(	WFILE *	wav,
		const char *	buf,
		long	n
	)

Write a block of audio samples to a RIFF wave file.

Parameters

wav	The pointer returned by a call to vpb_wave_open_write().
buf	The buffer of samples to write.
n	The number of bytes to write.

Returns

The number of bytes actually written.

Variable Documentation

next

VPB_TONE* VPB_TONE::next

Pointer to the next tone in a sequence.

For tone sequences this field should should point to the next tone definition in the sequence. It should be NULL for a single tone and for the last tone in a one-shot sequence of tones. As a special case for the last tone of a sequence, if this field points to the object that contains it then the whole sequence will be continuously repeated until explicitly terminated by the user application.

twist

int16_t VPB_DETECT::twist

Allowable difference in tone powers.

If (E1/E2 < twist) AND (E2/E1 < twist), the tone is OK.