00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * adsi.h - Analogue display services interface and other call ID related handling. 00005 * 00006 * Written by Steve Underwood <steveu@coppice.org> 00007 * 00008 * Copyright (C) 2003 Steve Underwood 00009 * 00010 * All rights reserved. 00011 * 00012 * This program is free software; you can redistribute it and/or modify 00013 * it under the terms of the GNU Lesser General Public License version 2.1, 00014 * as published by the Free Software Foundation. 00015 * 00016 * This program is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 * GNU Lesser General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU Lesser General Public 00022 * License along with this program; if not, write to the Free Software 00023 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00024 * 00025 * $Id: adsi.h,v 1.31 2008/05/05 11:25:01 steveu Exp $ 00026 */ 00027 00028 /*! \file */ 00029 00030 #if !defined(_SPANDSP_ADSI_H_) 00031 #define _SPANDSP_ADSI_H_ 00032 00033 /*! \page adsi_page ADSI transmission and reception 00034 \section adsi_page_sec_1 What does it do? 00035 Although ADSI has a specific meaning in some places, the term is used here to indicate 00036 any form of Analogue Display Service Interface, which includes caller ID, SMS, and others. 00037 00038 The ADSI module provides for the transmission and reception of ADSI messages 00039 in various formats. Currently, the supported formats are: 00040 00041 - Bellcore/Telcordia GR-30 CORE CLASS (Custom Local Area Signaling Services) standard 00042 (North America, Australia, China, Taiwan, and Hong Kong). 00043 00044 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) FSK standard 00045 (France, Germany, Norway, Italy, Spain, South Africa, Turkey, and the UK). 00046 00047 - ETSI Caller-ID support for the UK, British Telecom SIN227 and SIN242. 00048 00049 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard 00050 variant 1 (Belgium, Brazil, Denmark, Finland, Iceland, India, Netherlands, Saudi Arabia, 00051 Sweden and Uruguay). 00052 00053 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard 00054 variant 2 (Denmark and Holland). 00055 00056 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard 00057 variant 3. 00058 00059 - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard 00060 variant 4. (Taiwan and Kuwait). 00061 00062 - ETSI Caller-ID support in UK (British Telecom), British Telecomm SIN227, SIN242. 00063 00064 - Nippon Telegraph & Telephone Corporation JCLIP (Japanese Calling Line Identity 00065 Presentation) standard. 00066 00067 - Telecommunications Authority of Singapore ACLIP (Analog Calling Line Identity 00068 Presentation) standard. 00069 00070 - TDD (Telecommunications Device for the Deaf). 00071 00072 \section adsi_page_sec_2 How does it work? 00073 00074 \section adsi_page_sec_2a The Bellcore CLASS specification 00075 Most FSK based CLI formats are similar to the US CLASS one, which is as follows: 00076 00077 The alert tone for CLI during a call is at least 100ms of silence, then 00078 2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time, 00079 this tone is not sent. In the US, CLI is usually sent between the first 00080 two rings. This silence period is long in the US, so the message fits easily. 00081 In other places, where the standard ring tone has much smaller silences, 00082 a line voltage reversal is used to wake up a power saving receiver, then the 00083 message is sent, then the phone begins to ring. 00084 00085 The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits 00086 per second. The message protocol uses 8-bit data words (bytes), each bounded 00087 by a start bit and a stop bit. 00088 00089 Channel Carrier Message Message Data Checksum 00090 Seizure Signal Type Length Word(s) Word 00091 Signal Word Word 00092 00093 \section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL 00094 The channel seizure is 30 continuous bytes of 55h (01010101), including 00095 the start and stop bits (i.e. 300 bits of alternations in total). 00096 This provides a detectable alternating function to the CPE (i.e. the 00097 modem data pump). 00098 00099 \section adsi_page_sec_2a2 CARRIER SIGNAL 00100 The carrier signal consists of 180 bits of 1s. This may be reduced to 80 00101 bits of 1s for caller ID on call waiting. 00102 00103 \section adsi_page_sec_2a3 MESSAGE TYPE WORD 00104 Various message types are defined. The commonest ones for the US CLASS 00105 standard are: 00106 00107 - Type 0x04 (SDMF) - single data message. Simple caller ID (CND) 00108 - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID, 00109 with extra information. 00110 00111 Other messages support message waiting, for voice mail, and other display features. 00112 00113 \section adsi_page_sec_2a4 MESSAGE LENGTH WORD 00114 The message length word specifies the total number of data words 00115 to follow. 00116 00117 \section adsi_page_sec_2a5 DATA WORDS 00118 The data words contain the actual message. 00119 00120 \section adsi_page_sec_2a6 CHECKSUM WORD 00121 The Checksum Word contains the twos complement of the modulo 256 00122 sum of the other words in the data message (i.e., message type, 00123 message length, and data words). The receiving equipment may 00124 calculate the modulo 256 sum of the received words and add this 00125 sum to the received checksum word. A result of zero generally 00126 indicates that the message was correctly received. Message 00127 retransmission is not supported. The sumcheck word should be followed 00128 by a minimum of two stop bits. 00129 00130 \section adsi_page_sec_2b The ETSI CLIP specification 00131 The ETSI CLIP specification uses similar messages to the Bellcore specification. 00132 They are not, however, identical. First, ETSI use the V.23 modem standard, rather 00133 than Bell 202. Second, different fields, and different message types are available. 00134 00135 The wake up indication generally differs from the Bellcore specification, to 00136 accomodate differences in European ring cadences. 00137 00138 \section adsi_page_sec_2c The ETSI caller ID by DTMF specification 00139 CLI by DTMF is usually sent in a very simple way. The exchange does not give 00140 any prior warning (no reversal, or ring) to wake up the receiver. It just 00141 sends a string of DTMF digits. Around the world several variants of this 00142 basic scheme are used. 00143 00144 One variant of the digit string is used in Belgium, Brazil, Denmark, Finland, Iceland, 00145 India, Netherlands, Saudi Arabia, Sweden and Uruguay: 00146 00147 - A<caller's phone number>D<redirected number>B<special information>C 00148 00149 Each of these fields may be omitted. The following special information codes are defined 00150 00151 - "00" indicates the calling party number is not available. 00152 - "10" indicates that the presentation of the calling party number is restricted. 00153 00154 A second variant of the digit string is one of the following: 00155 00156 - A<caller's phone number># 00157 - D1# Number not available because the caller has restricted it. 00158 - D2# Number not available because the call is international. 00159 - D3# Number not available due to technical reasons. 00160 00161 A third variant of the digit string is used in Taiwan and Kuwait: 00162 00163 - D<caller's phone number>C 00164 00165 A forth variant of the digit string is used in Denmark and Holland: 00166 00167 - <caller's phone number># 00168 00169 There is no distinctive start marker in this format. 00170 00171 \section adsi_page_sec_2d The Japanese specification from NTT 00172 00173 The Japanese caller ID specification is considerably different from any of the others. It 00174 uses V.23 modem signals, but the message structure is uniqeue. Also, the message is delivered 00175 while off hook. This results in a sequence 00176 00177 - The phone line rings 00178 - CPE answers and waits for the caller ID message 00179 - CPE hangs up on receipt of the caller ID message 00180 - The phone line rings a second time 00181 - The CPE answers a second time, connecting the called party with the caller. 00182 00183 Timeouts are, obviously, required to ensure this system behaves well when the caller ID message 00184 or the second ring are missing. 00185 */ 00186 00187 enum 00188 { 00189 ADSI_STANDARD_NONE = 0, 00190 ADSI_STANDARD_CLASS = 1, 00191 ADSI_STANDARD_CLIP = 2, 00192 ADSI_STANDARD_ACLIP = 3, 00193 ADSI_STANDARD_JCLIP = 4, 00194 ADSI_STANDARD_CLIP_DTMF = 5, 00195 ADSI_STANDARD_TDD = 6 00196 }; 00197 00198 /* In some of the messages code characters are used, as follows: 00199 'C' for public callbox 00200 'L' for long distance 00201 'O' for overseas 00202 'P' for private 00203 'S' for service conflict 00204 00205 Taiwan and Kuwait change this pattern to: 00206 'C' for coin/public callbox 00207 'I' for international call 00208 'O' for out of area call 00209 'P' for private 00210 */ 00211 00212 /*! Definitions for CLASS (Custom Local Area Signaling Services) */ 00213 enum 00214 { 00215 /*! Single data message caller ID */ 00216 CLASS_SDMF_CALLERID = 0x04, 00217 /*! Multiple data message caller ID */ 00218 CLASS_MDMF_CALLERID = 0x80, 00219 /*! Single data message message waiting */ 00220 CLASS_SDMF_MSG_WAITING = 0x06, 00221 /*! Multiple data message message waiting */ 00222 CLASS_MDMF_MSG_WAITING = 0x82 00223 }; 00224 00225 /*! CLASS MDMF message IDs */ 00226 enum 00227 { 00228 /*! Date and time (MMDDHHMM) */ 00229 MCLASS_DATETIME = 0x01, 00230 /*! Caller number */ 00231 MCLASS_CALLER_NUMBER = 0x02, 00232 /*! Dialed number */ 00233 MCLASS_DIALED_NUMBER = 0x03, 00234 /*! Caller number absent: 'O' or 'P' */ 00235 MCLASS_ABSENCE1 = 0x04, 00236 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */ 00237 MCLASS_REDIRECT = 0x05, 00238 /*! Long distance: 'L' */ 00239 MCLASS_QUALIFIER = 0x06, 00240 /*! Caller's name */ 00241 MCLASS_CALLER_NAME = 0x07, 00242 /*! Caller's name absent: 'O' or 'P' */ 00243 MCLASS_ABSENCE2 = 0x08, 00244 /*! Alternate route */ 00245 MCLASS_ALT_ROUTE = 0x09 00246 }; 00247 00248 /*! CLASS MDMF message waiting message IDs */ 00249 /*! Message waiting/not waiting */ 00250 #define MCLASS_VISUAL_INDICATOR 0x0B 00251 00252 /*! Definitions for CLIP (Calling Line Identity Presentation) */ 00253 enum 00254 { 00255 /*! Multiple data message caller ID */ 00256 CLIP_MDMF_CALLERID = 0x80, 00257 /*! Multiple data message message waiting */ 00258 CLIP_MDMF_MSG_WAITING = 0x82, 00259 /*! Multiple data message charge information */ 00260 CLIP_MDMF_CHARGE_INFO = 0x86, 00261 /*! Multiple data message SMS */ 00262 CLIP_MDMF_SMS = 0x89 00263 }; 00264 00265 /*! CLIP message IDs */ 00266 enum 00267 { 00268 /*! Date and time (MMDDHHMM) */ 00269 CLIP_DATETIME = 0x01, 00270 /*! Caller number */ 00271 CLIP_CALLER_NUMBER = 0x02, 00272 /*! Dialed number */ 00273 CLIP_DIALED_NUMBER = 0x03, 00274 /*! Caller number absent: 'O' or 'P' */ 00275 CLIP_ABSENCE1 = 0x04, 00276 /*! Caller's name */ 00277 CLIP_CALLER_NAME = 0x07, 00278 /*! Caller's name absent: 'O' or 'P' */ 00279 CLIP_ABSENCE2 = 0x08, 00280 /*! Visual indicator */ 00281 CLIP_VISUAL_INDICATOR = 0x0B, 00282 /*! Message ID */ 00283 CLIP_MESSAGE_ID = 0x0D, 00284 /*! Voice call, ring-back-when-free call, or msg waiting call */ 00285 CLIP_CALLTYPE = 0x11, 00286 /*! Number of messages */ 00287 CLIP_NUM_MSG = 0x13, 00288 /*! Redirecting number */ 00289 CLIP_REDIR_NUMBER = 0x03, 00290 /*! Charge */ 00291 CLIP_CHARGE = 0x20, 00292 /*! Duration of the call */ 00293 CLIP_DURATION = 0x23, 00294 /*! Additional charge */ 00295 CLIP_ADD_CHARGE = 0x21, 00296 /*! Display information */ 00297 CLIP_DISPLAY_INFO = 0x50, 00298 /*! Service information */ 00299 CLIP_SERVICE_INFO = 0x55 00300 }; 00301 00302 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */ 00303 enum 00304 { 00305 /*! Single data message caller ID frame */ 00306 ACLIP_SDMF_CALLERID = 0x04, 00307 /*! Multiple data message caller ID frame */ 00308 ACLIP_MDMF_CALLERID = 0x80 00309 }; 00310 00311 /*! A-CLIP MDM message IDs */ 00312 enum 00313 { 00314 /*! Date and time (MMDDHHMM) */ 00315 ACLIP_DATETIME = 0x01, 00316 /*! Caller number */ 00317 ACLIP_CALLER_NUMBER = 0x02, 00318 /*! Dialed number */ 00319 ACLIP_DIALED_NUMBER = 0x03, 00320 /*! Caller number absent: 'O' or 'P' */ 00321 ACLIP_NUMBER_ABSENCE = 0x04, 00322 /*! Call forward: universal, on busy, or on unanswered */ 00323 ACLIP_REDIRECT = 0x05, 00324 /*! Long distance call: 'L' */ 00325 ACLIP_QUALIFIER = 0x06, 00326 /*! Caller's name */ 00327 ACLIP_CALLER_NAME = 0x07, 00328 /*! Caller's name absent: 'O' or 'P' */ 00329 ACLIP_NAME_ABSENCE = 0x08 00330 }; 00331 00332 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */ 00333 /*! Multiple data message caller ID frame */ 00334 #define JCLIP_MDMF_CALLERID 0x40 00335 00336 /*! J-CLIP MDM message IDs */ 00337 enum 00338 { 00339 /*! Caller number */ 00340 JCLIP_CALLER_NUMBER = 0x02, 00341 /*! Caller number data extension signal */ 00342 JCLIP_CALLER_NUM_DES = 0x21, 00343 /*! Dialed number */ 00344 JCLIP_DIALED_NUMBER = 0x09, 00345 /*! Dialed number data extension signal */ 00346 JCLIP_DIALED_NUM_DES = 0x22, 00347 /*! Caller number absent: 'C', 'O', 'P' or 'S' */ 00348 JCLIP_ABSENCE = 0x04 00349 }; 00350 00351 /*! Definitions for CLIP-DTMF and its variants */ 00352 00353 #define CLIP_DTMF_HASH_TERMINATED '#' 00354 #define CLIP_DTMF_C_TERMINATED 'C' 00355 00356 /*! Caller number */ 00357 #define CLIP_DTMF_HASH_CALLER_NUMBER 'A' 00358 /*! Caller number absent: private (1), overseas (2) or not available (3) */ 00359 #define CLIP_DTMF_HASH_ABSENCE 'D' 00360 /*! Caller ID field with no explicit field type */ 00361 #define CLIP_DTMF_HASH_UNSPECIFIED 0 00362 00363 /*! Caller number */ 00364 #define CLIP_DTMF_C_CALLER_NUMBER 'A' 00365 /*! Diverting number */ 00366 #define CLIP_DTMF_C_REDIRECT_NUMBER 'D' 00367 /*! Caller number absent: private/restricted (00) or not available (10) */ 00368 #define CLIP_DTMF_C_ABSENCE 'B' 00369 00370 /*! 00371 ADSI transmitter descriptor. This contains all the state information for an ADSI 00372 (caller ID, CLASS, CLIP, ACLIP) transmit channel. 00373 */ 00374 typedef struct 00375 { 00376 int standard; 00377 00378 tone_gen_descriptor_t alert_tone_desc; 00379 tone_gen_state_t alert_tone_gen; 00380 fsk_tx_state_t fsktx; 00381 dtmf_tx_state_t dtmftx; 00382 async_tx_state_t asynctx; 00383 00384 int tx_signal_on; 00385 00386 int byte_no; 00387 int bit_pos; 00388 int bit_no; 00389 uint8_t msg[256]; 00390 int msg_len; 00391 int preamble_len; 00392 int preamble_ones_len; 00393 int postamble_ones_len; 00394 int stop_bits; 00395 int baudot_shift; 00396 00397 logging_state_t logging; 00398 } adsi_tx_state_t; 00399 00400 /*! 00401 ADSI receiver descriptor. This contains all the state information for an ADSI 00402 (caller ID, CLASS, CLIP, ACLIP, JCLIP) receive channel. 00403 */ 00404 typedef struct 00405 { 00406 int standard; 00407 put_msg_func_t put_msg; 00408 void *user_data; 00409 00410 fsk_rx_state_t fskrx; 00411 dtmf_rx_state_t dtmfrx; 00412 async_rx_state_t asyncrx; 00413 00414 int consecutive_ones; 00415 int bit_pos; 00416 int in_progress; 00417 uint8_t msg[256]; 00418 int msg_len; 00419 int baudot_shift; 00420 00421 /*! A count of the framing errors. */ 00422 int framing_errors; 00423 00424 logging_state_t logging; 00425 } adsi_rx_state_t; 00426 00427 #if defined(__cplusplus) 00428 extern "C" 00429 { 00430 #endif 00431 00432 /*! \brief Initialise an ADSI receive context. 00433 \param s The ADSI receive context. 00434 \param standard The code for the ADSI standard to be used. 00435 \param put_msg A callback routine called to deliver the received messages 00436 to the application. 00437 \param user_data An opaque pointer for the callback routine. 00438 \return A pointer to the initialised context, or NULL if there was a problem. 00439 */ 00440 adsi_rx_state_t *adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data); 00441 00442 /*! \brief Receive a chunk of ADSI audio. 00443 \param s The ADSI receive context. 00444 \param amp The audio sample buffer. 00445 \param len The number of samples in the buffer. 00446 \return The number of samples unprocessed. 00447 */ 00448 int adsi_rx(adsi_rx_state_t *s, const int16_t *amp, int len); 00449 00450 /*! \brief Initialise an ADSI transmit context. 00451 \param s The ADSI transmit context. 00452 \param standard The code for the ADSI standard to be used. 00453 \return A pointer to the initialised context, or NULL if there was a problem. 00454 */ 00455 adsi_tx_state_t *adsi_tx_init(adsi_tx_state_t *s, int standard); 00456 00457 /*! \brief Adjust the preamble associated with an ADSI transmit context. 00458 \param s The ADSI transmit context. 00459 \param preamble_len The number of bits of preamble. 00460 \param preamble_ones_len The number of bits of continuous one before a message. 00461 \param postamble_ones_len The number of bits of continuous one after a message. 00462 \param stop_bits The number of stop bits per character. 00463 */ 00464 void adsi_tx_set_preamble(adsi_tx_state_t *s, 00465 int preamble_len, 00466 int preamble_ones_len, 00467 int postamble_ones_len, 00468 int stop_bits); 00469 00470 /*! \brief Generate a block of ADSI audio samples. 00471 \param s The ADSI transmit context. 00472 \param amp The audio sample buffer. 00473 \param max_len The number of samples to be generated. 00474 \return The number of samples actually generated. 00475 */ 00476 int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len); 00477 00478 /*! \brief Request generation of an ADSI alert tone. 00479 \param s The ADSI transmit context. 00480 */ 00481 void adsi_tx_send_alert_tone(adsi_tx_state_t *s); 00482 00483 /*! \brief Put a message into the input buffer of an ADSI transmit context. 00484 \param s The ADSI transmit context. 00485 \param msg The message. 00486 \param len The length of the message. 00487 \return The length actually added. If a message is already in progress 00488 in the transmitter, this function will return zero, as it will 00489 not successfully add the message to the buffer. 00490 */ 00491 int adsi_tx_put_message(adsi_tx_state_t *s, const uint8_t *msg, int len); 00492 00493 /*! \brief Get a field from an ADSI message. 00494 \param s The ADSI receive context. 00495 \param msg The message buffer. 00496 \param msg_len The length of the message. 00497 \param pos Current position within the message. Set to -1 when starting a message. 00498 \param field_type The type code for the field. 00499 \param field_body Pointer to the body of the field. 00500 \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt. 00501 */ 00502 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); 00503 00504 /*! \brief Insert the header or a field into an ADSI message. 00505 \param s The ADSI transmit context. 00506 \param msg The message buffer. 00507 \param len The current length of the message. 00508 \param field_type The type code for the new field. 00509 \param field_body Pointer to the body of the new field. 00510 \param field_len The length of the new field. 00511 */ 00512 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); 00513 00514 /*! \brief Return a short name for an ADSI standard 00515 \param standard The code for the standard. 00516 \return A pointer to the name. 00517 */ 00518 const char *adsi_standard_to_str(int standard); 00519 00520 #if defined(__cplusplus) 00521 } 00522 #endif 00523 00524 #endif 00525 /*- End of file ------------------------------------------------------------*/