dtmf.h File Reference

Go to the source code of this file.

Classes

struct dtmf_tx_state_t

struct dtmf_rx_state_t

Defines

#define _SPANDSP_DTMF_H_

#define MAX_DTMF_DIGITS 128

Typedefs

typedef void(* digits_rx_callback_t )(void *user_data, const char *digits, int len)

Functions

int dtmf_tx (dtmf_tx_state_t *s, int16_t amp[], int max_samples)

Generate a buffer of DTMF tones.

size_t dtmf_tx_put (dtmf_tx_state_t *s, const char *digits, int len)

Put a string of digits in a DTMF generator's input buffer.

void dtmf_tx_set_level (dtmf_tx_state_t *s, int level, int twist)

Change the transmit level for a DTMF tone generator context.

void dtmf_tx_set_timing (dtmf_tx_state_t *s, int on_time, int off_time)

Change the transmit on and off time for a DTMF tone generator context.

dtmf_tx_state_t * dtmf_tx_init (dtmf_tx_state_t *s)

Initialise a DTMF tone generator context.

int dtmf_tx_free (dtmf_tx_state_t *s)

Free a DTMF tone generator context.

void dtmf_rx_set_realtime_callback (dtmf_rx_state_t *s, tone_report_func_t callback, void *user_data)

Set a realtime callback for a DTMF receiver context.

void dtmf_rx_parms (dtmf_rx_state_t *s, int filter_dialtone, int twist, int reverse_twist, int threshold)

Adjust a DTMF receiver context.

int dtmf_rx (dtmf_rx_state_t *s, const int16_t amp[], int samples)

Process a block of received DTMF audio samples.

int dtmf_rx_status (dtmf_rx_state_t *s)

Get the status of DTMF detection during processing of the last audio chunk.

size_t dtmf_rx_get (dtmf_rx_state_t *s, char *digits, int max)

Get a string of digits from a DTMF receiver's output buffer.

dtmf_rx_state_t * dtmf_rx_init (dtmf_rx_state_t *s, digits_rx_callback_t callback, void *user_data)

Initialise a DTMF receiver context.

int dtmf_rx_free (dtmf_rx_state_t *s)

Free a DTMF receiver context.

Detailed Description

Function Documentation

int dtmf_rx	(	dtmf_rx_state_t *	s,
		const int16_t	amp[],
		int	samples
	)

Process a block of received DTMF audio samples.

Parameters:

	s	The DTMF receiver context.
	amp	The audio sample buffer.
	samples	The number of samples in the buffer.

Returns:: The number of samples unprocessed.

References dtmf_rx_state_t::col_out, dtmf_rx_state_t::current_digits, dtmf_rx_state_t::current_sample, dtmf_rx_state_t::digits, dtmf_rx_state_t::digits_callback, dtmf_rx_state_t::digits_callback_data, dtmf_rx_state_t::energy, dtmf_rx_state_t::filter_dialtone, goertzel_result(), dtmf_rx_state_t::in_digit, dtmf_rx_state_t::last_hit, dtmf_rx_state_t::lost_digits, dtmf_rx_state_t::normal_twist, dtmf_rx_state_t::realtime_callback, dtmf_rx_state_t::realtime_callback_data, dtmf_rx_state_t::reverse_twist, dtmf_rx_state_t::row_out, dtmf_rx_state_t::threshold, dtmf_rx_state_t::z350, and dtmf_rx_state_t::z440.

int dtmf_rx_free ( dtmf_rx_state_t * s )

Free a DTMF receiver context.

Parameters:

s

The DTMF receiver context.

Returns:: 0 for OK, else -1.

size_t dtmf_rx_get	(	dtmf_rx_state_t *	s,
		char *	digits,
		int	max
	)

Get a string of digits from a DTMF receiver's output buffer.

Parameters:

	s	The DTMF receiver context.
	digits	The buffer for the received digits.
	max	The maximum number of digits to be returned,

Returns:: The number of digits actually returned.

References dtmf_rx_state_t::current_digits, and dtmf_rx_state_t::digits.

