spandsp 3.0.0
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_cm_jm_parms_s v8_cm_jm_parms_t;
45
46typedef struct v8_parms_s v8_parms_t;
47
48typedef void (*v8_result_handler_t)(void *user_data, v8_parms_t *result);
49
50enum v8_call_function_e
51{
52 V8_CALL_TBS = 0,
53 V8_CALL_H324 = 1,
54 V8_CALL_V18 = 2,
55 V8_CALL_T101 = 3,
56 V8_CALL_T30_TX = 4,
57 V8_CALL_T30_RX = 5,
58 V8_CALL_V_SERIES = 6,
59 V8_CALL_FUNCTION_EXTENSION = 7
60};
61
62enum v8_modulation_e
63{
64 V8_MOD_V17 = (1 << 0), /* V.17 half-duplex */
65 V8_MOD_V21 = (1 << 1), /* V.21 duplex */
66 V8_MOD_V22 = (1 << 2), /* V.22/V22.bis duplex */
67 V8_MOD_V23HDX = (1 << 3), /* V.23 half-duplex */
68 V8_MOD_V23 = (1 << 4), /* V.23 duplex */
69 V8_MOD_V26BIS = (1 << 5), /* V.23 duplex */
70 V8_MOD_V26TER = (1 << 6), /* V.23 duplex */
71 V8_MOD_V27TER = (1 << 7), /* V.23 duplex */
72 V8_MOD_V29 = (1 << 8), /* V.29 half-duplex */
73 V8_MOD_V32 = (1 << 9), /* V.32/V32.bis duplex */
74 V8_MOD_V34HDX = (1 << 10), /* V.34 half-duplex */
75 V8_MOD_V34 = (1 << 11), /* V.34 duplex */
76 V8_MOD_V90 = (1 << 12), /* V.90 duplex */
77 V8_MOD_V92 = (1 << 13) /* V.92 duplex */
78};
79
80enum v8_protocol_e
81{
82 V8_PROTOCOL_NONE = 0,
83 V8_PROTOCOL_LAPM_V42 = 1,
84 V8_PROTOCOL_EXTENSION = 7
85};
86
87enum v8_pstn_access_e
88{
89 V8_PSTN_ACCESS_CALL_DCE_CELLULAR = 0x01,
90 V8_PSTN_ACCESS_ANSWER_DCE_CELLULAR = 0x02,
91 V8_PSTN_ACCESS_DCE_ON_DIGITAL = 0x04
92};
93
94enum v8_pcm_modem_availability_e
95{
96 V8_PSTN_PCM_MODEM_V90_V92_ANALOGUE = 0x01,
97 V8_PSTN_PCM_MODEM_V90_V92_DIGITAL = 0x02,
98 V8_PSTN_PCM_MODEM_V91 = 0x04
99};
100
102{
103 /*! V.8 negotiation is in progress. */
105 /*! V.8 has been offered by the other (calling) party (i.e. CM recognised). */
107 /*! V.8 has been successfully negotiated. Note that this only means the V.8
108 message exchange has successfully completed. The actual exchanged parameters
109 must be checked, to see if the call can proceed properly. */
111 /*! A non-V.8 is being received. */
113 /*! V.8 negotiation failed. */
115 /*! V.8 call function received (in a CI message). */
117 /*! Non-V.8 calling tone received. */
119 /*! FAX CNG tone received. */
121};
122
123typedef struct v8_state_s v8_state_t;
124
126{
127 int32_t call_function;
128 uint32_t modulations;
129 int32_t protocols;
130 int32_t pstn_access;
131 int32_t nsf;
132 int32_t pcm_modem_availability;
133 int32_t t66;
134};
135
137{
138 int status;
139 bool gateway_mode;
140 int32_t modem_connect_tone;
141 int32_t send_ci;
142 int32_t v92;
143 v8_cm_jm_parms_t jm_cm;
144};
145
146#if defined(__cplusplus)
147extern "C"
148{
149#endif
150
151/*! Continue with negotiation when in gateway mode. */
152SPAN_DECLARE(int) v8_continue(v8_state_t *s, v8_parms_t *parms);
153
154SPAN_DECLARE(int) v8_restart(v8_state_t *s,
155 bool calling_party,
156 v8_parms_t *parms);
157
158/*! Initialise a V.8 context.
159 \brief Initialise a V.8 context.
160 \param s The V.8 context.
161 \param calling_party True if caller mode, else answerer mode.
162 \param parms The allowed parameters for the call.
163 \param result_handler The callback routine used to handle the results of negotiation.
164 \param user_data An opaque pointer passed to the result_handler routine.
165 \return A pointer to the V.8 context, or NULL if there was a problem. */
166SPAN_DECLARE(v8_state_t *) v8_init(v8_state_t *s,
167 bool calling_party,
168 v8_parms_t *parms,
169 v8_result_handler_t result_handler,
170 void *user_data);
171
172/*! Release a V.8 context.
173 \brief Release a V.8 context.
174 \param s The V.8 context.
175 \return 0 for OK. */
176SPAN_DECLARE(int) v8_release(v8_state_t *s);
177
178/*! Free a V.8 context.
179 \brief Release a V.8 context.
180 \param s The V.8 context.
181 \return 0 for OK. */
182SPAN_DECLARE(int) v8_free(v8_state_t *s);
183
184SPAN_DECLARE(logging_state_t *) v8_get_logging_state(v8_state_t *s);
185
186/*! Generate a block of V.8 audio samples.
187 \brief Generate a block of V.8 audio samples.
188 \param s The V.8 context.
189 \param amp The audio sample buffer.
190 \param max_len The number of samples to be generated.
191 \return The number of samples actually generated.
192*/
193SPAN_DECLARE(int) v8_tx(v8_state_t *s, int16_t *amp, int max_len);
194
195/*! Decode a block of received V.8 audio samples. N.B. This is not the function to
196 call to run the V.8 protocol on received audio. It is for analysing audio streams,
197 to extract the V.8 messages, for monitoring or debug applications.
198 \brief Decode a block of received V.8 audio samples.
199 \param s The V.8 context.
200 \param amp The audio sample buffer.
201 \param len The number of samples in the buffer.
202*/
203SPAN_DECLARE(int) v8_decode_rx(v8_state_t *s, const int16_t *amp, int len);
204
205/*! Process a block of received V.8 audio samples.
206 \brief Process a block of received V.8 audio samples.
207 \param s The V.8 context.
208 \param amp The audio sample buffer.
209 \param len The number of samples in the buffer.
210*/
211SPAN_DECLARE(int) v8_rx(v8_state_t *s, const int16_t *amp, int len);
212
213/*! Log the list of supported modulations.
214 \brief Log the list of supported modulations.
215 \param s The V.8 context.
216 \param modulation_schemes The list of supported modulations. */
217SPAN_DECLARE(void) v8_log_supported_modulations(v8_state_t *s, int modulation_schemes);
218
219SPAN_DECLARE(const char *) v8_status_to_str(int status);
220SPAN_DECLARE(const char *) v8_call_function_to_str(int call_function);
221SPAN_DECLARE(const char *) v8_modulation_to_str(int modulation_scheme);
222SPAN_DECLARE(const char *) v8_protocol_to_str(int protocol);
223SPAN_DECLARE(const char *) v8_pstn_access_to_str(int pstn_access);
224SPAN_DECLARE(const char *) v8_nsf_to_str(int nsf);
225SPAN_DECLARE(const char *) v8_pcm_modem_availability_to_str(int pcm_modem_availability);
226SPAN_DECLARE(const char *) v8_t66_to_str(int t66);
227
228#if defined(__cplusplus)
229}
230#endif
231
232#endif
233/*- End of file ------------------------------------------------------------*/
struct logging_state_s logging_state_t
Definition logging.h:72
Definition v8.h:126
Definition v8.h:137
Definition private/v8.h:30
v8_state_t * v8_init(v8_state_t *s, bool calling_party, v8_parms_t *parms, v8_result_handler_t result_handler, void *user_data)
Initialise a V.8 context.
Definition v8.c:1378
int v8_release(v8_state_t *s)
Release a V.8 context.
Definition v8.c:1402
int v8_continue(v8_state_t *s, v8_parms_t *parms)
Definition v8.c:1307
int v8_decode_rx(v8_state_t *s, const int16_t *amp, int len)
Decode a block of received V.8 audio samples.
Definition v8.c:1006
int v8_free(v8_state_t *s)
Release a V.8 context.
Definition v8.c:1408
void v8_log_supported_modulations(v8_state_t *s, int modulation_schemes)
Log the list of supported modulations.
Definition v8.c:316
int v8_rx(v8_state_t *s, const int16_t *amp, int len)
Process a block of received V.8 audio samples.
Definition v8.c:1035
v8_status_e
Definition v8.h:102
@ V8_STATUS_CALL_FUNCTION_RECEIVED
Definition v8.h:116
@ V8_STATUS_FAX_CNG_TONE_RECEIVED
Definition v8.h:120
@ V8_STATUS_CALLING_TONE_RECEIVED
Definition v8.h:118
@ V8_STATUS_NON_V8_CALL
Definition v8.h:112
@ V8_STATUS_IN_PROGRESS
Definition v8.h:104
@ V8_STATUS_V8_OFFERED
Definition v8.h:106
@ V8_STATUS_FAILED
Definition v8.h:114
@ V8_STATUS_V8_CALL
Definition v8.h:110
int v8_tx(v8_state_t *s, int16_t *amp, int max_len)
Generate a block of V.8 audio samples.
Definition v8.c:845