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  * $Id: v18.h,v 1.6 2009/11/04 15:52:06 steveu Exp $
00026  */
00027  
00028 /*! \file */
00029 
00030 /*! \page v18_page The V.18 text telephony protocols
00031 \section v18_page_sec_1 What does it do?
00032 
00033 \section v18_page_sec_2 How does it work?
00034 */
00035 
00036 #if !defined(_SPANDSP_V18_H_)
00037 #define _SPANDSP_V18_H_
00038 
00039 typedef struct v18_state_s v18_state_t;
00040 
00041 enum
00042 {
00043     V18_MODE_NONE = 0,
00044     /* V.18 Annex A - Weitbrecht TDD at 45.45bps, half-duplex, 5 bit baudot. */
00045     V18_MODE_5BIT_45 = 1,
00046     /* V.18 Annex A - Weitbrecht TDD at 50bps, half-duplex, 5 bit baudot. */
00047     V18_MODE_5BIT_50 = 2,
00048     /* V.18 Annex B - DTMF encoding of ASCII. */
00049     V18_MODE_DTMF = 3,
00050     /* V.18 Annex C - EDT 110bps, V.21, half-duplex, ASCII. */
00051     V18_MODE_EDT = 4,
00052     /* V.18 Annex D - 300bps, Bell 103, duplex, ASCII. */
00053     V18_MODE_BELL103 = 5,
00054     /* V.18 Annex E - 1200bps Videotex terminals, ASCII. */
00055     V18_MODE_V23VIDEOTEX = 6,
00056     /* V.18 Annex F - V.21 text telephone, V.21, duplex, ASCII. */
00057     V18_MODE_V21TEXTPHONE = 7,
00058     /* V.18 Annex G - V.18 text telephone mode. */
00059     V18_MODE_V18TEXTPHONE = 8
00060 };
00061 
00062 #if defined(__cplusplus)
00063 extern "C"
00064 {
00065 #endif
00066 
00067 SPAN_DECLARE(logging_state_t *) v18_get_logging_state(v18_state_t *s);
00068 
00069 /*! Initialise a V.18 context.
00070     \brief Initialise a V.18 context.
00071     \param s The V.18 context.
00072     \param calling_party TRUE if caller mode, else answerer mode.
00073     \param mode Mode of operation.
00074     \param put_msg A callback routine called to deliver the received text
00075            to the application.
00076     \param user_data An opaque pointer for the callback routine.
00077     \return A pointer to the V.18 context, or NULL if there was a problem. */
00078 SPAN_DECLARE(v18_state_t *) v18_init(v18_state_t *s,
00079                                      int calling_party,
00080                                      int mode,
00081                                      put_msg_func_t put_msg,
00082                                      void *user_data);
00083 
00084 /*! Release a V.18 context.
00085     \brief Release a V.18 context.
00086     \param s The V.18 context.
00087     \return 0 for OK. */
00088 SPAN_DECLARE(int) v18_release(v18_state_t *s);
00089 
00090 /*! Free a V.18 context.
00091     \brief Release a V.18 context.
00092     \param s The V.18 context.
00093     \return 0 for OK. */
00094 SPAN_DECLARE(int) v18_free(v18_state_t *s);
00095 
00096 /*! Generate a block of V.18 audio samples.
00097     \brief Generate a block of V.18 audio samples.
00098     \param s The V.18 context.
00099     \param amp The audio sample buffer.
00100     \param max_len The number of samples to be generated.
00101     \return The number of samples actually generated.
00102 */
00103 SPAN_DECLARE_NONSTD(int) v18_tx(v18_state_t *s, int16_t amp[], int max_len);
00104 
00105 /*! Process a block of received V.18 audio samples.
00106     \brief Process a block of received V.18 audio samples.
00107     \param s The V.18 context.
00108     \param amp The audio sample buffer.
00109     \param len The number of samples in the buffer.
00110 */
00111 SPAN_DECLARE_NONSTD(int) v18_rx(v18_state_t *s, const int16_t amp[], int len);
00112 
00113 /*! \brief Put a string to a V.18 context's input buffer.
00114     \param s The V.18 context.
00115     \param msg The string to be added.
00116     \param len The length of the string. If negative, the string is
00117            assumed to be a NULL terminated string.
00118     \return The number of characters actually added. This may be less than the
00119             length of the digit string, if the buffer fills up. If the string is
00120             invalid, this function will return -1. */
00121 SPAN_DECLARE(int) v18_put(v18_state_t *s, const char msg[], int len);
00122 
00123 /*! Convert a text string to a V.18 DTMF string.
00124     \brief Convert a text string to a V.18 DTMF string.
00125     \param s The V.18 context.
00126     \param dtmf The resulting DTMF string.
00127     \param msg The text string to be converted.
00128     \return The length of the DTMF string.
00129 */
00130 SPAN_DECLARE(int) v18_encode_dtmf(v18_state_t *s, char dtmf[], const char msg[]);
00131 
00132 /*! Convert a V.18 DTMF string to a text string.
00133     \brief Convert a V.18 DTMF string to a text string.
00134     \param s The V.18 context.
00135     \param msg The resulting test string.
00136     \param dtmf The DTMF string to be converted.
00137     \return The length of the text string.
00138 */
00139 SPAN_DECLARE(int) v18_decode_dtmf(v18_state_t *s, char msg[], const char dtmf[]);
00140 
00141 SPAN_DECLARE(uint16_t) v18_encode_baudot(v18_state_t *s, uint8_t ch);
00142 
00143 SPAN_DECLARE(uint8_t) v18_decode_baudot(v18_state_t *s, uint8_t ch);
00144 
00145 /*! \brief Return a short name for an V.18 mode
00146     \param mode The code for the V.18 mode.
00147     \return A pointer to the name.
00148 */
00149 SPAN_DECLARE(const char *) v18_mode_to_str(int mode);
00150 
00151 #if defined(__cplusplus)
00152 }
00153 #endif
00154 
00155 #endif
00156 /*- End of file ------------------------------------------------------------*/

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