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 General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
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 General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: v8.h,v 1.8 2005/12/25 17:33:37 steveu Exp $
00027  */
00028  
00029 /*! \file */
00030 
00031 /*! \page v8_page The V.8 modem negotiation protocol
00032 \section v8_page_sec_1 What does it do?
00033 The V.8 specification defines a procedure to be used as PSTN modem answer phone calls,
00034 which allows the modems to negotiate the optimum modem standard, which both ends can
00035 support.
00036 
00037 \section v8_page_sec_2 How does it work?
00038 At startup the modems communicate using the V.21 standard at 300 bits/second. They
00039 exchange simple messages about their capabilities, and choose the modem standard they
00040 will use for data communication. The V.8 protocol then terminates, and the modems
00041 being negotiating and training with their chosen modem standard.
00042 */
00043 
00044 #if !defined(_V8_H_)
00045 #define _V8_H_
00046 
00047 typedef void (v8_result_handler_t)(void *user_data, int result);
00048 
00049 typedef struct
00050 {
00051     /*! \brief TRUE if we are the calling modem */
00052     int caller;
00053     /*! \brief The current state of the V8 protocol */
00054     int state;
00055     int negotiation_timer;
00056     int ci_timer;
00057     int ci_count;
00058     fsk_tx_state_t v21tx;
00059     fsk_rx_state_t v21rx;
00060     queue_t tx_queue;
00061     echo_can_disable_tx_state_t v8_tx;
00062     echo_can_disable_rx_state_t v8_rx;
00063 
00064     v8_result_handler_t *result_handler;
00065     void *result_handler_user_data;
00066 
00067     /*! \brief Modulation schemes available at this end. */
00068     int available_modulations;
00069     int common_modulations;
00070     int selected_modulation;
00071     int far_end_modulations;
00072 
00073     /* V8 data parsing */
00074     unsigned int bit_stream;
00075     int bit_cnt;
00076     /* Indicates the type of message coming up */
00077     int preamble_type;
00078     uint8_t rx_data[64];
00079     int rx_data_ptr;
00080     
00081     /*! \brief a reference copy of the last CM or JM message, used when
00082                testing for matches. */
00083     uint8_t cm_jm_data[64];
00084     int cm_jm_count;
00085     int got_cm_jm;
00086     int got_cj;
00087     int zero_byte_count;
00088     /*! \brief Error and flow logging control */
00089     logging_state_t logging;
00090 } v8_state_t;
00091 
00092 #define V8_MOD_V17          (1 << 0)    /* V.17 duplex */
00093 #define V8_MOD_V21          (1 << 1)    /* V.21 duplex */
00094 #define V8_MOD_V22          (1 << 2)    /* V.22/V22.bis duplex */
00095 #define V8_MOD_V23HALF      (1 << 3)    /* V.23 half-duplex */
00096 #define V8_MOD_V23          (1 << 4)    /* V.23 duplex */
00097 #define V8_MOD_V26BIS       (1 << 5)    /* V.23 duplex */
00098 #define V8_MOD_V26TER       (1 << 6)    /* V.23 duplex */
00099 #define V8_MOD_V27TER       (1 << 7)    /* V.23 duplex */
00100 #define V8_MOD_V29          (1 << 8)    /* V.29 half-duplex */
00101 #define V8_MOD_V32          (1 << 9)    /* V.32/V32.bis duplex */
00102 #define V8_MOD_V34HALF      (1 << 10)   /* V.34 half-duplex */
00103 #define V8_MOD_V34          (1 << 11)   /* V.34 duplex */
00104 #define V8_MOD_V90          (1 << 12)   /* V.90 duplex */
00105 #define V8_MOD_V92          (1 << 13)   /* V.92 duplex */
00106 
00107 #define V8_MOD_FAILED       (1 << 15)   /* Indicates failure to negotiate */
00108 
00109 #ifdef __cplusplus
00110 extern "C" {
00111 #endif
00112 
00113 /*! Initialise a V.8 context.
00114     \brief Initialise a V.8 context.
00115     \param s The V.8 context.
00116     \param caller TRUE if caller mode, else answerer mode.
00117     \param available_modulations A bitwise list of the modulation schemes to be
00118            advertised as available here.
00119     \param result_handler The callback routine used to handle the results of negotiation.
00120     \param user_data An opaque pointer passed to the result_handler routine.
00121     \return A pointer to the V.8 context, or NULL if there was a problem. */
00122 v8_state_t *v8_init(v8_state_t *s,
00123                     int caller,
00124                     int available_modulations,
00125                     v8_result_handler_t *result_handler,
00126                     void *user_data);
00127 
00128 /*! Release a V.8 context.
00129     \brief Release a V.8 context.
00130     \param s The V.8 context.
00131     \return 0 for OK. */
00132 int v8_release(v8_state_t *s);
00133 
00134 /*! Generate a block of V.8 audio samples.
00135     \brief Generate a block of V.8 audio samples.
00136     \param s The V.8 context.
00137     \param amp The audio sample buffer.
00138     \param max_len The number of samples to be generated.
00139     \return The number of samples actually generated.
00140 */
00141 int v8_tx(v8_state_t *s, int16_t *amp, int max_len);
00142 
00143 /*! Process a block of received V.8 audio samples.
00144     \brief Process a block of received V.8 audio samples.
00145     \param s The V.8 context.
00146     \param amp The audio sample buffer.
00147     \param len The number of samples in the buffer.
00148 */
00149 int v8_rx(v8_state_t *s, const int16_t *amp, int len);
00150 
00151 /*! Log the list of supported modulations.
00152     \brief Log the list of supported modulations.
00153     \param s The V.8 context.
00154     \param modulation_schemes The list of supported modulations. */
00155 void v8_log_supported_modulations(v8_state_t *s, int modulation_schemes);
00156 
00157 /*! Log the selected modulation.
00158     \brief Log the selected modulation.
00159     \param s The V.8 context.
00160     \param modulation_scheme The selected modulation. */
00161 void v8_log_selected_modulation(v8_state_t *s, int modulation_scheme);
00162 
00163 #ifdef __cplusplus
00164 }
00165 #endif
00166 
00167 #endif
00168 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1