Mercurial > hg > audiostuff

comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/adsi.h @ 5:f762bf195c4b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.3
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 16:00:21 +0200
parents
children
comparison
equal deleted inserted replaced
4:26cd8f1ef0b1 5:f762bf195c4b
1 /*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * adsi.h - Analogue display services interface and other call ID related handling.
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2003 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 General Public License version 2, as
14 * 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 General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 *
25 * $Id: adsi.h,v 1.15 2006/10/24 13:22:01 steveu Exp $
26 */
27
28 /*! \file */
29
30 #if !defined(_ADSI_H_)
31 #define _ADSI_H_
32
33 /*! \page adsi_page ADSI transmission and reception
34 \section adsi_page_sec_1 What does it do?
35 Although ADSI has a specific meaning in some places, the term is used here to indicate
36 any form of Analogue Display Service Interface, which includes caller ID, SMS, and others.
37
38 The ADSI module provides for the transmission and reception of ADSI messages
39 in various formats. Currently, the supported formats are:
40 - CLASS (Custom Local Area Signaling Services) standard, published by Bellcore:
41
42 - ACLIP (Analog Calling Line Identity Presentation) standard, published by the
43 Telecommunications Authority of Singapore:
44
45 - CLIP (Calling Line Identity Presentation) standard, published by ETSI.
46
47 - JCLIP (Japanese Calling Line Identity Presentation) standard, published by NTT.
48
49 - TDD (Telecommunications Device for the Deaf).
50
51 \section adsi_page_sec_2 How does it work?
52
53 \section adsi_page_sec_2a The Bellcore CLASS specification
54 Most FSK based CLI formats are similar to the US CLASS one, which is as follows:
55
56 The alert tone for CLI during a call is at least 100ms of silence, then
57 2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time,
58 this tone is not sent. In the US, CLI is usually sent between the first
59 two rings. This silence period is long in the US, so the message fits easily.
60 In other places, where the standard ring tone has much smaller silences,
61 a line voltage reversal is used to wake up a power saving receiver, then the
62 message is sent, then the phone begins to ring.
63
64 The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits
65 per second. The message protocol uses 8-bit data words (bytes), each bounded
66 by a start bit and a stop bit.
67
68 Channel Carrier Message Message Data Checksum
69 Seizure Signal Type Length Word(s) Word
70 Signal Word Word
71
72 \section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL
73 The channel seizure is 30 continuous bytes of 55h (01010101), including
74 the start and stop bits (i.e. 300 bits of alternations in total).
75 This provides a detectable alternating function to the CPE (i.e. the
76 modem data pump).
77
78 \section adsi_page_sec_2a2 CARRIER SIGNAL
79 The carrier signal consists of 180 bits of 1s. This may be reduced to 80
80 bits of 1s for caller ID on call waiting.
81
82 \section adsi_page_sec_2a3 MESSAGE TYPE WORD
83 Various message types are defined. The common ones for the US CLASS
84 standard are:
85 - Type 0x04 (SDMF) - single data message. Simple caller ID (CND)
86 - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID,
87 with extra information.
88
89 \section adsi_page_sec_2a4 MESSAGE LENGTH WORD
90 The message length word specifies the total number of data words
91 to follow.
92
93 \section adsi_page_sec_2a5 DATA WORDS
94 The data words contain the actual message.
95
96 \section adsi_page_sec_2a6 CHECKSUM WORD
97 The Checksum Word contains the twos complement of the modulo 256
98 sum of the other words in the data message (i.e., message type,
99 message length, and data words). The receiving equipment may
100 calculate the modulo 256 sum of the received words and add this
101 sum to the received checksum word. A result of zero generally
102 indicates that the message was correctly received. Message
103 retransmission is not supported. The sumcheck word should be followed
104 by a minimum of two stop bits.
105
106 \section adsi_page_sec_2b The ETSI CLIP specification
107 The ETSI CLIP specification uses similar messages to the Bellcore specification.
108 They are not, however, identical. First, ETSI use the V.23 modem standard, rather
109 than Bell 202. Second, different fields, and different message types are available.
110
111 \section adsi_page_sec_2e The ETSI caller ID by DTMF specification
112 CLI by DTMF is usually sent in a very simple way. The exchange does not give
113 any prior warning (no reversal, or ring) to wake up the receiver. It just
114 sends one of the following DTMF strings:
115
116 - A<phone number>#
117 - D1# Number not available because the caller has restricted it.
118 - D2# Number not available because the call is international.
119 - D3# Number not available due to technical reasons.
120 */
121
122 enum
123 {
124 ADSI_STANDARD_NONE = 0,
125 ADSI_STANDARD_CLASS = 1,
126 ADSI_STANDARD_CLIP = 2,
127 ADSI_STANDARD_ACLIP = 3,
128 ADSI_STANDARD_JCLIP = 4,
129 ADSI_STANDARD_CLIP_DTMF = 5,
130 ADSI_STANDARD_TDD = 6
131 };
132
133 /* In some of the messages code characters are used, as follows:
134 'C' for public callbox
135 'L' for long distance
136 'O' for overseas
137 'P' for private
138 'S' for service conflict */
139
140 /*! Definitions for generic caller ID message type IDs */
141 /*! Complete caller ID message */
142 #define CLIDINFO_CMPLT 0x100
143 /*! Date, time, phone #, name */
144 #define CLIDINFO_GENERAL 0x101
145 /*! Caller ID */
146 #define CLIDINFO_CALLID 0x102
147 /*! See frame type equates */
148 #define CLIDINFO_FRAMETYPE 0x103
149
150 /*! Definitions for CLASS (Custom Local Area Signaling Services) */
151 /*! Single data message caller ID */
152 #define CLASS_SDMF_CALLERID 0x04
153 /*! Multiple data message caller ID */
154 #define CLASS_MDMF_CALLERID 0x80
155 /*! Single data message message waiting */
156 #define CLASS_SDMF_MSG_WAITING 0x06
157 /*! Multiple data message message waiting */
158 #define CLASS_MDMF_MSG_WAITING 0x82
159
160 /*! CLASS MDMF message IDs */
161 /*! Date and time (MMDDHHMM) */
162 #define MCLASS_DATETIME 0x01
163 /*! Caller number */
164 #define MCLASS_CALLER_NUMBER 0x02
165 /*! Dialed number */
166 #define MCLASS_DIALED_NUMBER 0x03
167 /*! Caller number absent: 'O' or 'P' */
168 #define MCLASS_ABSENCE1 0x04
169 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
170 #define MCLASS_REDIRECT 0x05
171 /*! Long distance: 'L' */
172 #define MCLASS_QUALIFIER 0x06
173 /*! Caller's name */
174 #define MCLASS_CALLER_NAME 0x07
175 /*! Caller's name absent: 'O' or 'P' */
176 #define MCLASS_ABSENCE2 0x08
177
178 /*! CLASS MDMF message waiting message IDs */
179 /*! Message waiting/not waiting */
180 #define MCLASS_VISUAL_INDICATOR 0x0B
181
182 /*! Definitions for CLIP (Calling Line Identity Presentation) */
183 /*! Multiple data message caller ID */
184 #define CLIP_MDMF_CALLERID 0x80
185 /*! Multiple data message message waiting */
186 #define CLIP_MDMF_MSG_WAITING 0x82
187 /*! Multiple data message charge information */
188 #define CLIP_MDMF_CHARGE_INFO 0x86
189 /*! Multiple data message SMS */
190 #define CLIP_MDMF_SMS 0x89
191
192 /*! CLIP message IDs */
193 /*! Date and time (MMDDHHMM) */
194 #define CLIP_DATETIME 0x01
195 /*! Caller number */
196 #define CLIP_CALLER_NUMBER 0x02
197 /*! Dialed number */
198 #define CLIP_DIALED_NUMBER 0x03
199 /*! Caller number absent: 'O' or 'P' */
200 #define CLIP_ABSENCE1 0x04
201 /*! Caller's name */
202 #define CLIP_CALLER_NAME 0x07
203 /*! Caller's name absent: 'O' or 'P' */
204 #define CLIP_ABSENCE2 0x08
205 /*! Visual indicator */
206 #define CLIP_VISUAL_INDICATOR 0x0B
207 /*! Message ID */
208 #define CLIP_MESSAGE_ID 0x0D
209 /*! Voice call, ring-back-when-free call, or msg waiting call */
210 #define CLIP_CALLTYPE 0x11
211 /*! Number of messages */
212 #define CLIP_NUM_MSG 0x13
213 /*! Redirecting number */
214 #define CLIP_REDIR_NUMBER 0x03
215 /*! Charge */
216 #define CLIP_CHARGE 0x20
217 /*! Duration of the call */
218 #define CLIP_DURATION 0x23
219 /*! Additional charge */
220 #define CLIP_ADD_CHARGE 0x21
221 /*! Display information */
222 #define CLIP_DISPLAY_INFO 0x50
223 /*! Service information */
224 #define CLIP_SERVICE_INFO 0x55
225
226 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
227 /*! Single data message caller ID frame */
228 #define ACLIP_SDMF_CALLERID 0x04
229 /*! Multiple data message caller ID frame */
230 #define ACLIP_MDMF_CALLERID 0x80
231
232 /*! A-CLIP MDM message IDs */
233 /*! Date and time (MMDDHHMM) */
234 #define ACLIP_DATETIME 0x01
235 /*! Caller number */
236 #define ACLIP_CALLER_NUMBER 0x02
237 /*! Dialed number */
238 #define ACLIP_DIALED_NUMBER 0x03
239 /*! Caller number absent: 'O' or 'P' */
240 #define ACLIP_ABSENCE1 0x04
241 /*! Call forward: universal, on busy, or on unanswered */
242 #define ACLIP_REDIRECT 0x05
243 /*! Long distance call: 'L' */
244 #define ACLIP_QUALIFIER 0x06
245 /*! Caller's name */
246 #define ACLIP_CALLER_NAME 0x07
247 /*! Caller's name absent: 'O' or 'P' */
248 #define ACLIP_ABSENCE2 0x08
249
250 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
251 /*! Multiple data message caller ID frame */
252 #define JCLIP_MDMF_CALLERID 0x40
253
254 /*! J-CLIP MDM message IDs */
255 /*! Caller number */
256 #define JCLIP_CALLER_NUMBER 0x02
257 /*! Caller number data extension signal */
258 #define JCLIP_CALLER_NUM_DES 0x21
259 /*! Dialed number */
260 #define JCLIP_DIALED_NUMBER 0x09
261 /*! Dialed number data extension signal */
262 #define JCLIP_DIALED_NUM_DES 0x22
263 /*! Caller number absent: 'C', 'O', 'P' or 'S' */
264 #define JCLIP_ABSENCE 0x04
265
266 /*! Definitions for CLIP-DTMF */
267 /*! Caller number */
268 #define CLIP_DTMF_CALLER_NUMBER 'A'
269 /*! Caller number absent: private (1), overseas (2) or not available (3) */
270 #define CLIP_DTMF_ABSENCE1 'D'
271
272 /*!
273 ADSI transmitter descriptor. This contains all the state information for an ADSI
274 (caller ID, CLASS, CLIP, ACLIP) transmit channel.
275 */
276 typedef struct
277 {
278 int standard;
279
280 tone_gen_descriptor_t alert_tone_desc;
281 tone_gen_state_t alert_tone_gen;
282 fsk_tx_state_t fsktx;
283 dtmf_tx_state_t dtmftx;
284 async_tx_state_t asynctx;
285
286 int tx_signal_on;
287
288 int byteno;
289 int bitpos;
290 int bitno;
291 uint8_t msg[256];
292 int msg_len;
293 int ones_len;
294 int baudot_shift;
295
296 logging_state_t logging;
297 } adsi_tx_state_t;
298
299 /*!
300 ADSI receiver descriptor. This contains all the state information for an ADSI
301 (caller ID, CLASS, CLIP, ACLIP) receive channel.
302 */
303 typedef struct
304 {
305 put_msg_func_t put_msg;
306 void *user_data;
307 int standard;
308
309 fsk_rx_state_t fskrx;
310 dtmf_rx_state_t dtmfrx;
311 async_rx_state_t asyncrx;
312
313 int consecutive_ones;
314 int bitpos;
315 int in_progress;
316 uint8_t msg[256];
317 int msg_len;
318 int baudot_shift;
319
320 /*! A count of the framing errors. */
321 int framing_errors;
322
323 logging_state_t logging;
324 } adsi_rx_state_t;
325
326 #ifdef __cplusplus
327 extern "C" {
328 #endif
329
330 /*! \brief Initialise an ADSI receive context.
331 \param s The ADSI receive context.
332 \param standard The code for the ADSI standard to be used.
333 \param put_msg A callback routine called to deliver the received messages
334 to the application.
335 \param user_data An opaque pointer for the callback routine.
336 */
337 void adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data);
338
339 /*! \brief Receive a chunk of ADSI audio.
340 \param s The ADSI receive context.
341 \param amp The audio sample buffer.
342 \param len The number of samples in the buffer.
343 */
344 void adsi_rx(adsi_rx_state_t *s, const int16_t *amp, int len);
345
346 /*! \brief Initialise an ADSI transmit context.
347 \param s The ADSI transmit context.
348 \param standard The code for the ADSI standard to be used.
349 */
350 void adsi_tx_init(adsi_tx_state_t *s, int standard);
351
352 /*! \brief Generate a block of ADSI audio samples.
353 \param s The ADSI transmit context.
354 \param amp The audio sample buffer.
355 \param max_len The number of samples to be generated.
356 \return The number of samples actually generated.
357 */
358 int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len);
359
360 /*! \brief Request generation of an ADSI alert tone.
361 \param s The ADSI transmit context.
362 */
363 void adsi_send_alert_tone(adsi_tx_state_t *s);
364
365 /*! \brief Put a message into the input buffer of an ADSI transmit context.
366 \param s The ADSI transmit context.
367 \param msg The message.
368 \param len The length of the message.
369 \return The length actually added. If a message is already in progress
370 in the transmitter, this function will return zero, as it will
371 not successfully add the message to the buffer.
372 */
373 int adsi_put_message(adsi_tx_state_t *s, uint8_t *msg, int len);
374
375 /*! \brief Get a field from an ADSI message.
376 \param s The ADSI receive context.
377 \param msg The message buffer.
378 \param msg_len The length of the message.
379 \param pos Current position within the message. Set to -1 when starting a message.
380 \param field_type The type code for the field.
381 \param field_body Pointer to the body of the field.
382 \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
383 */
384 int adsi_next_field(adsi_rx_state_t *s, const uint8_t *msg, int msg_len, int pos, uint8_t *field_type, uint8_t const **field_body, int *field_len);
385
386 /*! \brief Insert the header or a field into an ADSI message.
387 \param s The ADSI transmit context.
388 \param msg The message buffer.
389 \param len The current length of the message.
390 \param field_type The type code for the new field.
391 \param field_body Pointer to the body of the new field.
392 \param field_len The length of the new field.
393 */
394 int adsi_add_field(adsi_tx_state_t *s, uint8_t *msg, int len, uint8_t field_type, uint8_t const *field_body, int field_len);
395
396 /*! \brief Return a short name for an ADSI standard
397 \param standard The code for the standard.
398 \return A pointer to the name.
399 */
400 const char *adsi_standard_to_str(int standard);
401
402 #ifdef __cplusplus
403 }
404 #endif
405
406 #endif
407 /*- End of file ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.