v18.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * v18.h - V.18 text telephony for the deaf.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004-2009 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025  
00026 /*! \file */
00027 
00028 /*! \page v18_page The V.18 text telephony protocols
00029 \section v18_page_sec_1 What does it do?
00030 
00031 \section v18_page_sec_2 How does it work?
00032 */
00033 
00034 #if !defined(_SPANDSP_V18_H_)
00035 #define _SPANDSP_V18_H_
00036 
00037 typedef struct v18_state_s v18_state_t;
00038 
00039 enum
00040 {
00041     V18_MODE_NONE = 0,
00042     /* V.18 Annex A - Weitbrecht TDD at 45.45bps, half-duplex, 5 bit baudot. */
00043     V18_MODE_5BIT_45 = 1,
00044     /* V.18 Annex A - Weitbrecht TDD at 50bps, half-duplex, 5 bit baudot. */
00045     V18_MODE_5BIT_50 = 2,
00046     /* V.18 Annex B - DTMF encoding of ASCII. */
00047     V18_MODE_DTMF = 3,
00048     /* V.18 Annex C - EDT 110bps, V.21, half-duplex, ASCII. */
00049     V18_MODE_EDT = 4,
00050     /* V.18 Annex D - 300bps, Bell 103, duplex, ASCII. */
00051     V18_MODE_BELL103 = 5,
00052     /* V.18 Annex E - 1200bps Videotex terminals, ASCII. */
00053     V18_MODE_V23VIDEOTEX = 6,
00054     /* V.18 Annex F - V.21 text telephone, V.21, duplex, ASCII. */
00055     V18_MODE_V21TEXTPHONE = 7,
00056     /* V.18 Annex G - V.18 text telephone mode. */
00057     V18_MODE_V18TEXTPHONE = 8
00058 };
00059 
00060 #if defined(__cplusplus)
00061 extern "C"
00062 {
00063 #endif
00064 
00065 SPAN_DECLARE(logging_state_t *) v18_get_logging_state(v18_state_t *s);
00066 
00067 /*! Initialise a V.18 context.
00068     \brief Initialise a V.18 context.
00069     \param s The V.18 context.
00070     \param calling_party TRUE if caller mode, else answerer mode.
00071     \param mode Mode of operation.
00072     \param put_msg A callback routine called to deliver the received text
00073            to the application.
00074     \param user_data An opaque pointer for the callback routine.
00075     \return A pointer to the V.18 context, or NULL if there was a problem. */
00076 SPAN_DECLARE(v18_state_t *) v18_init(v18_state_t *s,
00077                                      int calling_party,
00078                                      int mode,
00079                                      put_msg_func_t put_msg,
00080                                      void *user_data);
00081 
00082 /*! Release a V.18 context.
00083     \brief Release a V.18 context.
00084     \param s The V.18 context.
00085     \return 0 for OK. */
00086 SPAN_DECLARE(int) v18_release(v18_state_t *s);
00087 
00088 /*! Free a V.18 context.
00089     \brief Release a V.18 context.
00090     \param s The V.18 context.
00091     \return 0 for OK. */
00092 SPAN_DECLARE(int) v18_free(v18_state_t *s);
00093 
00094 /*! Generate a block of V.18 audio samples.
00095     \brief Generate a block of V.18 audio samples.
00096     \param s The V.18 context.
00097     \param amp The audio sample buffer.
00098     \param max_len The number of samples to be generated.
00099     \return The number of samples actually generated.
00100 */
00101 SPAN_DECLARE_NONSTD(int) v18_tx(v18_state_t *s, int16_t amp[], int max_len);
00102 
00103 /*! Process a block of received V.18 audio samples.
00104     \brief Process a block of received V.18 audio samples.
00105     \param s The V.18 context.
00106     \param amp The audio sample buffer.
00107     \param len The number of samples in the buffer.
00108 */
00109 SPAN_DECLARE_NONSTD(int) v18_rx(v18_state_t *s, const int16_t amp[], int len);
00110 
00111 /*! \brief Put a string to a V.18 context's input buffer.
00112     \param s The V.18 context.
00113     \param msg The string to be added.
00114     \param len The length of the string. If negative, the string is
00115            assumed to be a NULL terminated string.
00116     \return The number of characters actually added. This may be less than the
00117             length of the digit string, if the buffer fills up. If the string is
00118             invalid, this function will return -1. */
00119 SPAN_DECLARE(int) v18_put(v18_state_t *s, const char msg[], int len);
00120 
00121 /*! Convert a text string to a V.18 DTMF string.
00122     \brief Convert a text string to a V.18 DTMF string.
00123     \param s The V.18 context.
00124     \param dtmf The resulting DTMF string.
00125     \param msg The text string to be converted.
00126     \return The length of the DTMF string.
00127 */
00128 SPAN_DECLARE(int) v18_encode_dtmf(v18_state_t *s, char dtmf[], const char msg[]);
00129 
00130 /*! Convert a V.18 DTMF string to a text string.
00131     \brief Convert a V.18 DTMF string to a text string.
00132     \param s The V.18 context.
00133     \param msg The resulting test string.
00134     \param dtmf The DTMF string to be converted.
00135     \return The length of the text string.
00136 */
00137 SPAN_DECLARE(int) v18_decode_dtmf(v18_state_t *s, char msg[], const char dtmf[]);
00138 
00139 SPAN_DECLARE(uint16_t) v18_encode_baudot(v18_state_t *s, uint8_t ch);
00140 
00141 SPAN_DECLARE(uint8_t) v18_decode_baudot(v18_state_t *s, uint8_t ch);
00142 
00143 /*! \brief Return a short name for an V.18 mode
00144     \param mode The code for the V.18 mode.
00145     \return A pointer to the name.
00146 */
00147 SPAN_DECLARE(const char *) v18_mode_to_str(int mode);
00148 
00149 #if defined(__cplusplus)
00150 }
00151 #endif
00152 
00153 #endif
00154 /*- End of file ------------------------------------------------------------*/

Generated on Wed Feb 8 18:38:19 2012 for spandsp by  doxygen 1.4.7