spandsp: t38_non_ecm_buffer.h Source File

spandsp 0.0.6

t38_non_ecm_buffer.h
Go to the documentation of this file.
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * t38_non_ecm_buffer.h - A rate adapting buffer for T.38 non-ECM image
5 * and TCF data
6 *
7 * Written by Steve Underwood <steveu@coppice.org>
8 *
9 * Copyright (C) 2005, 2006, 2007, 2008 Steve Underwood
10 *
11 * All rights reserved.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU Lesser General Public License version 2.1,
15 * as published by the Free Software Foundation.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this program; if not, write to the Free Software
24 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25 */
26
27/*! \file */
28
29#if !defined(_SPANDSP_T38_NON_ECM_BUFFER_H_)
30#define _SPANDSP_T38_NON_ECM_BUFFER_H_
31
32/*! \page t38_non_ecm_buffer_page T.38 rate adapting non-ECM image data buffer
33\section t38_non_ecm_buffer_page_sec_1 What does it do?
34
35The T.38 rate adapting non-ECM image data buffer is used to buffer TCF and non-ECM
36FAX image data being gatewayed from a T.38 link to an analogue FAX modem link.
37
38As well as rate adapting, the buffer has the ability to impose a minimum on the number
39of bits per row of image data. This allows any row padding zeros to be stripped from
40the data stream, to minimise the data sent as T.38 packets, and be reinserted before
41the data is sent to its final destination. Not all T.38 implementations support this
42feature, so it's use must be negotiated.
43
44\section t38_non_ecm_buffer_page_sec_2 How does it work?
45
46When inserting padding bits, whether to ensure a minimum row time or for flow control,
47it is important the right value is inserted at the right point in the data sequence.
48If we are in the optional initial period of all ones, we can insert a byte of extra
49ones at any time. Once we pass that initial stage, TCF and image data need separate
50handling.
51
52TCF data is all zeros. Once the period of all zeros has begun it is OK to insert
53additional bytes of zeros at any point.
54
55Image data consists of rows, separated by EOL (end of line) markers. Inserting
56zeros at arbitrary times would corrupt the image. However, it is OK to insert a
57considerable number of extra zeros just before an EOL. Therefore we track where the
58EOL markers occur as we fill the buffer. As we empty the buffer stop outputting real
59data, and start outputting bytes of zero, if we reach this last EOL marker location.
60The EOL marker is 11 zeros following by 1 (1D mode) or 2 (2D mode) ones. Therefore, it
61always spills across 2 bytes in the buffer, and there is always a point where we can
62insert our extra zeros between bytes.
63
64Padding between the group of successive EOL markers which for the RTC (return to control)
65marker that ends an image causes some FAX machines not to recognise them as an RTC condition.
66Therefore, our padding applies special protection so padding never occurs between two
67successive EOL markers, with no pixel data between them.
68*/
69
70/*! The buffer length much be a power of two. The chosen length is big enough for
71 over 9s of data at the V.17 14,400bps rate. */
72#define T38_NON_ECM_TX_BUF_LEN 16384
73
74/*! \brief A flow controlled non-ECM image data buffer, for buffering T.38 to analogue
75 modem data.
76*/
77 typedef struct t38_non_ecm_buffer_state_s t38_non_ecm_buffer_state_t;
78
79#if defined(__cplusplus)
80extern "C"
81{
82#endif
83
84/*! \brief Initialise a T.38 rate adapting non-ECM buffer context.
85 \param s The buffer context.
86 \param mode TRUE for image data mode, or FALSE for TCF mode.
87 \param bits The minimum number of bits per FAX image row.
88 \return A pointer to the buffer context, or NULL if there was a problem. */
89SPAN_DECLARE(t38_non_ecm_buffer_state_t *) t38_non_ecm_buffer_init(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits);
90
91SPAN_DECLARE(int) t38_non_ecm_buffer_release(t38_non_ecm_buffer_state_t *s);
92
93SPAN_DECLARE(int) t38_non_ecm_buffer_free(t38_non_ecm_buffer_state_t *s);
94
95/*! \brief Set the mode of a T.38 rate adapting non-ECM buffer context.
96 \param s The buffer context.
97 \param mode TRUE for image data mode, or FALSE for TCF mode.
98 \param bits The minimum number of bits per FAX image row. */
99SPAN_DECLARE(void) t38_non_ecm_buffer_set_mode(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits);
100
101/*! \brief Inject data to T.38 rate adapting non-ECM buffer context.
102 \param s The buffer context.
103 \param buf The data buffer to be injected.
104 \param len The length of the data to be injected. */
105SPAN_DECLARE(void) t38_non_ecm_buffer_inject(t38_non_ecm_buffer_state_t *s, const uint8_t *buf, int len);
106
107/*! \brief Inform a T.38 rate adapting non-ECM buffer context that the incoming data has finished,
108 and the contents of the buffer should be played out as quickly as possible.
109 \param s The buffer context. */
110SPAN_DECLARE(void) t38_non_ecm_buffer_push(t38_non_ecm_buffer_state_t *s);
111
112/*! \brief Report the input status of a T.38 rate adapting non-ECM buffer context to the specified
113 logging context.
114 \param s The buffer context.
115 \param logging The logging context. */
116SPAN_DECLARE(void) t38_non_ecm_buffer_report_input_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging);
117
118/*! \brief Report the output status of a T.38 rate adapting non-ECM buffer context to the specified
119 logging context.
120 \param s The buffer context.
121 \param logging The logging context. */
122SPAN_DECLARE(void) t38_non_ecm_buffer_report_output_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging);
123
124/*! \brief Get the next bit of data from a T.38 rate adapting non-ECM buffer context.
125 \param user_data The buffer context, cast to a void pointer.
126 \return The next bit, or one of the values indicating a change of modem status. */
127SPAN_DECLARE_NONSTD(int) t38_non_ecm_buffer_get_bit(void *user_data);
128
129#if defined(__cplusplus)
130}
131#endif
132
133#endif
134/*- End of file ------------------------------------------------------------*/
logging_state_s
Definition private/logging.h:34
t38_non_ecm_buffer_state_s
A flow controlled non-ECM image data buffer, for buffering T.38 to analogue modem data.
Definition private/t38_non_ecm_buffer.h:34
t38_non_ecm_buffer_report_output_status
void t38_non_ecm_buffer_report_output_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging)
Report the output status of a T.38 rate adapting non-ECM buffer context to the specified logging cont...
Definition t38_non_ecm_buffer.c:326
t38_non_ecm_buffer_report_input_status
void t38_non_ecm_buffer_report_input_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging)
Report the input status of a T.38 rate adapting non-ECM buffer context to the specified logging conte...
Definition t38_non_ecm_buffer.c:309
t38_non_ecm_buffer_push
void t38_non_ecm_buffer_push(t38_non_ecm_buffer_state_t *s)
Inform a T.38 rate adapting non-ECM buffer context that the incoming data has finished,...
Definition t38_non_ecm_buffer.c:121
t38_non_ecm_buffer_set_mode
void t38_non_ecm_buffer_set_mode(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits)
Set the mode of a T.38 rate adapting non-ECM buffer context.
Definition t38_non_ecm_buffer.c:343
t38_non_ecm_buffer_init
t38_non_ecm_buffer_state_t * t38_non_ecm_buffer_init(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits)
Initialise a T.38 rate adapting non-ECM buffer context.
Definition t38_non_ecm_buffer.c:350
t38_non_ecm_buffer_inject
void t38_non_ecm_buffer_inject(t38_non_ecm_buffer_state_t *s, const uint8_t *buf, int len)
Inject data to T.38 rate adapting non-ECM buffer context.
Definition t38_non_ecm_buffer.c:130