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 
37 typedef struct v18_state_s v18_state_t;
38 
39 enum
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_WEITBRECHT_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_WEITBRECHT_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_WEITBRECHT_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 */
65 enum v18_autobauding_modes_e
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 enum v18_status_e
106 {
107  V18_STATUS_SWITCH_TO_NONE,
108  V18_STATUS_SWITCH_TO_WEITBRECHT_5BIT_4545,
109  V18_STATUS_SWITCH_TO_WEITBRECHT_5BIT_476,
110  V18_STATUS_SWITCH_TO_WEITBRECHT_5BIT_50,
111  V18_STATUS_SWITCH_TO_DTMF,
112  V18_STATUS_SWITCH_TO_EDT,
113  V18_STATUS_SWITCH_TO_BELL103,
114  V18_STATUS_SWITCH_TO_V23VIDEOTEX,
115  V18_STATUS_SWITCH_TO_V21TEXTPHONE,
116  V18_STATUS_SWITCH_TO_V18TEXTPHONE
117 };
118 
119 #if defined(__cplusplus)
120 extern "C"
121 {
122 #endif
123 
124 SPAN_DECLARE(logging_state_t *) v18_get_logging_state(v18_state_t *s);
125 
126 /*! Initialise a V.18 context.
127  \brief Initialise a V.18 context.
128  \param s The V.18 context.
129  \param calling_party True if caller mode, else answerer mode.
130  \param mode Mode of operation.
131  \param nation National variant for automoding.
132  \param put_msg A callback routine called to deliver the received text
133  to the application.
134  \param put_msg_user_data An opaque pointer for the put_msg callback routine.
135  \param status_handler A callback routine called to deliver status reports.
136  \param status_handler_user_data An opaque pointer for the status callback routine.
137  \return A pointer to the V.18 context, or NULL if there was a problem. */
138 SPAN_DECLARE(v18_state_t *) v18_init(v18_state_t *s,
139  bool calling_party,
140  int mode,
141  int nation,
142  span_put_msg_func_t put_msg,
143  void *put_msg_user_data,
144  span_modem_status_func_t status_handler,
145  void *status_handler_user_data);
146 
147 /*! Release a V.18 context.
148  \brief Release a V.18 context.
149  \param s The V.18 context.
150  \return 0 for OK. */
151 SPAN_DECLARE(int) v18_release(v18_state_t *s);
152 
153 /*! Free a V.18 context.
154  \brief Release a V.18 context.
155  \param s The V.18 context.
156  \return 0 for OK. */
157 SPAN_DECLARE(int) v18_free(v18_state_t *s);
158 
159 /*! Generate a block of V.18 audio samples.
160  \brief Generate a block of V.18 audio samples.
161  \param s The V.18 context.
162  \param amp The audio sample buffer.
163  \param max_len The number of samples to be generated.
164  \return The number of samples actually generated.
165 */
166 SPAN_DECLARE(int) v18_tx(v18_state_t *s, int16_t amp[], int max_len);
167 
168 /*! Process a block of received V.18 audio samples.
169  \brief Process a block of received V.18 audio samples.
170  \param s The V.18 context.
171  \param amp The audio sample buffer.
172  \param len The number of samples in the buffer.
173  \return The number of unprocessed samples.
174 */
175 SPAN_DECLARE(int) v18_rx(v18_state_t *s, const int16_t amp[], int len);
176 
177 /*! Fake processing of a missing block of received V.18 audio samples.
178  (e.g due to packet loss).
179  \brief Fake processing of a missing block of received V.18 audio samples.
180  \param s The V.18 context.
181  \param len The number of samples to fake.
182  \return The number of unprocessed samples.
183 */
184 SPAN_DECLARE(int) v18_rx_fillin(v18_state_t *s, int len);
185 
186 /*! \brief Put a string to a V.18 context's input buffer.
187  \param s The V.18 context.
188  \param msg The string to be added.
189  \param len The length of the string. If negative, the string is
190  assumed to be a NULL terminated string.
191  \return The number of characters actually added. This may be less than the
192  length of the digit string, if the buffer fills up. If the string is
193  invalid, this function will return -1. */
194 SPAN_DECLARE(int) v18_put(v18_state_t *s, const char msg[], int len);
195 
196 /*! \brief Set the stored message, as per V.18/5.2.12.1. This message may be up
197  to 80 bytes long.
198  \param s The V.18 context.
199  \param msg The string to be set.
200 */
201 SPAN_DECLARE(int) v18_set_stored_message(v18_state_t *s, const char *msg);
202 
203 /*! \brief Get the current mode of a V.18 connection.
204  \param s The V.18 context.
205  \return The mode. */
206 SPAN_DECLARE(int) v18_get_current_mode(v18_state_t *s);
207 
208 /*! \brief Return a short name for a V.18 mode
209  \param mode The code for the V.18 mode.
210  \return A pointer to the name.
211 */
212 SPAN_DECLARE(const char *) v18_mode_to_str(int mode);
213 
214 SPAN_DECLARE(const char *) v18_status_to_str(int status);
215 
216 #if defined(__cplusplus)
217 }
218 #endif
219 
220 #endif
221 /*- End of file ------------------------------------------------------------*/
bool calling_party
True if we are the calling modem.
Definition: private/v18.h:72
int v18_tx(v18_state_t *s, int16_t amp[], int max_len)
Generate a block of V.18 audio samples.
int v18_set_stored_message(v18_state_t *s, const char *msg)
Set the stored message, as per V.18/5.2.12.1. This message may be up to 80 bytes long.
Definition: v18.c:2047
void(* span_modem_status_func_t)(void *user_data, int status)
Definition: async.h:131
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:1943
void(* span_put_msg_func_t)(void *user_data, const uint8_t *msg, int len)
Definition: async.h:107
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:1874
int v18_release(v18_state_t *s)
Release a V.18 context.
Definition: v18.c:2118
Definition: private/logging.h:33
int v18_get_current_mode(v18_state_t *s)
Get the current mode of a V.18 connection.
Definition: v18.c:2019
int v18_put(v18_state_t *s, const char msg[], int len)
Put a string to a V.18 context&#39;s input buffer.
Definition: v18.c:1990
v18_state_t * v18_init(v18_state_t *s, bool calling_party, int mode, int nation, span_put_msg_func_t put_msg, void *put_msg_user_data, span_modem_status_func_t status_handler, void *status_handler_user_data)
Initialise a V.18 context.
Definition: v18.c:2054
int v18_free(v18_state_t *s)
Release a V.18 context.
Definition: v18.c:2125
const char * v18_mode_to_str(int mode)
Return a short name for a V.18 mode.
Definition: v18.c:710
Definition: private/v18.h:69