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 /*! Get the logging context associated with an ADSI receive context.
394  \brief Get the logging context associated with an ADSI receive context.
395  \param s The ADSI receive context.
396  \return A pointer to the logging context */
398 
399 /*! \brief Initialise an ADSI receive context.
400  \param s The ADSI receive context.
401  \param standard The code for the ADSI standard to be used.
402  \param put_msg A callback routine called to deliver the received messages
403  to the application.
404  \param user_data An opaque pointer for the callback routine.
405  \return A pointer to the initialised context, or NULL if there was a problem.
406 */
407 SPAN_DECLARE(adsi_rx_state_t *) adsi_rx_init(adsi_rx_state_t *s,
408  int standard,
409  put_msg_func_t put_msg,
410  void *user_data);
411 
412 /*! \brief Release an ADSI receive context.
413  \param s The ADSI receive context.
414  \return 0 for OK.
415 */
416 SPAN_DECLARE(int) adsi_rx_release(adsi_rx_state_t *s);
417 
418 /*! \brief Free the resources of an ADSI receive context.
419  \param s The ADSI receive context.
420  \return 0 for OK.
421 */
422 SPAN_DECLARE(int) adsi_rx_free(adsi_rx_state_t *s);
423 
424 /*! \brief Receive a chunk of ADSI audio.
425  \param s The ADSI receive context.
426  \param amp The audio sample buffer.
427  \param len The number of samples in the buffer.
428  \return The number of samples unprocessed.
429 */
430 SPAN_DECLARE(int) adsi_rx(adsi_rx_state_t *s, const int16_t amp[], int len);
431 
432 /*! \brief Initialise an ADSI transmit context.
433  \param s The ADSI transmit context.
434  \param standard The code for the ADSI standard to be used.
435  \return A pointer to the initialised context, or NULL if there was a problem.
436 */
437 SPAN_DECLARE(adsi_tx_state_t *) adsi_tx_init(adsi_tx_state_t *s, int standard);
438 
439 /*! \brief Release an ADSI transmit context.
440  \param s The ADSI transmit context.
441  \return 0 for OK.
442 */
443 SPAN_DECLARE(int) adsi_tx_release(adsi_tx_state_t *s);
444 
445 /*! \brief Free the resources of an ADSI transmit context.
446  \param s The ADSI transmit context.
447  \return 0 for OK.
448 */
449 SPAN_DECLARE(int) adsi_tx_free(adsi_tx_state_t *s);
450 
451 /*! \brief Adjust the preamble associated with an ADSI transmit context.
452  \param s The ADSI transmit context.
453  \param preamble_len The number of bits of preamble.
454  \param preamble_ones_len The number of bits of continuous one before a message.
455  \param postamble_ones_len The number of bits of continuous one after a message.
456  \param stop_bits The number of stop bits per character.
457 */
458 SPAN_DECLARE(void) adsi_tx_set_preamble(adsi_tx_state_t *s,
459  int preamble_len,
460  int preamble_ones_len,
461  int postamble_ones_len,
462  int stop_bits);
463 
464 /*! \brief Generate a block of ADSI audio samples.
465  \param s The ADSI transmit context.
466  \param amp The audio sample buffer.
467  \param max_len The number of samples to be generated.
468  \return The number of samples actually generated.
469 */
470 SPAN_DECLARE(int) adsi_tx(adsi_tx_state_t *s, int16_t amp[], int max_len);
471 
472 /*! \brief Request generation of an ADSI alert tone.
473  \param s The ADSI transmit context.
474 */
475 SPAN_DECLARE(void) adsi_tx_send_alert_tone(adsi_tx_state_t *s);
476 
477 /*! \brief Put a message into the input buffer of an ADSI transmit context.
478  \param s The ADSI transmit context.
479  \param msg The message.
480  \param len The length of the message.
481  \return The length actually added. If a message is already in progress
482  in the transmitter, this function will return zero, as it will
483  not successfully add the message to the buffer. If the message is
484  invalid (e.g. it is too long), this function will return -1.
485 */
486 SPAN_DECLARE(int) adsi_tx_put_message(adsi_tx_state_t *s, const uint8_t *msg, int len);
487 
488 /*! \brief Get a field from an ADSI message.
489  \param s The ADSI receive context.
490  \param msg The message buffer.
491  \param msg_len The length of the message.
492  \param pos Current position within the message. Set to -1 when starting a message.
493  \param field_type The type code for the field.
494  \param field_body Pointer to the body of the field.
495  \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
496 */
497 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);
498 
499 /*! \brief Insert the header or a field into an ADSI message.
500  \param s The ADSI transmit context.
501  \param msg The message buffer.
502  \param len The current length of the message.
503  \param field_type The type code for the new field.
504  \param field_body Pointer to the body of the new field.
505  \param field_len The length of the new field.
506 */
507 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);
508 
509 /*! \brief Return a short name for an ADSI standard
510  \param standard The code for the standard.
511  \return A pointer to the name.
512 */
513 SPAN_DECLARE(const char *) adsi_standard_to_str(int standard);
514 
515 #if defined(__cplusplus)
516 }
517 #endif
518 
519 #endif
520 /*- End of file ------------------------------------------------------------*/
Definition: adsi.h:350
Definition: adsi.h:285
int adsi_rx_release(adsi_rx_state_t *s)
Release an ADSI receive context.
Definition: adsi.c:465
Definition: adsi.h:301
Definition: adsi.h:237
Definition: adsi.h:321
void(* put_msg_func_t)(void *user_data, const uint8_t *msg, int len)
Definition: async.h:93
Definition: adsi.h:329
Definition: adsi.h:218
void adsi_tx_send_alert_tone(adsi_tx_state_t *s)
Request generation of an ADSI alert tone.
Definition: adsi.c:506
Definition: adsi.h:289
Definition: adsi.h:235
Definition: adsi.h:291
Definition: adsi.h:299
Definition: adsi.h:297
Definition: adsi.h:275
int adsi_tx_free(adsi_tx_state_t *s)
Free the resources of an ADSI transmit context.
Definition: adsi.c:692
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:512
Definition: adsi.h:271
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:427
Definition: adsi.h:287
Definition: adsi.h:260
Definition: adsi.h:327
int adsi_tx(adsi_tx_state_t *s, int16_t amp[], int max_len)
Generate a block of ADSI audio samples.
Definition: adsi.c:478
Definition: adsi.h:254
Definition: adsi.h:281
logging_state_t * adsi_rx_get_logging_state(adsi_rx_state_t *s)
Get the logging context associated with an ADSI receive context.
Definition: adsi.c:421
Definition: adsi.h:325
Definition: adsi.h:241
Definition: adsi.h:303
adsi_tx_state_t * adsi_tx_init(adsi_tx_state_t *s, int standard)
Initialise an ADSI transmit context.
Definition: adsi.c:660
int adsi_tx_release(adsi_tx_state_t *s)
Release an ADSI transmit context.
Definition: adsi.c:686
const char * adsi_standard_to_str(int standard)
Return a short name for an ADSI standard.
Definition: adsi.c:1103
Definition: adsi.h:312
Definition: adsi.h:344
Definition: adsi.h:295
Definition: adsi.h:319
Definition: adsi.h:258
Definition: adsi.h:352
Definition: adsi.h:333
Definition: adsi.h:331
Definition: adsi.h:216
Definition: adsi.h:229
Definition: adsi.h:227
Definition: adsi.h:348
Definition: adsi.h:243
Definition: private/logging.h:33
Definition: adsi.h:273
Definition: adsi.h:279
Definition: adsi.h:256
Definition: adsi.h:310
Definition: adsi.h:231
Definition: adsi.h:283
Definition: adsi.h:220
Definition: adsi.h:346
Definition: adsi.h:214
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:881
Definition: private/adsi.h:83
Definition: adsi.h:277
Definition: adsi.h:269
int adsi_rx_free(adsi_rx_state_t *s)
Free the resources of an ADSI receive context.
Definition: adsi.c:471
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:1001
int adsi_rx(adsi_rx_state_t *s, const int16_t amp[], int len)
Receive a chunk of ADSI audio.
Definition: adsi.c:402
Definition: adsi.h:323
Definition: adsi.h:239
Definition: private/adsi.h:35
Definition: adsi.h:293
Definition: adsi.h:233
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:565
Definition: adsi.h:267