spandsp  0.0.6
fax.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * fax.h - definitions for analogue line ITU T.30 fax processing
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2005 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 /*! \file */
27 
28 #if !defined(_SPANDSP_FAX_H_)
29 #define _SPANDSP_FAX_H_
30 
31 /*! \page fax_page FAX over analogue modem handling
32 
33 \section fax_page_sec_1 What does it do?
34 
35 \section fax_page_sec_2 How does it work?
36 */
37 
38 typedef struct fax_state_s fax_state_t;
39 
40 #if defined(__cplusplus)
41 extern "C"
42 {
43 #endif
44 
45 /*! Apply T.30 receive processing to a block of audio samples.
46  \brief Apply T.30 receive processing to a block of audio samples.
47  \param s The FAX context.
48  \param amp The audio sample buffer.
49  \param len The number of samples in the buffer.
50  \return The number of samples unprocessed. This should only be non-zero if
51  the software has reached the end of the FAX call.
52 */
53 SPAN_DECLARE_NONSTD(int) fax_rx(fax_state_t *s, int16_t *amp, int len);
54 
55 /*! Apply fake T.30 receive processing when a block of audio samples is missing (e.g due
56  to packet loss).
57  \brief Apply fake T.30 receive processing.
58  \param s The FAX context.
59  \param len The number of samples to fake.
60  \return The number of samples unprocessed. This should only be non-zero if
61  the software has reached the end of the FAX call.
62 */
63 SPAN_DECLARE_NONSTD(int) fax_rx_fillin(fax_state_t *s, int len);
64 
65 /*! Apply T.30 transmit processing to generate a block of audio samples.
66  \brief Apply T.30 transmit processing to generate a block of audio samples.
67  \param s The FAX context.
68  \param amp The audio sample buffer.
69  \param max_len The number of samples to be generated.
70  \return The number of samples actually generated. This will be zero when
71  there is nothing to send.
72 */
73 SPAN_DECLARE_NONSTD(int) fax_tx(fax_state_t *s, int16_t *amp, int max_len);
74 
75 /*! Select whether silent audio will be sent when FAX transmit is idle.
76  \brief Select whether silent audio will be sent when FAX transmit is idle.
77  \param s The FAX context.
78  \param transmit_on_idle TRUE if silent audio should be output when the FAX transmitter is
79  idle. FALSE to transmit zero length audio when the FAX transmitter is idle. The default
80  behaviour is FALSE.
81 */
82 SPAN_DECLARE(void) fax_set_transmit_on_idle(fax_state_t *s, int transmit_on_idle);
83 
84 /*! Select whether talker echo protection tone will be sent for the image modems.
85  \brief Select whether TEP will be sent for the image modems.
86  \param s The FAX context.
87  \param use_tep TRUE if TEP should be sent.
88 */
89 SPAN_DECLARE(void) fax_set_tep_mode(fax_state_t *s, int use_tep);
90 
91 /*! Get a pointer to the T.30 engine associated with a FAX context.
92  \brief Get a pointer to the T.30 engine associated with a FAX context.
93  \param s The FAX context.
94  \return A pointer to the T.30 context, or NULL.
95 */
96 SPAN_DECLARE(t30_state_t *) fax_get_t30_state(fax_state_t *s);
97 
98 /*! Get a pointer to the logging context associated with a FAX context.
99  \brief Get a pointer to the logging context associated with a FAX context.
100  \param s The FAX context.
101  \return A pointer to the logging context, or NULL.
102 */
104 
105 /*! Restart a FAX context.
106  \brief Restart a FAX context.
107  \param s The FAX context.
108  \param calling_party TRUE if the context is for a calling party. FALSE if the
109  context is for an answering party.
110  \return 0 for OK, else -1. */
111 SPAN_DECLARE(int) fax_restart(fax_state_t *s, int calling_party);
112 
113 /*! Initialise a FAX context.
114  \brief Initialise a FAX context.
115  \param s The FAX context.
116  \param calling_party TRUE if the context is for a calling party. FALSE if the
117  context is for an answering party.
118  \return A pointer to the FAX context, or NULL if there was a problem.
119 */
120 SPAN_DECLARE(fax_state_t *) fax_init(fax_state_t *s, int calling_party);
121 
122 /*! Release a FAX context.
123  \brief Release a FAX context.
124  \param s The FAX context.
125  \return 0 for OK, else -1. */
126 SPAN_DECLARE(int) fax_release(fax_state_t *s);
127 
128 /*! Free a FAX context.
129  \brief Free a FAX context.
130  \param s The FAX context.
131  \return 0 for OK, else -1. */
132 SPAN_DECLARE(int) fax_free(fax_state_t *s);
133 
134 #if defined(__cplusplus)
135 }
136 #endif
137 
138 #endif
139 /*- End of file ------------------------------------------------------------*/
fax_get_logging_state
logging_state_t * fax_get_logging_state(fax_state_t *s)
Get a pointer to the logging context associated with a FAX context.
Definition: fax.c:597
MODEM_CONNECT_TONES_ANSAM_PR
@ MODEM_CONNECT_TONES_ANSAM_PR
The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM modulation,...
Definition: modem_connect_tones.h:72
v29_rx_signal_power
float v29_rx_signal_power(v29_rx_state_t *s)
Definition: v29rx.c:165
fax_get_t30_state
t30_state_t * fax_get_t30_state(fax_state_t *s)
Get a pointer to the T.30 engine associated with a FAX context.
Definition: fax.c:591
t4_tx.h
tone_generate.h
MODEM_CONNECT_TONES_FAX_CNG
@ MODEM_CONNECT_TONES_FAX_CNG
CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The bursts repeat for as...
Definition: modem_connect_tones.h:62
v17_rx_set_put_bit
void v17_rx_set_put_bit(v17_rx_state_t *s, put_bit_func_t put_bit, void *user_data)
Change the put_bit function associated with a V.17 modem receive context.
Definition: v17rx.c:1360
fax_state_s::logging
logging_state_t logging
V.8.
Definition: private/fax.h:46
modem_connect_tones.h
t30_front_end_status
void t30_front_end_status(void *user_data, int status)
Inform the T.30 engine of a status change in the front end (end of tx, rx signal change,...
Definition: t30.c:5833
v27ter_tx_set_get_bit
void v27ter_tx_set_get_bit(v27ter_tx_state_t *s, get_bit_func_t get_bit, void *user_data)
Change the get_bit function associated with a V.27ter modem transmit context.
Definition: v27ter_tx.c:368
T30_SUPPORT_V34HDX
@ T30_SUPPORT_V34HDX
Definition: t30.h:348
t30_logging.h
fax_modems_state_s::audio_tx_log
int audio_tx_log
Audio logging file handle for transmitted audio.
Definition: private/fax_modems.h:122
fax_set_transmit_on_idle
void fax_set_transmit_on_idle(fax_state_t *s, int transmit_on_idle)
Select whether silent audio will be sent when FAX transmit is idle.
Definition: fax.c:579
fax_modems_state_s::logging
logging_state_t logging
Error and flow logging control.
Definition: private/fax_modems.h:124
fax_init
fax_state_t * fax_init(fax_state_t *s, int calling_party)
Initialise a FAX context.
Definition: fax.c:664
fsk_rx_signal_power
float fsk_rx_signal_power(fsk_rx_state_t *s)
Definition: fsk.c:246
async.h
hdlc.h
t30.h
fax_modems_state_s::v27ter_rx
v27ter_rx_state_t v27ter_rx
A V.27ter modem context used when receiving FAXes at 2400bps or 4800bps.
Definition: private/fax_modems.h:74
t30_release
int t30_release(t30_state_t *s)
Release a T.30 context.
Definition: t30.c:6368
t4_rx.h
v17_tx_restart
int v17_tx_restart(v17_tx_state_t *s, int bit_rate, int tep, int short_train)
Reinitialise an existing V.17 modem transmit context.
Definition: v17tx.c:380
put_bit_func_t
void(* put_bit_func_t)(void *user_data, int bit)
Definition: async.h:105
fax_set_transmit_on_idle
void fax_set_transmit_on_idle(fax_state_t *s, int transmit_on_idle)
Select whether silent audio will be sent when FAX transmit is idle.
Definition: fax.c:579
v27ter_tx.h
fax_modems_state_s::rx_fillin_handler
span_rx_fillin_handler_t * rx_fillin_handler
The current receive missing signal fill-in handler.
Definition: private/fax_modems.h:100
v27ter_rx_set_put_bit
void v27ter_rx_set_put_bit(v27ter_rx_state_t *s, put_bit_func_t put_bit, void *user_data)
Change the put_bit function associated with a V.27ter modem receive context.
Definition: v27ter_rx.c:1016
MODEM_CONNECT_TONES_FAX_CED
#define MODEM_CONNECT_TONES_FAX_CED
FAX CED tone is the same as ANS tone.
Definition: modem_connect_tones.h:87
fax_modems_state_s::v29_tx
v29_tx_state_t v29_tx
A V.29 modem context used when sending FAXes at 7200bps or 9600bps.
Definition: private/fax_modems.h:65
t30.h
fax_modems_state_s::v27ter_tx
v27ter_tx_state_t v27ter_tx
A V.27ter modem context used when sending FAXes at 2400bps or 4800bps.
Definition: private/fax_modems.h:71
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(int) async_tx_get_bit(void *user_data)
Get the next bit of a transmitted serial bit stream.
v29_rx_set_put_bit
void v29_rx_set_put_bit(v29_rx_state_t *s, put_bit_func_t put_bit, void *user_data)
Change the put_bit function associated with a V.29 modem receive context.
Definition: v29rx.c:1052
fax_modems_state_s::v17_tx
v17_tx_state_t v17_tx
A V.17 modem context used when sending FAXes at 7200bps, 9600bps 12000bps or 14400bps.
Definition: private/fax_modems.h:59
timezone.h
v17rx.h
fax_restart
int fax_restart(fax_state_t *s, int calling_party)
Restart a FAX context.
Definition: fax.c:603
v27ter_rx_restart
int v27ter_rx_restart(v27ter_rx_state_t *s, int bit_rate, int old_train)
Reinitialise an existing V.27ter modem receive context.
Definition: v27ter_rx.c:1036
t30_timer_update
void t30_timer_update(t30_state_t *s, int samples)
Report the passage of time to the T.30 engine.
Definition: t30.c:6127
t30_api.h
complex.h
fax_modems_state_s::silence_gen
silence_gen_state_t silence_gen
Used to insert timed silences.
Definition: private/fax_modems.h:77
fax_set_tep_mode
void fax_set_tep_mode(fax_state_t *s, int use_tep)
Select whether TEP will be sent for the image modems.
Definition: fax.c:585
fax_modems_state_s::transmit_on_idle
int transmit_on_idle
Definition: private/fax_modems.h:43
fax_state_s::t30
t30_state_t t30
The T.30 back-end.
Definition: private/fax.h:38
fax_modems_state_s::audio_rx_log
int audio_rx_log
Audio logging file handle for received audio.
Definition: private/fax_modems.h:120
fax_restart
int fax_restart(fax_state_t *s, int calling_party)
Restart a FAX context.
Definition: fax.c:603
fax_free
int fax_free(fax_state_t *s)
Free a FAX context.
Definition: fax.c:726
fax_modems_state_s::v29_rx
v29_rx_state_t v29_rx
A V.29 modem context used when receiving FAXes at 7200bps or 9600bps.
Definition: private/fax_modems.h:68
fax_set_tep_mode
void fax_set_tep_mode(fax_state_t *s, int use_tep)
Select whether TEP will be sent for the image modems.
Definition: fax.c:585
t4_t6_encode.h
fax_release
int fax_release(fax_state_t *s)
Release a FAX context.
Definition: fax.c:719
fax_modems_state_s
Definition: private/fax_modems.h:34
v27ter_rx.h
get_bit_func_t
int(* get_bit_func_t)(void *user_data)
Definition: async.h:108
fax_modems_state_s::rx_handler
span_rx_handler_t * rx_handler
The current receive signal handler.
Definition: private/fax_modems.h:98
T30_SUPPORT_V29
@ T30_SUPPORT_V29
Definition: t30.h:344
fax_modems_state_s::next_tx_handler
span_tx_handler_t * next_tx_handler
The next transmit signal handler, for two stage transmit operations. E.g. a short silence followed by...
Definition: private/fax_modems.h:109
t4_t6_decode.h
fax_modems_state_s::rx_bit_rate
int rx_bit_rate
The current bit rate of the receiver.
Definition: private/fax_modems.h:115
fax_modems_state_s::tx_bit_rate
int tx_bit_rate
The current bit rate of the transmitter.
Definition: private/fax_modems.h:113
v17tx.h
v29_tx_set_get_bit
void v29_tx_set_get_bit(v29_tx_state_t *s, get_bit_func_t get_bit, void *user_data)
Change the get_bit function associated with a V.29 modem transmit context.
Definition: v29tx.c:310
v17_rx_restart
int v17_rx_restart(v17_rx_state_t *s, int bit_rate, int short_train)
Reinitialise an existing V.17 modem receive context.
Definition: v17rx.c:1380
T30_SUPPORT_V27TER
@ T30_SUPPORT_V27TER
Definition: t30.h:342
queue.h
fax_state_s
Definition: private/fax.h:35
fax_modems_state_s::hdlc_rx
hdlc_rx_state_t hdlc_rx
An HDLC context used when receiving HDLC messages.
Definition: private/fax_modems.h:48
HDLC_FRAMING_OK_THRESHOLD
#define HDLC_FRAMING_OK_THRESHOLD
Definition: t38_gateway.c:175
span_log
int span_log(logging_state_t *s, int level, const char *format,...)
Generate a log entry.
Definition: logging.c:84
v29rx.h
dc_restore.h
modem_connect_tones_tx_init
modem_connect_tones_tx_state_t * modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s, int tone_type)
Initialise an instance of the modem connect tones generator.
Definition: modem_connect_tones.c:253
t30_state_s::logging
logging_state_t logging
Error and flow logging control.
Definition: private/t30.h:306
fax_free
int fax_free(fax_state_t *s)
Free a FAX context.
Definition: fax.c:726
hdlc_rx_init
hdlc_rx_state_t * hdlc_rx_init(hdlc_rx_state_t *s, int crc32, int report_bad_frames, int framing_ok_threshold, hdlc_frame_handler_t handler, void *user_data)
Initialise an HDLC receiver context.
Definition: hdlc.c:327
t30_state_s
Definition: private/t30.h:35
silence_gen_alter
void silence_gen_alter(silence_gen_state_t *s, int silent_samples)
Alter the period of a silence generator context by a specified amount.
Definition: silence_gen.c:86
fsk_rx_init
fsk_rx_state_t * fsk_rx_init(fsk_rx_state_t *s, const fsk_spec_t *spec, int framing_mode, put_bit_func_t put_bit, void *user_data)
Initialise an FSK modem receive context.
Definition: fsk.c:314
t30_state_s::rx_frame_received
int rx_frame_received
True if a valid HDLC frame has been received in the current reception period.
Definition: private/t30.h:189
v29_rx_restart
int v29_rx_restart(v29_rx_state_t *s, int bit_rate, int old_train)
Reinitialise an existing V.29 modem receive context.
Definition: v29rx.c:1072
v17tx.h
fax_get_t30_state
t30_state_t * fax_get_t30_state(fax_state_t *s)
Get a pointer to the T.30 engine associated with a FAX context.
Definition: fax.c:591
fsk_tx_init
fsk_tx_state_t * fsk_tx_init(fsk_tx_state_t *s, const fsk_spec_t *spec, get_bit_func_t get_bit, void *user_data)
Initialise an FSK modem transmit context.
Definition: fsk.c:153
v27ter_tx_restart
int v27ter_tx_restart(v27ter_tx_state_t *s, int bit_rate, int tep)
Reinitialise an existing V.27ter modem transmit context.
Definition: v27ter_tx.c:390
v17_tx_set_get_bit
void v17_tx_set_get_bit(v17_tx_state_t *s, get_bit_func_t get_bit, void *user_data)
Change the get_bit function associated with a V.17 modem transmit context.
Definition: v17tx.c:358
fsk.h
fax_modems_state_s::transmit
int transmit
If TRUE, transmission is in progress.
Definition: private/fax_modems.h:118
fsk_rx_signal_cutoff
void fsk_rx_signal_cutoff(fsk_rx_state_t *s, float cutoff)
Adjust an FSK modem receive context's carrier detect power threshold.
Definition: fsk.c:238
fax_modems_state_s::current_tx_type
int current_tx_type
The currently selected transmitter type.
Definition: private/fax_modems.h:88
logging.h
fax.h
fax_release
int fax_release(fax_state_t *s)
Release a FAX context.
Definition: fax.c:719
fax_state_s::modems
fax_modems_state_t modems
The analogue modem front-end.
Definition: private/fax.h:41
v8.h
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(int) fax_rx(fax_state_t *s
Apply T.30 receive processing to a block of audio samples.
v29tx.h
fax_modems_state_s::v21_rx
fsk_rx_state_t v21_rx
A V.21 FSK modem context used when receiving HDLC over V.21 messages.
Definition: private/fax_modems.h:54
fax_modems_state_s::use_tep
int use_tep
Definition: private/fax_modems.h:37
t30_set_supported_modems
int t30_set_supported_modems(t30_state_t *s, int supported_modems)
Specify supported modems.
Definition: t30_api.c:680
fax_modems_state_s::tx_handler
span_tx_handler_t * tx_handler
The current transmit signal handler.
Definition: private/fax_modems.h:104
fax_modems.h
fax_modems_state_s::hdlc_tx
hdlc_tx_state_t hdlc_tx
An HDLC context used when transmitting HDLC messages.
Definition: private/fax_modems.h:46
fax_modems_state_s::v17_rx
v17_rx_state_t v17_rx
A V.29 modem context used when receiving FAXes at 7200bps, 9600bps 12000bps or 14400bps.
Definition: private/fax_modems.h:62
fax_init
fax_state_t * fax_init(fax_state_t *s, int calling_party)
Initialise a FAX context.
Definition: fax.c:664
t30_restart
int t30_restart(t30_state_t *s)
Restart a T.30 context.
Definition: t30.c:6287
fax_get_logging_state
logging_state_t * fax_get_logging_state(fax_state_t *s)
Get a pointer to the logging context associated with a FAX context.
Definition: fax.c:597
T30_SUPPORT_V17
@ T30_SUPPORT_V17
Definition: t30.h:346
t30_fcf.h
fax_modems_state_s::current_rx_type
int current_rx_type
The currently selected receiver type.
Definition: private/fax_modems.h:86
t30_state_s::rx_trained
int rx_trained
True if a modem has trained correctly.
Definition: private/t30.h:187
v27ter_rx_signal_power
float v27ter_rx_signal_power(v27ter_rx_state_t *s)
Definition: v27ter_rx.c:152
t35.h
logging_state_s
Definition: private/logging.h:33
modem_connect_tones.h
v8_init
v8_state_t * v8_init(v8_state_t *s, int calling_party, v8_parms_t *parms, v8_result_handler_t result_handler, void *user_data)
Initialise a V.8 context.
Definition: v8.c:1073
t30_state_s::supported_modems
int supported_modems
A bit mask of the currently supported modem types.
Definition: private/t30.h:52
v8_parms_s
Definition: v8.h:117
fax_modems_state_s::connect_tx
modem_connect_tones_tx_state_t connect_tx
CED or CNG generator.
Definition: private/fax_modems.h:79
fax.h
fax_modems_state_s::v21_tx
fsk_tx_state_t v21_tx
A V.21 FSK modem context used when transmitting HDLC over V.21 messages.
Definition: private/fax_modems.h:51
fax_modems.h
v29_tx_restart
int v29_tx_restart(v29_tx_state_t *s, int bit_rate, int tep)
Reinitialise an existing V.29 modem transmit context.
Definition: v29tx.c:332
hdlc_tx_flags
int hdlc_tx_flags(hdlc_tx_state_t *s, int len)
Transmit a specified quantity of flag octets, typically as a preamble.
Definition: hdlc.c:424
t30_init
t30_state_t * t30_init(t30_state_t *s, int calling_party, t30_set_handler_t *set_rx_type_handler, void *set_rx_type_user_data, t30_set_handler_t *set_tx_type_handler, void *set_tx_type_user_data, t30_send_hdlc_handler_t *send_hdlc_handler, void *send_hdlc_user_data)
Initialise a T.30 context.
Definition: t30.c:6327
v17_rx_signal_power
float v17_rx_signal_power(v17_rx_state_t *s)
Definition: v17rx.c:182