dtmf_rx_state_t* dtmf_rx_init	(	dtmf_rx_state_t *	s,
		digits_rx_callback_t	callback,
		void *	user_data
	)

Initialise a DTMF receiver context.

Parameters:

	s	The DTMF receiver context.
	callback	An optional callback routine, used to report received digits. If no callback routine is set, digits may be collected, using the dtmf_rx_get() function.
	user_data	An opaque pointer which is associated with the context, and supplied in callbacks.

Returns:: A pointer to the DTMF receiver context.

References dtmf_rx_state_t::col_out, dtmf_rx_state_t::current_digits, dtmf_rx_state_t::current_sample, dtmf_rx_state_t::digits, dtmf_rx_state_t::digits_callback, dtmf_rx_state_t::digits_callback_data, dtmf_rx_state_t::energy, dtmf_rx_state_t::filter_dialtone, goertzel_init(), dtmf_rx_state_t::in_digit, dtmf_rx_state_t::last_hit, dtmf_rx_state_t::lost_digits, make_goertzel_descriptor(), dtmf_rx_state_t::normal_twist, dtmf_rx_state_t::realtime_callback, dtmf_rx_state_t::realtime_callback_data, dtmf_rx_state_t::reverse_twist, dtmf_rx_state_t::row_out, and dtmf_rx_state_t::threshold.

void dtmf_rx_parms	(	dtmf_rx_state_t *	s,
		int	filter_dialtone,
		int	twist,
		int	reverse_twist,
		int	threshold
	)

Adjust a DTMF receiver context.

Parameters:

	s	The DTMF receiver context.
	filter_dialtone	TRUE to enable filtering of dialtone, FALSE to disable, < 0 to leave unchanged.
	twist	Acceptable twist, in dB. < 0 to leave unchanged.
	reverse_twist	Acceptable reverse twist, in dB. < 0 to leave unchanged.
	threshold	The minimum acceptable tone level for detection, in dBm0. <= -99 to leave unchanged.

References dtmf_rx_state_t::filter_dialtone, dtmf_rx_state_t::normal_twist, dtmf_rx_state_t::reverse_twist, dtmf_rx_state_t::threshold, dtmf_rx_state_t::z350, and dtmf_rx_state_t::z440.

void dtmf_rx_set_realtime_callback	(	dtmf_rx_state_t *	s,
		tone_report_func_t	callback,
		void *	user_data
	)

Set a realtime callback for a DTMF receiver context.

Set a optional realtime callback for a DTMF receiver context. This function is called immediately a confirmed state change occurs in the received DTMF. It is called with the ASCII value for a DTMF tone pair, or zero to indicate no tone is being received.

Parameters:

	s	The DTMF receiver context.
	callback	Callback routine used to report the start and end of digits.
	user_data	An opaque pointer which is associated with the context, and supplied in callbacks.

References dtmf_rx_state_t::realtime_callback, and dtmf_rx_state_t::realtime_callback_data.

int dtmf_rx_status ( dtmf_rx_state_t * s )

Get the status of DTMF detection during processing of the last audio chunk.

Parameters:

s

The DTMF receiver context.

Returns:: The current digit status. Either 'x' for a "maybe" condition, or the digit being detected.

References dtmf_rx_state_t::in_digit, and dtmf_rx_state_t::last_hit.

int dtmf_tx	(	dtmf_tx_state_t *	s,
		int16_t	amp[],
		int	max_samples
	)

Generate a buffer of DTMF tones.

Parameters:

	s	The DTMF generator context.
	amp	The buffer for the generated signal.
	max_samples	The required number of generated samples.

Returns:: The number of samples actually generated. This may be less than max_samples if the input buffer empties.

References tone_gen_state_t::current_section, tone_gen_state_t::duration, dtmf_tx_state_t::high_level, dtmf_tx_state_t::low_level, dtmf_tx_state_t::off_time, dtmf_tx_state_t::on_time, dtmf_tx_state_t::queue, queue_read_byte(), tone_gen_state_t::tone, and dtmf_tx_state_t::tones.

int dtmf_tx_free ( dtmf_tx_state_t * s )

