Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/adsi.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.6pre17
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 15:50:58 +0200
parents
children
comparison
equal deleted inserted replaced
3:c6c5a16ce2f2 4:26cd8f1ef0b1
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 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 * $Id: adsi.h,v 1.40 2009/05/22 16:39:01 steveu Exp $
26 */
27
28 /*! \file */
29
30 #if !defined(_SPANDSP_ADSI_H_)
31 #define _SPANDSP_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
41 - Bellcore/Telcordia GR-30 CORE CLASS (Custom Local Area Signaling Services) standard
42 (North America, Australia, China, Taiwan, and Hong Kong).
43
44 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) FSK standard
45 (France, Germany, Norway, Italy, Spain, South Africa, Turkey, and the UK).
46
47 - ETSI Caller-ID support for the UK, British Telecom SIN227 and SIN242.
48
49 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
50 variant 1 (Belgium, Brazil, Denmark, Finland, Iceland, India, Netherlands, Saudi Arabia,
51 Sweden and Uruguay).
52
53 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
54 variant 2 (Denmark and Holland).
55
56 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
57 variant 3.
58
59 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
60 variant 4. (Taiwan and Kuwait).
61
62 - ETSI Caller-ID support in UK (British Telecom), British Telecomm SIN227, SIN242.
63
64 - Nippon Telegraph & Telephone Corporation JCLIP (Japanese Calling Line Identity
65 Presentation) standard.
66
67 - Telecommunications Authority of Singapore ACLIP (Analog Calling Line Identity
68 Presentation) standard.
69
70 - TDD (Telecommunications Device for the Deaf).
71
72 \section adsi_page_sec_2 How does it work?
73
74 \section adsi_page_sec_2a The Bellcore CLASS specification
75 Most FSK based CLI formats are similar to the US CLASS one, which is as follows:
76
77 The alert tone for CLI during a call is at least 100ms of silence, then
78 2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time,
79 this tone is not sent. In the US, CLI is usually sent between the first
80 two rings. This silence period is long in the US, so the message fits easily.
81 In other places, where the standard ring tone has much smaller silences,
82 a line voltage reversal is used to wake up a power saving receiver, then the
83 message is sent, then the phone begins to ring.
84
85 The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits
86 per second. The message protocol uses 8-bit data words (bytes), each bounded
87 by a start bit and a stop bit.
88
89 Channel Carrier Message Message Data Checksum
90 Seizure Signal Type Length Word(s) Word
91 Signal Word Word
92
93 \section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL
94 The channel seizure is 30 continuous bytes of 55h (01010101), including
95 the start and stop bits (i.e. 300 bits of alternations in total).
96 This provides a detectable alternating function to the CPE (i.e. the
97 modem data pump).
98
99 \section adsi_page_sec_2a2 CARRIER SIGNAL
100 The carrier signal consists of 180 bits of 1s. This may be reduced to 80
101 bits of 1s for caller ID on call waiting.
102
103 \section adsi_page_sec_2a3 MESSAGE TYPE WORD
104 Various message types are defined. The commonest ones for the US CLASS
105 standard are:
106
107 - Type 0x04 (SDMF) - single data message. Simple caller ID (CND)
108 - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID,
109 with extra information.
110
111 Other messages support message waiting, for voice mail, and other display features.
112
113 \section adsi_page_sec_2a4 MESSAGE LENGTH WORD
114 The message length word specifies the total number of data words
115 to follow.
116
117 \section adsi_page_sec_2a5 DATA WORDS
118 The data words contain the actual message.
119
120 \section adsi_page_sec_2a6 CHECKSUM WORD
121 The Checksum Word contains the twos complement of the modulo 256
122 sum of the other words in the data message (i.e., message type,
123 message length, and data words). The receiving equipment may
124 calculate the modulo 256 sum of the received words and add this
125 sum to the received checksum word. A result of zero generally
126 indicates that the message was correctly received. Message
127 retransmission is not supported. The sumcheck word should be followed
128 by a minimum of two stop bits.
129
130 \section adsi_page_sec_2b The ETSI CLIP specification
131 The ETSI CLIP specification uses similar messages to the Bellcore specification.
132 They are not, however, identical. First, ETSI use the V.23 modem standard, rather
133 than Bell 202. Second, different fields, and different message types are available.
134
135 The wake up indication generally differs from the Bellcore specification, to
136 accomodate differences in European ring cadences.
137
138 \section adsi_page_sec_2c The ETSI caller ID by DTMF specification
139 CLI by DTMF is usually sent in a very simple way. The exchange does not give
140 any prior warning (no reversal, or ring) to wake up the receiver. It just
141 sends a string of DTMF digits. Around the world several variants of this
142 basic scheme are used.
143
144 One variant of the digit string is used in Belgium, Brazil, Denmark, Finland, Iceland,
145 India, Netherlands, Saudi Arabia, Sweden and Uruguay:
146
147 - A<caller's phone number>D<redirected number>B<special information>C
148
149 Each of these fields may be omitted. The following special information codes are defined
150
151 - "00" indicates the calling party number is not available.
152 - "10" indicates that the presentation of the calling party number is restricted.
153
154 A second variant of the digit string is one of the following:
155
156 - A<caller's phone number>#
157 - D1# Number not available because the caller has restricted it.
158 - D2# Number not available because the call is international.
159 - D3# Number not available due to technical reasons.
160
161 A third variant of the digit string is used in Taiwan and Kuwait:
162
163 - D<caller's phone number>C
164
165 A forth variant of the digit string is used in Denmark and Holland:
166
167 - <caller's phone number>#
168
169 There is no distinctive start marker in this format.
170
171 \section adsi_page_sec_2d The Japanese specification from NTT
172
173 The Japanese caller ID specification is considerably different from any of the others. It
174 uses V.23 modem signals, but the message structure is uniqeue. Also, the message is delivered
175 while off hook. This results in a sequence
176
177 - The phone line rings
178 - CPE answers and waits for the caller ID message
179 - CPE hangs up on receipt of the caller ID message
180 - The phone line rings a second time
181 - The CPE answers a second time, connecting the called party with the caller.
182
183 Timeouts are, obviously, required to ensure this system behaves well when the caller ID message
184 or the second ring are missing.
185 */
186
187 enum
188 {
189 ADSI_STANDARD_NONE = 0,
190 ADSI_STANDARD_CLASS = 1,
191 ADSI_STANDARD_CLIP = 2,
192 ADSI_STANDARD_ACLIP = 3,
193 ADSI_STANDARD_JCLIP = 4,
194 ADSI_STANDARD_CLIP_DTMF = 5,
195 ADSI_STANDARD_TDD = 6
196 };
197
198 /* In some of the messages code characters are used, as follows:
199 'C' for public callbox
200 'L' for long distance
201 'O' for overseas
202 'P' for private
203 'S' for service conflict
204
205 Taiwan and Kuwait change this pattern to:
206 'C' for coin/public callbox
207 'I' for international call
208 'O' for out of area call
209 'P' for private
210 */
211
212 /*! Definitions for CLASS (Custom Local Area Signaling Services) */
213 enum
214 {
215 /*! Single data message caller ID */
216 CLASS_SDMF_CALLERID = 0x04,
217 /*! Multiple data message caller ID */
218 CLASS_MDMF_CALLERID = 0x80,
219 /*! Single data message message waiting */
220 CLASS_SDMF_MSG_WAITING = 0x06,
221 /*! Multiple data message message waiting */
222 CLASS_MDMF_MSG_WAITING = 0x82
223 };
224
225 /*! CLASS MDMF message IDs */
226 enum
227 {
228 /*! Date and time (MMDDHHMM) */
229 MCLASS_DATETIME = 0x01,
230 /*! Caller number */
231 MCLASS_CALLER_NUMBER = 0x02,
232 /*! Dialed number */
233 MCLASS_DIALED_NUMBER = 0x03,
234 /*! Caller number absent: 'O' or 'P' */
235 MCLASS_ABSENCE1 = 0x04,
236 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
237 MCLASS_REDIRECT = 0x05,
238 /*! Long distance: 'L' */
239 MCLASS_QUALIFIER = 0x06,
240 /*! Caller's name */
241 MCLASS_CALLER_NAME = 0x07,
242 /*! Caller's name absent: 'O' or 'P' */
243 MCLASS_ABSENCE2 = 0x08,
244 /*! Alternate route */
245 MCLASS_ALT_ROUTE = 0x09
246 };
247
248 /*! CLASS MDMF message waiting message IDs */
249 /*! Message waiting/not waiting */
250 #define MCLASS_VISUAL_INDICATOR 0x0B
251
252 /*! Definitions for CLIP (Calling Line Identity Presentation) (from ETS 300 659-1) */
253 enum
254 {
255 /*! Multiple data message caller ID */
256 CLIP_MDMF_CALLERID = 0x80,
257 /*! Multiple data message message waiting */
258 CLIP_MDMF_MSG_WAITING = 0x82,
259 /*! Multiple data message charge information */
260 CLIP_MDMF_CHARGE_INFO = 0x86,
261 /*! Multiple data message SMS */
262 CLIP_MDMF_SMS = 0x89
263 };
264
265 /*! CLIP message IDs (from ETS 300 659-1) */
266 enum
267 {
268 /*! Date and time (MMDDHHMM) */
269 CLIP_DATETIME = 0x01,
270 /*! Caller number (AKA calling line identity) */
271 CLIP_CALLER_NUMBER = 0x02,
272 /*! Dialed number (AKA called line identity) */
273 CLIP_DIALED_NUMBER = 0x03,
274 /*! Caller number absent: 'O' or 'P' (AKA reason for absence of calling line identity) */
275 CLIP_ABSENCE1 = 0x04,
276 /*! Caller's name (AKA calling party name) */
277 CLIP_CALLER_NAME = 0x07,
278 /*! Caller's name absent: 'O' or 'P' (AKA reason for absence of calling party name) */
279 CLIP_ABSENCE2 = 0x08,
280 /*! Visual indicator */
281 CLIP_VISUAL_INDICATOR = 0x0B,
282 /*! Message ID */
283 CLIP_MESSAGE_ID = 0x0D,
284 /*! Complementary calling line identity */
285 CLIP_COMPLEMENTARY_CALLER_NUMBER = 0x10,
286 /*! Call type - voice call (1), ring-back-when-free call (2), calling name delivery (3) or msg waiting call(0x81) */
287 CLIP_CALLTYPE = 0x11,
288 /*! Number of messages */
289 CLIP_NUM_MSG = 0x13,
290 /*! Type of forwarded call */
291 CLIP_TYPE_OF_FORWARDED_CALL = 0x15,
292 /*! Type of calling user */
293 CLIP_TYPE_OF_CALLING_USER = 0x16,
294 /*! Redirecting number */
295 CLIP_REDIR_NUMBER = 0x1A,
296 /*! Charge */
297 CLIP_CHARGE = 0x20,
298 /*! Duration of the call */
299 CLIP_DURATION = 0x23,
300 /*! Additional charge */
301 CLIP_ADD_CHARGE = 0x21,
302 /*! Display information */
303 CLIP_DISPLAY_INFO = 0x50,
304 /*! Service information */
305 CLIP_SERVICE_INFO = 0x55
306 };
307
308 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
309 enum
310 {
311 /*! Single data message caller ID frame */
312 ACLIP_SDMF_CALLERID = 0x04,
313 /*! Multiple data message caller ID frame */
314 ACLIP_MDMF_CALLERID = 0x80
315 };
316
317 /*! A-CLIP MDM message IDs */
318 enum
319 {
320 /*! Date and time (MMDDHHMM) */
321 ACLIP_DATETIME = 0x01,
322 /*! Caller number */
323 ACLIP_CALLER_NUMBER = 0x02,
324 /*! Dialed number */
325 ACLIP_DIALED_NUMBER = 0x03,
326 /*! Caller number absent: 'O' or 'P' */
327 ACLIP_NUMBER_ABSENCE = 0x04,
328 /*! Call forward: universal, on busy, or on unanswered */
329 ACLIP_REDIRECT = 0x05,
330 /*! Long distance call: 'L' */
331 ACLIP_QUALIFIER = 0x06,
332 /*! Caller's name */
333 ACLIP_CALLER_NAME = 0x07,
334 /*! Caller's name absent: 'O' or 'P' */
335 ACLIP_NAME_ABSENCE = 0x08
336 };
337
338 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
339 /*! Multiple data message caller ID frame */
340 #define JCLIP_MDMF_CALLERID 0x40
341
342 /*! J-CLIP MDM message IDs */
343 enum
344 {
345 /*! Caller number */
346 JCLIP_CALLER_NUMBER = 0x02,
347 /*! Caller number data extension signal */
348 JCLIP_CALLER_NUM_DES = 0x21,
349 /*! Dialed number */
350 JCLIP_DIALED_NUMBER = 0x09,
351 /*! Dialed number data extension signal */
352 JCLIP_DIALED_NUM_DES = 0x22,
353 /*! Caller number absent: 'C', 'O', 'P' or 'S' */
354 JCLIP_ABSENCE = 0x04
355 };
356
357 /* Definitions for CLIP-DTMF and its variants */
358
359 /*! Caller number is '#' terminated DTMF. */
360 #define CLIP_DTMF_HASH_TERMINATED '#'
361 /*! Caller number is 'C' terminated DTMF. */
362 #define CLIP_DTMF_C_TERMINATED 'C'
363
364 /*! Caller number */
365 #define CLIP_DTMF_HASH_CALLER_NUMBER 'A'
366 /*! Caller number absent: private (1), overseas (2) or not available (3) */
367 #define CLIP_DTMF_HASH_ABSENCE 'D'
368 /*! Caller ID field with no explicit field type */
369 #define CLIP_DTMF_HASH_UNSPECIFIED 0
370
371 /*! Caller number */
372 #define CLIP_DTMF_C_CALLER_NUMBER 'A'
373 /*! Diverting number */
374 #define CLIP_DTMF_C_REDIRECT_NUMBER 'D'
375 /*! Caller number absent: private/restricted (00) or not available (10) */
376 #define CLIP_DTMF_C_ABSENCE 'B'
377
378 /*!
379 ADSI transmitter descriptor. This contains all the state information for an ADSI
380 (caller ID, CLASS, CLIP, ACLIP) transmit channel.
381 */
382 typedef struct adsi_tx_state_s adsi_tx_state_t;
383
384 /*!
385 ADSI receiver descriptor. This contains all the state information for an ADSI
386 (caller ID, CLASS, CLIP, ACLIP, JCLIP) receive channel.
387 */
388 typedef struct adsi_rx_state_s adsi_rx_state_t;
389
390 #if defined(__cplusplus)
391 extern "C"
392 {
393 #endif
394
395 /*! \brief Initialise an ADSI receive context.
396 \param s The ADSI receive context.
397 \param standard The code for the ADSI standard to be used.
398 \param put_msg A callback routine called to deliver the received messages
399 to the application.
400 \param user_data An opaque pointer for the callback routine.
401 \return A pointer to the initialised context, or NULL if there was a problem.
402 */
403 SPAN_DECLARE(adsi_rx_state_t *) adsi_rx_init(adsi_rx_state_t *s,
404 int standard,
405 put_msg_func_t put_msg,
406 void *user_data);
407
408 /*! \brief Release an ADSI receive context.
409 \param s The ADSI receive context.
410 \return 0 for OK.
411 */
412 SPAN_DECLARE(int) adsi_rx_release(adsi_rx_state_t *s);
413
414 /*! \brief Free the resources of an ADSI receive context.
415 \param s The ADSI receive context.
416 \return 0 for OK.
417 */
418 SPAN_DECLARE(int) adsi_rx_free(adsi_rx_state_t *s);
419
420 /*! \brief Receive a chunk of ADSI audio.
421 \param s The ADSI receive context.
422 \param amp The audio sample buffer.
423 \param len The number of samples in the buffer.
424 \return The number of samples unprocessed.
425 */
426 SPAN_DECLARE(int) adsi_rx(adsi_rx_state_t *s, const int16_t amp[], int len);
427
428 /*! \brief Initialise an ADSI transmit context.
429 \param s The ADSI transmit context.
430 \param standard The code for the ADSI standard to be used.
431 \return A pointer to the initialised context, or NULL if there was a problem.
432 */
433 SPAN_DECLARE(adsi_tx_state_t *) adsi_tx_init(adsi_tx_state_t *s, int standard);
434
435 /*! \brief Release an ADSI transmit context.
436 \param s The ADSI transmit context.
437 \return 0 for OK.
438 */
439 SPAN_DECLARE(int) adsi_tx_release(adsi_tx_state_t *s);
440
441 /*! \brief Free the resources of an ADSI transmit context.
442 \param s The ADSI transmit context.
443 \return 0 for OK.
444 */
445 SPAN_DECLARE(int) adsi_tx_free(adsi_tx_state_t *s);
446
447 /*! \brief Adjust the preamble associated with an ADSI transmit context.
448 \param s The ADSI transmit context.
449 \param preamble_len The number of bits of preamble.
450 \param preamble_ones_len The number of bits of continuous one before a message.
451 \param postamble_ones_len The number of bits of continuous one after a message.
452 \param stop_bits The number of stop bits per character.
453 */
454 SPAN_DECLARE(void) adsi_tx_set_preamble(adsi_tx_state_t *s,
455 int preamble_len,
456 int preamble_ones_len,
457 int postamble_ones_len,
458 int stop_bits);
459
460 /*! \brief Generate a block of ADSI audio samples.
461 \param s The ADSI transmit context.
462 \param amp The audio sample buffer.
463 \param max_len The number of samples to be generated.
464 \return The number of samples actually generated.
465 */
466 SPAN_DECLARE(int) adsi_tx(adsi_tx_state_t *s, int16_t amp[], int max_len);
467
468 /*! \brief Request generation of an ADSI alert tone.
469 \param s The ADSI transmit context.
470 */
471 SPAN_DECLARE(void) adsi_tx_send_alert_tone(adsi_tx_state_t *s);
472
473 /*! \brief Put a message into the input buffer of an ADSI transmit context.
474 \param s The ADSI transmit context.
475 \param msg The message.
476 \param len The length of the message.
477 \return The length actually added. If a message is already in progress
478 in the transmitter, this function will return zero, as it will
479 not successfully add the message to the buffer. If the message is
480 invalid (e.g. it is too long), this function will return -1.
481 */
482 SPAN_DECLARE(int) adsi_tx_put_message(adsi_tx_state_t *s, const uint8_t *msg, int len);
483
484 /*! \brief Get a field from an ADSI message.
485 \param s The ADSI receive context.
486 \param msg The message buffer.
487 \param msg_len The length of the message.
488 \param pos Current position within the message. Set to -1 when starting a message.
489 \param field_type The type code for the field.
490 \param field_body Pointer to the body of the field.
491 \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
492 */
493 SPAN_DECLARE(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);
494
495 /*! \brief Insert the header or a field into an ADSI message.
496 \param s The ADSI transmit context.
497 \param msg The message buffer.
498 \param len The current length of the message.
499 \param field_type The type code for the new field.
500 \param field_body Pointer to the body of the new field.
501 \param field_len The length of the new field.
502 */
503 SPAN_DECLARE(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);
504
505 /*! \brief Return a short name for an ADSI standard
506 \param standard The code for the standard.
507 \return A pointer to the name.
508 */
509 SPAN_DECLARE(const char *) adsi_standard_to_str(int standard);
510
511 #if defined(__cplusplus)
512 }
513 #endif
514
515 #endif
516 /*- End of file ------------------------------------------------------------*/

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