v8.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * v8.h - V.8 modem negotiation processing.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004 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: v8.h,v 1.31.4.1 2009/12/28 12:20:47 steveu Exp $
00026  */
00027  
00028 /*! \file */
00029 
00030 /*! \page v8_page The V.8 modem negotiation protocol
00031 \section v8_page_sec_1 What does it do?
00032 The V.8 specification defines a procedure to be used as PSTN modem answer phone calls,
00033 which allows the modems to negotiate the optimum modem standard, which both ends can
00034 support.
00035 
00036 \section v8_page_sec_2 How does it work?
00037 At startup the modems communicate using the V.21 standard at 300 bits/second. They
00038 exchange simple messages about their capabilities, and choose the modem standard they
00039 will use for data communication. The V.8 protocol then terminates, and the modems
00040 being negotiating and training with their chosen modem standard.
00041 */
00042 
00043 #if !defined(_SPANDSP_V8_H_)
00044 #define _SPANDSP_V8_H_
00045 
00046 typedef struct v8_parms_s v8_parms_t;
00047 
00048 typedef void (v8_result_handler_t)(void *user_data, v8_parms_t *result);
00049 
00050 enum v8_call_function_e
00051 {
00052     V8_CALL_TBS = 0,
00053     V8_CALL_H324 = 1,
00054     V8_CALL_V18 = 2,
00055     V8_CALL_T101 = 3,
00056     V8_CALL_T30_TX = 4,
00057     V8_CALL_T30_RX = 5,
00058     V8_CALL_V_SERIES = 6,
00059     V8_CALL_FUNCTION_EXTENSION = 7
00060 };
00061 
00062 enum v8_modulation_e
00063 {
00064     V8_MOD_V17          = (1 << 0),     /* V.17 half-duplex */
00065     V8_MOD_V21          = (1 << 1),     /* V.21 duplex */
00066     V8_MOD_V22          = (1 << 2),     /* V.22/V22.bis duplex */
00067     V8_MOD_V23HALF      = (1 << 3),     /* V.23 half-duplex */
00068     V8_MOD_V23          = (1 << 4),     /* V.23 duplex */
00069     V8_MOD_V26BIS       = (1 << 5),     /* V.23 duplex */
00070     V8_MOD_V26TER       = (1 << 6),     /* V.23 duplex */
00071     V8_MOD_V27TER       = (1 << 7),     /* V.23 duplex */
00072     V8_MOD_V29          = (1 << 8),     /* V.29 half-duplex */
00073     V8_MOD_V32          = (1 << 9),     /* V.32/V32.bis duplex */
00074     V8_MOD_V34HALF      = (1 << 10),    /* V.34 half-duplex */
00075     V8_MOD_V34          = (1 << 11),    /* V.34 duplex */
00076     V8_MOD_V90          = (1 << 12),    /* V.90 duplex */
00077     V8_MOD_V92          = (1 << 13),    /* V.92 duplex */
00078 
00079     V8_MOD_FAILED       = (1 << 15)     /* Indicates failure to negotiate */
00080 };
00081 
00082 enum v8_protocol_e
00083 {
00084     V8_PROTOCOL_NONE = 0,
00085     V8_PROTOCOL_LAPM_V42 = 1,
00086     V8_PROTOCOL_EXTENSION = 7
00087 };
00088 
00089 enum v8_pstn_access_e
00090 {
00091     V8_PSTN_ACCESS_CALL_DCE_CELLULAR = 0x01,
00092     V8_PSTN_ACCESS_ANSWER_DCE_CELLULAR = 0x02,
00093     V8_PSTN_ACCESS_DCE_ON_DIGITAL = 0x04
00094 };
00095 
00096 enum v8_pcm_modem_availability_e
00097 {
00098     V8_PSTN_PCM_MODEM_V90_V92_ANALOGUE = 0x01,
00099     V8_PSTN_PCM_MODEM_V90_V92_DIGITAL = 0x02,
00100     V8_PSTN_PCM_MODEM_V91 = 0x04
00101 };
00102 
00103 typedef struct v8_state_s v8_state_t;
00104 
00105 struct v8_parms_s
00106 {
00107     int modem_connect_tone;
00108     int call_function;
00109     unsigned int modulations;
00110     int protocol;
00111     int pstn_access;
00112     int pcm_modem_availability;
00113     int nsf;
00114     int t66;
00115 };
00116 
00117 #if defined(__cplusplus)
00118 extern "C"
00119 {
00120 #endif
00121 
00122 SPAN_DECLARE(int) v8_restart(v8_state_t *s,
00123                              int calling_party,
00124                              v8_parms_t *parms);
00125 
00126 /*! Initialise a V.8 context.
00127     \brief Initialise a V.8 context.
00128     \param s The V.8 context.
00129     \param calling_party TRUE if caller mode, else answerer mode.
00130     \param parms The allowed parameters for the call.
00131     \param result_handler The callback routine used to handle the results of negotiation.
00132     \param user_data An opaque pointer passed to the result_handler routine.
00133     \return A pointer to the V.8 context, or NULL if there was a problem. */
00134 SPAN_DECLARE(v8_state_t *) v8_init(v8_state_t *s,
00135                                    int calling_party,
00136                                    v8_parms_t *parms,
00137                                    v8_result_handler_t *result_handler,
00138                                    void *user_data);
00139 
00140 /*! Release a V.8 context.
00141     \brief Release a V.8 context.
00142     \param s The V.8 context.
00143     \return 0 for OK. */
00144 SPAN_DECLARE(int) v8_release(v8_state_t *s);
00145 
00146 /*! Free a V.8 context.
00147     \brief Release a V.8 context.
00148     \param s The V.8 context.
00149     \return 0 for OK. */
00150 SPAN_DECLARE(int) v8_free(v8_state_t *s);
00151 
00152 SPAN_DECLARE(logging_state_t *) v8_get_logging_state(v8_state_t *s);
00153 
00154 /*! Generate a block of V.8 audio samples.
00155     \brief Generate a block of V.8 audio samples.
00156     \param s The V.8 context.
00157     \param amp The audio sample buffer.
00158     \param max_len The number of samples to be generated.
00159     \return The number of samples actually generated.
00160 */
00161 SPAN_DECLARE_NONSTD(int) v8_tx(v8_state_t *s, int16_t *amp, int max_len);
00162 
00163 /*! Process a block of received V.8 audio samples.
00164     \brief Process a block of received V.8 audio samples.
00165     \param s The V.8 context.
00166     \param amp The audio sample buffer.
00167     \param len The number of samples in the buffer.
00168 */
00169 SPAN_DECLARE_NONSTD(int) v8_rx(v8_state_t *s, const int16_t *amp, int len);
00170 
00171 /*! Log the list of supported modulations.
00172     \brief Log the list of supported modulations.
00173     \param s The V.8 context.
00174     \param modulation_schemes The list of supported modulations. */
00175 SPAN_DECLARE(void) v8_log_supported_modulations(v8_state_t *s, int modulation_schemes);
00176 
00177 SPAN_DECLARE(const char *) v8_call_function_to_str(int call_function);
00178 SPAN_DECLARE(const char *) v8_modulation_to_str(int modulation_scheme);
00179 SPAN_DECLARE(const char *) v8_protocol_to_str(int protocol);
00180 SPAN_DECLARE(const char *) v8_pstn_access_to_str(int pstn_access);
00181 SPAN_DECLARE(const char *) v8_nsf_to_str(int nsf);
00182 SPAN_DECLARE(const char *) v8_pcm_modem_availability_to_str(int pcm_modem_availability);
00183 SPAN_DECLARE(const char *) v8_t66_to_str(int t66);
00184 
00185 #if defined(__cplusplus)
00186 }
00187 #endif
00188 
00189 #endif
00190 /*- End of file ------------------------------------------------------------*/

Generated on Mon Jan 3 02:31:16 2011 for spandsp by  doxygen 1.4.7