spandsp: v8.h Source File

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?
30The V.8 specification defines a procedure to be used as PSTN modem answer phone calls,
31which allows the modems to negotiate the optimum modem standard, which both ends can
32support.
33
34\section v8_page_sec_2 How does it work?
35At startup the modems communicate using the V.21 standard at 300 bits/second. They
36exchange simple messages about their capabilities, and choose the modem standard they
37will use for data communication. The V.8 protocol then terminates, and the modems
38being negotiating and training with their chosen modem standard.
39*/
40
41#if !defined(_SPANDSP_V8_H_)
42#define _SPANDSP_V8_H_
43
44typedef struct v8_parms_s v8_parms_t;
45
46typedef void (*v8_result_handler_t)(void *user_data, v8_parms_t *result);
47
48enum 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
60enum 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
78enum v8_protocol_e
79{
80 V8_PROTOCOL_NONE = 0,
81 V8_PROTOCOL_LAPM_V42 = 1,
82 V8_PROTOCOL_EXTENSION = 7
83};
84
85enum 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
92enum 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
99 enum v8_status_e
100{
101 /*! V.8 negotiation is in progress. */
102 V8_STATUS_IN_PROGRESS = 0,
103 /*! V.8 has been offered by the other (calling) party. */
104 V8_STATUS_V8_OFFERED = 1,
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. */
108 V8_STATUS_V8_CALL = 2,
109 /*! A non-V.8 is being received. */
110 V8_STATUS_NON_V8_CALL = 3,
111 /*! V.8 negotiation failed. */
112 V8_STATUS_FAILED = 4
113};
114
115typedef struct v8_state_s v8_state_t;
116
117 struct v8_parms_s
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)
133extern "C"
134{
135#endif
136
137SPAN_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. */
149SPAN_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. */
159SPAN_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. */
165SPAN_DECLARE(int) v8_free(v8_state_t *s);
166
167SPAN_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. */
190SPAN_DECLARE(void) v8_log_supported_modulations(v8_state_t *s, int modulation_schemes);
191
192SPAN_DECLARE(const char *) v8_call_function_to_str(int call_function);
193SPAN_DECLARE(const char *) v8_modulation_to_str(int modulation_scheme);
194SPAN_DECLARE(const char *) v8_protocol_to_str(int protocol);
195SPAN_DECLARE(const char *) v8_pstn_access_to_str(int pstn_access);
196SPAN_DECLARE(const char *) v8_nsf_to_str(int nsf);
197SPAN_DECLARE(const char *) v8_pcm_modem_availability_to_str(int pcm_modem_availability);
198SPAN_DECLARE(const char *) v8_t66_to_str(int t66);
199
200#if defined(__cplusplus)
201}
202#endif
203
204#endif
205/*- End of file ------------------------------------------------------------*/
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(void) async_rx_put_bit(void *user_data
Accept a bit from a received serial bit stream.
logging_state_t
struct logging_state_s logging_state_t
Definition logging.h:75
v8_parms_s
Definition v8.h:118
v8_state_s
Definition private/v8.h:30
v8_release
int v8_release(v8_state_t *s)
Release a V.8 context.
Definition v8.c:1095
v8_free
int v8_free(v8_state_t *s)
Release a V.8 context.
Definition v8.c:1101
v8_log_supported_modulations
void v8_log_supported_modulations(v8_state_t *s, int modulation_schemes)
Log the list of supported modulations.
Definition v8.c:270
v8_init
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
v8_status_e
v8_status_e
Definition v8.h:100
V8_STATUS_NON_V8_CALL
@ V8_STATUS_NON_V8_CALL
Definition v8.h:110
V8_STATUS_IN_PROGRESS
@ V8_STATUS_IN_PROGRESS
Definition v8.h:102
V8_STATUS_V8_OFFERED
@ V8_STATUS_V8_OFFERED
Definition v8.h:104
V8_STATUS_FAILED
@ V8_STATUS_FAILED
Definition v8.h:112
V8_STATUS_V8_CALL
@ V8_STATUS_V8_CALL
Definition v8.h:108