spandsp  0.0.6
v8.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * v8.h - V.8 modem negotiation processing.
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2004 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 /*! \file */
27 
28 /*! \page v8_page The V.8 modem negotiation protocol
29 \section v8_page_sec_1 What does it do?
30 The V.8 specification defines a procedure to be used as PSTN modem answer phone calls,
31 which allows the modems to negotiate the optimum modem standard, which both ends can
32 support.
33 
34 \section v8_page_sec_2 How does it work?
35 At startup the modems communicate using the V.21 standard at 300 bits/second. They
36 exchange simple messages about their capabilities, and choose the modem standard they
37 will use for data communication. The V.8 protocol then terminates, and the modems
38 being negotiating and training with their chosen modem standard.
39 */
40 
41 #if !defined(_SPANDSP_V8_H_)
42 #define _SPANDSP_V8_H_
43 
44 typedef struct v8_parms_s v8_parms_t;
45 
46 typedef void (*v8_result_handler_t)(void *user_data, v8_parms_t *result);
47 
48 enum v8_call_function_e
49 {
50  V8_CALL_TBS = 0,
51  V8_CALL_H324 = 1,
52  V8_CALL_V18 = 2,
53  V8_CALL_T101 = 3,
54  V8_CALL_T30_TX = 4,
55  V8_CALL_T30_RX = 5,
56  V8_CALL_V_SERIES = 6,
57  V8_CALL_FUNCTION_EXTENSION = 7
58 };
59 
60 enum v8_modulation_e
61 {
62  V8_MOD_V17 = (1 << 0), /* V.17 half-duplex */
63  V8_MOD_V21 = (1 << 1), /* V.21 duplex */
64  V8_MOD_V22 = (1 << 2), /* V.22/V22.bis duplex */
65  V8_MOD_V23HDX = (1 << 3), /* V.23 half-duplex */
66  V8_MOD_V23 = (1 << 4), /* V.23 duplex */
67  V8_MOD_V26BIS = (1 << 5), /* V.23 duplex */
68  V8_MOD_V26TER = (1 << 6), /* V.23 duplex */
69  V8_MOD_V27TER = (1 << 7), /* V.23 duplex */
70  V8_MOD_V29 = (1 << 8), /* V.29 half-duplex */
71  V8_MOD_V32 = (1 << 9), /* V.32/V32.bis duplex */
72  V8_MOD_V34HDX = (1 << 10), /* V.34 half-duplex */
73  V8_MOD_V34 = (1 << 11), /* V.34 duplex */
74  V8_MOD_V90 = (1 << 12), /* V.90 duplex */
75  V8_MOD_V92 = (1 << 13) /* V.92 duplex */
76 };
77 
78 enum v8_protocol_e
79 {
80  V8_PROTOCOL_NONE = 0,
81  V8_PROTOCOL_LAPM_V42 = 1,
82  V8_PROTOCOL_EXTENSION = 7
83 };
84 
85 enum v8_pstn_access_e
86 {
87  V8_PSTN_ACCESS_CALL_DCE_CELLULAR = 0x01,
88  V8_PSTN_ACCESS_ANSWER_DCE_CELLULAR = 0x02,
89  V8_PSTN_ACCESS_DCE_ON_DIGITAL = 0x04
90 };
91 
92 enum v8_pcm_modem_availability_e
93 {
94  V8_PSTN_PCM_MODEM_V90_V92_ANALOGUE = 0x01,
95  V8_PSTN_PCM_MODEM_V90_V92_DIGITAL = 0x02,
96  V8_PSTN_PCM_MODEM_V91 = 0x04
97 };
98 
100 {
101  /*! V.8 negotiation is in progress. */
103  /*! V.8 has been offered by the other (calling) party. */
105  /*! V.8 has been successfully negotiated. Note that this only means the V.8
106  message exchange has successfully completed. The actual exchanged parameters
107  must be checked, to see if the call can proceed properly. */
109  /*! A non-V.8 is being received. */
111  /*! V.8 negotiation failed. */
113 };
114 
115 typedef struct v8_state_s v8_state_t;
116 
118 {
119  int status;
120  int modem_connect_tone;
121  int send_ci;
122  int v92;
123  int call_function;
124  unsigned int modulations;
125  int protocol;
126  int pstn_access;
127  int pcm_modem_availability;
128  int nsf;
129  int t66;
130 };
131 
132 #if defined(__cplusplus)
133 extern "C"
134 {
135 #endif
136 
137 SPAN_DECLARE(int) v8_restart(v8_state_t *s,
138  int calling_party,
139  v8_parms_t *parms);
140 
141 /*! Initialise a V.8 context.
142  \brief Initialise a V.8 context.
143  \param s The V.8 context.
144  \param calling_party TRUE if caller mode, else answerer mode.
145  \param parms The allowed parameters for the call.
146  \param result_handler The callback routine used to handle the results of negotiation.
147  \param user_data An opaque pointer passed to the result_handler routine.
148  \return A pointer to the V.8 context, or NULL if there was a problem. */
149 SPAN_DECLARE(v8_state_t *) v8_init(v8_state_t *s,
150  int calling_party,
151  v8_parms_t *parms,
152  v8_result_handler_t result_handler,
153  void *user_data);
154 
155 /*! Release a V.8 context.
156  \brief Release a V.8 context.
157  \param s The V.8 context.
158  \return 0 for OK. */
159 SPAN_DECLARE(int) v8_release(v8_state_t *s);
160 
161 /*! Free a V.8 context.
162  \brief Release a V.8 context.
163  \param s The V.8 context.
164  \return 0 for OK. */
165 SPAN_DECLARE(int) v8_free(v8_state_t *s);
166 
167 SPAN_DECLARE(logging_state_t *) v8_get_logging_state(v8_state_t *s);
168 
169 /*! Generate a block of V.8 audio samples.
170  \brief Generate a block of V.8 audio samples.
171  \param s The V.8 context.
172  \param amp The audio sample buffer.
173  \param max_len The number of samples to be generated.
174  \return The number of samples actually generated.
175 */
176 SPAN_DECLARE_NONSTD(int) v8_tx(v8_state_t *s, int16_t *amp, int max_len);
177 
178 /*! Process a block of received V.8 audio samples.
179  \brief Process a block of received V.8 audio samples.
180  \param s The V.8 context.
181  \param amp The audio sample buffer.
182  \param len The number of samples in the buffer.
183 */
184 SPAN_DECLARE_NONSTD(int) v8_rx(v8_state_t *s, const int16_t *amp, int len);
185 
186 /*! Log the list of supported modulations.
187  \brief Log the list of supported modulations.
188  \param s The V.8 context.
189  \param modulation_schemes The list of supported modulations. */
190 SPAN_DECLARE(void) v8_log_supported_modulations(v8_state_t *s, int modulation_schemes);
191 
192 SPAN_DECLARE(const char *) v8_call_function_to_str(int call_function);
193 SPAN_DECLARE(const char *) v8_modulation_to_str(int modulation_scheme);
194 SPAN_DECLARE(const char *) v8_protocol_to_str(int protocol);
195 SPAN_DECLARE(const char *) v8_pstn_access_to_str(int pstn_access);
196 SPAN_DECLARE(const char *) v8_nsf_to_str(int nsf);
197 SPAN_DECLARE(const char *) v8_pcm_modem_availability_to_str(int pcm_modem_availability);
198 SPAN_DECLARE(const char *) v8_t66_to_str(int t66);
199 
200 #if defined(__cplusplus)
201 }
202 #endif
203 
204 #endif
205 /*- End of file ------------------------------------------------------------*/
Definition: v8.h:112
v8_status_e
Definition: v8.h:99
Definition: v8.h:104
void v8_log_supported_modulations(v8_state_t *s, int modulation_schemes)
Log the list of supported modulations.
Definition: v8.c:270
int v8_free(v8_state_t *s)
Release a V.8 context.
Definition: v8.c:1101
SPAN_DECLARE_NONSTD(int) v8_tx(v8_state_t *s
Generate a block of V.8 audio samples.
Definition: v8.h:110
Definition: v8.h:102
Definition: v8.h:108
Definition: private/logging.h:33
v8_state_t * v8_init(v8_state_t *s, int calling_party, v8_parms_t *parms, v8_result_handler_t result_handler, void *user_data)
Initialise a V.8 context.
Definition: v8.c:1073
Definition: v8.h:117
Definition: private/v8.h:29
int v8_release(v8_state_t *s)
Release a V.8 context.
Definition: v8.c:1095