Free a DTMF tone generator context.

Parameters:

s

The DTMF tone generator context.

Returns:: 0 for OK, else -1.

dtmf_tx_state_t* dtmf_tx_init ( dtmf_tx_state_t * s )

Initialise a DTMF tone generator context.

Parameters:

s

The DTMF generator context.

Returns:: A pointer to the DTMF generator context.

References tone_gen_state_t::current_section, dtmf_tx_state_t::queue, queue_init(), QUEUE_READ_ATOMIC, QUEUE_WRITE_ATOMIC, and dtmf_tx_state_t::tones.

size_t dtmf_tx_put	(	dtmf_tx_state_t *	s,
		const char *	digits,
		int	len
	)

Put a string of digits in a DTMF generator's input buffer.

Parameters:

	s	The DTMF generator context.
	digits	The string of digits to be added.
	len	The length of the string of digits. If negative, the string is assumed to be a NULL terminated string.

Returns:: The number of digits actually added. This may be less than the length of the digit string, if the buffer fills up.

References dtmf_tx_state_t::queue, queue_free_space(), and queue_write().

void dtmf_tx_set_level	(	dtmf_tx_state_t *	s,
		int	level,
		int	twist
	)

Change the transmit level for a DTMF tone generator context.

Parameters:

	s	The DTMF generator context.
	level	The level of the low tone, in dBm0.
	twist	The twist, in dB.

References dds_scaling_dbm0f(), dtmf_tx_state_t::high_level, and dtmf_tx_state_t::low_level.

void dtmf_tx_set_timing	(	dtmf_tx_state_t *	s,
		int	on_time,
		int	off_time
	)

Change the transmit on and off time for a DTMF tone generator context.

Parameters:

	s	The DTMF generator context.
	on-time	The on time, in ms.
	off_time	The off time, in ms.

References dtmf_tx_state_t::off_time, and dtmf_tx_state_t::on_time.


Classes
struct	dtmf_tx_state_t
struct	dtmf_rx_state_t
Defines
#define	_SPANDSP_DTMF_H_
#define	MAX_DTMF_DIGITS 128
Typedefs
typedef void(*	digits_rx_callback_t )(void user_data, const char digits, int len)
Functions
int	dtmf_tx (dtmf_tx_state_t *s, int16_t amp[], int max_samples)
	Generate a buffer of DTMF tones.
size_t	dtmf_tx_put (dtmf_tx_state_t s, const char digits, int len)
	Put a string of digits in a DTMF generator's input buffer.
void	dtmf_tx_set_level (dtmf_tx_state_t *s, int level, int twist)
	Change the transmit level for a DTMF tone generator context.
void	dtmf_tx_set_timing (dtmf_tx_state_t *s, int on_time, int off_time)
	Change the transmit on and off time for a DTMF tone generator context.
dtmf_tx_state_t *	dtmf_tx_init (dtmf_tx_state_t *s)
	Initialise a DTMF tone generator context.
int	dtmf_tx_free (dtmf_tx_state_t *s)
	Free a DTMF tone generator context.
void	dtmf_rx_set_realtime_callback (dtmf_rx_state_t s, tone_report_func_t callback, void user_data)
	Set a realtime callback for a DTMF receiver context.
void	dtmf_rx_parms (dtmf_rx_state_t *s, int filter_dialtone, int twist, int reverse_twist, int threshold)
	Adjust a DTMF receiver context.
int	dtmf_rx (dtmf_rx_state_t *s, const int16_t amp[], int samples)
	Process a block of received DTMF audio samples.
int	dtmf_rx_status (dtmf_rx_state_t *s)
	Get the status of DTMF detection during processing of the last audio chunk.
size_t	dtmf_rx_get (dtmf_rx_state_t s, char digits, int max)
	Get a string of digits from a DTMF receiver's output buffer.
dtmf_rx_state_t *	dtmf_rx_init (dtmf_rx_state_t s, digits_rx_callback_t callback, void user_data)
	Initialise a DTMF receiver context.
int	dtmf_rx_free (dtmf_rx_state_t *s)
	Free a DTMF receiver context.