spandsp 3.0.0
v18.h
Go to the documentation of this file.
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * v18.h - V.18 text telephony for the deaf.
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2004-2009 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 v18_page The V.18 text telephony protocols
29\section v18_page_sec_1 What does it do?
30
31\section v18_page_sec_2 How does it work?
32*/
33
34#if !defined(_SPANDSP_V18_H_)
35#define _SPANDSP_V18_H_
36
37typedef struct v18_state_s v18_state_t;
38
39enum
40{
41 V18_MODE_NONE = 0x0001,
42 /* V.18 Annex A - Weitbrecht TDD at 45.45bps (US TTY), half-duplex, 5 bit baudot (USA). */
43 V18_MODE_5BIT_4545 = 0x0002,
44 /* V.18 Annex A - Weitbrecht TDD at 50bps (International TTY), half-duplex, 5 bit baudot (UK, Australia and others). */
45 V18_MODE_5BIT_50 = 0x0004,
46 /* V.18 Annex B - DTMF encoding of ASCII (Denmark, Holland and others). */
47 V18_MODE_DTMF = 0x0008,
48 /* V.18 Annex C - EDT (European Deaf Telephone) 110bps, V.21, half-duplex, ASCII (Germany, Austria, Switzerland and others). */
49 V18_MODE_EDT = 0x0010,
50 /* V.18 Annex D - 300bps, Bell 103, duplex, ASCII (USA). */
51 V18_MODE_BELL103 = 0x0020,
52 /* V.18 Annex E - 1200bps Videotex terminals, ASCII (France). */
53 V18_MODE_V23VIDEOTEX = 0x0040,
54 /* V.18 Annex F - V.21 text telephone, V.21, duplex, ASCII (Sweden, Norway and Finland). */
55 V18_MODE_V21TEXTPHONE = 0x0080,
56 /* V.18 Annex G - V.18 text telephone mode. */
57 V18_MODE_V18TEXTPHONE = 0x0100,
58 /* V.18 Annex A - Used during probing. */
59 V18_MODE_5BIT_476 = 0x0200,
60 /* Use repetitive shift characters where character set shifts are used */
61 V18_MODE_REPETITIVE_SHIFTS_OPTION = 0x1000
62};
63
64/* Automoding sequences for different countries */
65enum
66{
67 V18_AUTOMODING_GLOBAL = 0,
68
69 V18_AUTOMODING_NONE,
70
71 /* 5-bit, V.21, V.23, EDT, DTMF, Bell 103 */
72 V18_AUTOMODING_AUSTRALIA,
73 V18_AUTOMODING_IRELAND,
74
75 /* EDT, V.21, V.23, 5-bit, DTMF, Bell 103 */
76 V18_AUTOMODING_GERMANY,
77 V18_AUTOMODING_SWITZERLAND,
78 V18_AUTOMODING_ITALY,
79 V18_AUTOMODING_SPAIN,
80 V18_AUTOMODING_AUSTRIA,
81
82 /* DTMF, V.21, V.23, 5-bit, EDT, Bell 103 */
83 V18_AUTOMODING_NETHERLANDS,
84
85 /* V.21, DTMF, 5-bit, EDT, V.23, Bell 103 */
86 V18_AUTOMODING_ICELAND,
87 V18_AUTOMODING_NORWAY,
88 V18_AUTOMODING_SWEDEN,
89 V18_AUTOMODING_FINALND,
90 V18_AUTOMODING_DENMARK,
91
92 /* V.21, 5-bit, V.23, EDT, DTMF, Bell 103 */
93 V18_AUTOMODING_UK,
94
95 /* 5-bit, Bell 103, V.21, V.23, EDT, DTMF */
96 V18_AUTOMODING_USA,
97
98 /* V.23, EDT, DTMF, 5-bit, V.21, Bell 103 */
99 V18_AUTOMODING_FRANCE,
100 V18_AUTOMODING_BELGIUM,
101
102 V18_AUTOMODING_END
103};
104
105#if defined(__cplusplus)
106extern "C"
107{
108#endif
109
110SPAN_DECLARE(logging_state_t *) v18_get_logging_state(v18_state_t *s);
111
112/*! Initialise a V.18 context.
113 \brief Initialise a V.18 context.
114 \param s The V.18 context.
115 \param calling_party True if caller mode, else answerer mode.
116 \param mode Mode of operation.
117 \param nation National variant for automoding.
118 \param put_msg A callback routine called to deliver the received text
119 to the application.
120 \param user_data An opaque pointer for the callback routine.
121 \return A pointer to the V.18 context, or NULL if there was a problem. */
122SPAN_DECLARE(v18_state_t *) v18_init(v18_state_t *s,
123 bool calling_party,
124 int mode,
125 int nation,
126 put_msg_func_t put_msg,
127 void *user_data);
128
129/*! Release a V.18 context.
130 \brief Release a V.18 context.
131 \param s The V.18 context.
132 \return 0 for OK. */
133SPAN_DECLARE(int) v18_release(v18_state_t *s);
134
135/*! Free a V.18 context.
136 \brief Release a V.18 context.
137 \param s The V.18 context.
138 \return 0 for OK. */
139SPAN_DECLARE(int) v18_free(v18_state_t *s);
140
141/*! Generate a block of V.18 audio samples.
142 \brief Generate a block of V.18 audio samples.
143 \param s The V.18 context.
144 \param amp The audio sample buffer.
145 \param max_len The number of samples to be generated.
146 \return The number of samples actually generated.
147*/
148SPAN_DECLARE(int) v18_tx(v18_state_t *s, int16_t amp[], int max_len);
149
150/*! Process a block of received V.18 audio samples.
151 \brief Process a block of received V.18 audio samples.
152 \param s The V.18 context.
153 \param amp The audio sample buffer.
154 \param len The number of samples in the buffer.
155 \return The number of unprocessed samples.
156*/
157SPAN_DECLARE(int) v18_rx(v18_state_t *s, const int16_t amp[], int len);
158
159/*! Fake processing of a missing block of received V.18 audio samples.
160 (e.g due to packet loss).
161 \brief Fake processing of a missing block of received V.18 audio samples.
162 \param s The V.18 context.
163 \param len The number of samples to fake.
164 \return The number of unprocessed samples.
165*/
166SPAN_DECLARE(int) v18_rx_fillin(v18_state_t *s, int len);
167
168/*! \brief Put a string to a V.18 context's input buffer.
169 \param s The V.18 context.
170 \param msg The string to be added.
171 \param len The length of the string. If negative, the string is
172 assumed to be a NULL terminated string.
173 \return The number of characters actually added. This may be less than the
174 length of the digit string, if the buffer fills up. If the string is
175 invalid, this function will return -1. */
176SPAN_DECLARE(int) v18_put(v18_state_t *s, const char msg[], int len);
177
178/*! \brief Get the current mode of a V.18 connection.
179 \param s The V.18 context.
180 \return The mode. */
181SPAN_DECLARE(int) v18_get_current_mode(v18_state_t *s);
182
183/*! \brief Return a short name for an V.18 mode
184 \param mode The code for the V.18 mode.
185 \return A pointer to the name.
186*/
187SPAN_DECLARE(const char *) v18_mode_to_str(int mode);
188
189#if defined(__cplusplus)
190}
191#endif
192
193#endif
194/*- End of file ------------------------------------------------------------*/
void(* put_msg_func_t)(void *user_data, const uint8_t *msg, int len)
Definition async.h:95
Definition private/logging.h:34
Definition private/v18.h:30
bool calling_party
True if we are the calling modem.
Definition private/v18.h:32
int v18_free(v18_state_t *s)
Release a V.18 context.
Definition v18.c:1228
int v18_rx(v18_state_t *s, const int16_t amp[], int len)
Process a block of received V.18 audio samples.
Definition v18.c:1009
const char * v18_mode_to_str(int mode)
Return a short name for an V.18 mode.
Definition v18.c:1091
v18_state_t * v18_init(v18_state_t *s, bool calling_party, int mode, int nation, put_msg_func_t put_msg, void *user_data)
Initialise a V.18 context.
Definition v18.c:1126
int v18_rx_fillin(v18_state_t *s, int len)
Fake processing of a missing block of received V.18 audio samples.
Definition v18.c:1040
int v18_tx(v18_state_t *s, int16_t amp[], int max_len)
Generate a block of V.18 audio samples.
int v18_get_current_mode(v18_state_t *s)
Get the current mode of a V.18 connection.
int v18_put(v18_state_t *s, const char msg[], int len)
Put a string to a V.18 context's input buffer.
Definition v18.c:1071
int v18_release(v18_state_t *s)
Release a V.18 context.
Definition v18.c:1221