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