t38_non_ecm_buffer.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * t38_non_ecm_buffer.h - A rate adapting buffer for T.38 non-ECM image
00005  *                        and TCF data
00006  *
00007  * Written by Steve Underwood <steveu@coppice.org>
00008  *
00009  * Copyright (C) 2005, 2006, 2007, 2008 Steve Underwood
00010  *
00011  * All rights reserved.
00012  *
00013  * This program is free software; you can redistribute it and/or modify
00014  * it under the terms of the GNU Lesser General Public License version 2.1,
00015  * as published by the Free Software Foundation.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU Lesser General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU Lesser General Public
00023  * License along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: t38_non_ecm_buffer.h,v 1.7.4.1 2009/12/19 06:43:28 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 #if !defined(_SPANDSP_T38_NON_ECM_BUFFER_H_)
00032 #define _SPANDSP_T38_NON_ECM_BUFFER_H_
00033 
00034 /*! \page t38_non_ecm_buffer_page T.38 rate adapting non-ECM image data buffer
00035 \section t38_non_ecm_buffer_page_sec_1 What does it do?
00036 
00037 The T.38 rate adapting non-ECM image data buffer is used to buffer TCF and non-ECM
00038 FAX image data being gatewayed from a T.38 link to an analogue FAX modem link.
00039 
00040 As well as rate adapting, the buffer has the ability to impose a minimum on the number
00041 of bits per row of image data. This allows any row padding zeros to be stripped from
00042 the data stream, to minimise the data sent as T.38 packets, and be reinserted before
00043 the data is sent to its final destination. Not all T.38 implementations support this
00044 feature, so it's use must be negotiated.
00045 
00046 \section t38_non_ecm_buffer_page_sec_2 How does it work?
00047 
00048 When inserting padding bits, whether to ensure a minimum row time or for flow control,
00049 it is important the right value is inserted at the right point in the data sequence.
00050 If we are in the optional initial period of all ones, we can insert a byte of extra
00051 ones at any time. Once we pass that initial stage, TCF and image data need separate
00052 handling.
00053 
00054 TCF data is all zeros. Once the period of all zeros has begun it is OK to insert
00055 additional bytes of zeros at any point.
00056 
00057 Image data consists of rows, separated by EOL (end of line) markers. Inserting
00058 zeros at arbitrary times would corrupt the image. However, it is OK to insert a
00059 considerable number of extra zeros just before an EOL. Therefore we track where the
00060 EOL markers occur as we fill the buffer. As we empty the buffer stop outputting real
00061 data, and start outputting bytes of zero, if we reach this last EOL marker location.
00062 The EOL marker is 11 zeros following by 1 (1D mode) or 2 (2D mode) ones. Therefore, it
00063 always spills across 2 bytes in the buffer, and there is always a point where we can
00064 insert our extra zeros between bytes.
00065 
00066 Padding between the group of successive EOL markers which for the RTC (return to control)
00067 marker that ends an image causes some FAX machines not to recognise them as an RTC condition.
00068 Therefore, our padding applies special protection so padding never occurs between two
00069 successive EOL markers, with no pixel data between them.
00070 */
00071 
00072 /*! The buffer length much be a power of two. The chosen length is big enough for
00073     over 9s of data at the V.17 14,400bps rate. */    
00074 #define T38_NON_ECM_TX_BUF_LEN  16384
00075 
00076 /*! \brief A flow controlled non-ECM image data buffer, for buffering T.38 to analogue
00077            modem data.
00078 */
00079 typedef struct t38_non_ecm_buffer_state_s t38_non_ecm_buffer_state_t;
00080 
00081 #if defined(__cplusplus)
00082 extern "C"
00083 {
00084 #endif
00085 
00086 /*! \brief Initialise a T.38 rate adapting non-ECM buffer context.
00087     \param s The buffer context.
00088     \param mode TRUE for image data mode, or FALSE for TCF mode.
00089     \param bits The minimum number of bits per FAX image row.
00090     \return A pointer to the buffer context, or NULL if there was a problem. */
00091 SPAN_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);
00092 
00093 SPAN_DECLARE(int) t38_non_ecm_buffer_release(t38_non_ecm_buffer_state_t *s);
00094 
00095 SPAN_DECLARE(int) t38_non_ecm_buffer_free(t38_non_ecm_buffer_state_t *s);
00096 
00097 /*! \brief Set the mode of a T.38 rate adapting non-ECM buffer context.
00098     \param s The buffer context.
00099     \param mode TRUE for image data mode, or FALSE for TCF mode.
00100     \param bits The minimum number of bits per FAX image row. */
00101 SPAN_DECLARE(void) t38_non_ecm_buffer_set_mode(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits);
00102 
00103 /*! \brief Inject data to T.38 rate adapting non-ECM buffer context.
00104     \param s The buffer context.
00105     \param buf The data buffer to be injected.
00106     \param len The length of the data to be injected. */
00107 SPAN_DECLARE(void) t38_non_ecm_buffer_inject(t38_non_ecm_buffer_state_t *s, const uint8_t *buf, int len);
00108 
00109 /*! \brief Inform a T.38 rate adapting non-ECM buffer context that the incoming data has finished,
00110            and the contents of the buffer should be played out as quickly as possible.
00111     \param s The buffer context. */
00112 SPAN_DECLARE(void) t38_non_ecm_buffer_push(t38_non_ecm_buffer_state_t *s);
00113 
00114 /*! \brief Report the input status of a T.38 rate adapting non-ECM buffer context to the specified
00115            logging context.
00116     \param s The buffer context.
00117     \param logging The logging context. */
00118 SPAN_DECLARE(void) t38_non_ecm_buffer_report_input_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging);
00119 
00120 /*! \brief Report the output status of a T.38 rate adapting non-ECM buffer context to the specified
00121            logging context.
00122     \param s The buffer context.
00123     \param logging The logging context. */
00124 SPAN_DECLARE(void) t38_non_ecm_buffer_report_output_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging);
00125 
00126 /*! \brief Get the next bit of data from a T.38 rate adapting non-ECM buffer context.
00127     \param user_data The buffer context, cast to a void pointer.
00128     \return The next bit, or one of the values indicating a change of modem status. */
00129 SPAN_DECLARE_NONSTD(int) t38_non_ecm_buffer_get_bit(void *user_data);
00130 
00131 #if defined(__cplusplus)
00132 }
00133 #endif
00134 
00135 #endif
00136 /*- End of file ------------------------------------------------------------*/

Generated on Tue Jan 11 14:08:44 2011 for spandsp by  doxygen 1.4.7