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

Generated on 29 Jul 2015 for spandsp by  doxygen 1.6.1