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