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 General Public License version 2, as 00014 * 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 General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU General Public License 00022 * 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.17 2007/04/05 19:20:49 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 - CLASS (Custom Local Area Signaling Services) standard, published by Bellcore: 00041 00042 - ACLIP (Analog Calling Line Identity Presentation) standard, published by the 00043 Telecommunications Authority of Singapore: 00044 00045 - CLIP (Calling Line Identity Presentation) standard, published by ETSI. 00046 00047 - JCLIP (Japanese Calling Line Identity Presentation) standard, published by NTT. 00048 00049 - TDD (Telecommunications Device for the Deaf). 00050 00051 \section adsi_page_sec_2 How does it work? 00052 00053 \section adsi_page_sec_2a The Bellcore CLASS specification 00054 Most FSK based CLI formats are similar to the US CLASS one, which is as follows: 00055 00056 The alert tone for CLI during a call is at least 100ms of silence, then 00057 2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time, 00058 this tone is not sent. In the US, CLI is usually sent between the first 00059 two rings. This silence period is long in the US, so the message fits easily. 00060 In other places, where the standard ring tone has much smaller silences, 00061 a line voltage reversal is used to wake up a power saving receiver, then the 00062 message is sent, then the phone begins to ring. 00063 00064 The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits 00065 per second. The message protocol uses 8-bit data words (bytes), each bounded 00066 by a start bit and a stop bit. 00067 00068 Channel Carrier Message Message Data Checksum 00069 Seizure Signal Type Length Word(s) Word 00070 Signal Word Word 00071 00072 \section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL 00073 The channel seizure is 30 continuous bytes of 55h (01010101), including 00074 the start and stop bits (i.e. 300 bits of alternations in total). 00075 This provides a detectable alternating function to the CPE (i.e. the 00076 modem data pump). 00077 00078 \section adsi_page_sec_2a2 CARRIER SIGNAL 00079 The carrier signal consists of 180 bits of 1s. This may be reduced to 80 00080 bits of 1s for caller ID on call waiting. 00081 00082 \section adsi_page_sec_2a3 MESSAGE TYPE WORD 00083 Various message types are defined. The common ones for the US CLASS 00084 standard are: 00085 - Type 0x04 (SDMF) - single data message. Simple caller ID (CND) 00086 - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID, 00087 with extra information. 00088 00089 \section adsi_page_sec_2a4 MESSAGE LENGTH WORD 00090 The message length word specifies the total number of data words 00091 to follow. 00092 00093 \section adsi_page_sec_2a5 DATA WORDS 00094 The data words contain the actual message. 00095 00096 \section adsi_page_sec_2a6 CHECKSUM WORD 00097 The Checksum Word contains the twos complement of the modulo 256 00098 sum of the other words in the data message (i.e., message type, 00099 message length, and data words). The receiving equipment may 00100 calculate the modulo 256 sum of the received words and add this 00101 sum to the received checksum word. A result of zero generally 00102 indicates that the message was correctly received. Message 00103 retransmission is not supported. The sumcheck word should be followed 00104 by a minimum of two stop bits. 00105 00106 \section adsi_page_sec_2b The ETSI CLIP specification 00107 The ETSI CLIP specification uses similar messages to the Bellcore specification. 00108 They are not, however, identical. First, ETSI use the V.23 modem standard, rather 00109 than Bell 202. Second, different fields, and different message types are available. 00110 00111 \section adsi_page_sec_2e The ETSI caller ID by DTMF specification 00112 CLI by DTMF is usually sent in a very simple way. The exchange does not give 00113 any prior warning (no reversal, or ring) to wake up the receiver. It just 00114 sends one of the following DTMF strings: 00115 00116 - A<phone number># 00117 - D1# Number not available because the caller has restricted it. 00118 - D2# Number not available because the call is international. 00119 - D3# Number not available due to technical reasons. 00120 */ 00121 00122 enum 00123 { 00124 ADSI_STANDARD_NONE = 0, 00125 ADSI_STANDARD_CLASS = 1, 00126 ADSI_STANDARD_CLIP = 2, 00127 ADSI_STANDARD_ACLIP = 3, 00128 ADSI_STANDARD_JCLIP = 4, 00129 ADSI_STANDARD_CLIP_DTMF = 5, 00130 ADSI_STANDARD_TDD = 6 00131 }; 00132 00133 /* In some of the messages code characters are used, as follows: 00134 'C' for public callbox 00135 'L' for long distance 00136 'O' for overseas 00137 'P' for private 00138 'S' for service conflict */ 00139 00140 /*! Definitions for generic caller ID message type IDs */ 00141 /*! Complete caller ID message */ 00142 #define CLIDINFO_CMPLT 0x100 00143 /*! Date, time, phone #, name */ 00144 #define CLIDINFO_GENERAL 0x101 00145 /*! Caller ID */ 00146 #define CLIDINFO_CALLID 0x102 00147 /*! See frame type equates */ 00148 #define CLIDINFO_FRAMETYPE 0x103 00149 00150 /*! Definitions for CLASS (Custom Local Area Signaling Services) */ 00151 /*! Single data message caller ID */ 00152 #define CLASS_SDMF_CALLERID 0x04 00153 /*! Multiple data message caller ID */ 00154 #define CLASS_MDMF_CALLERID 0x80 00155 /*! Single data message message waiting */ 00156 #define CLASS_SDMF_MSG_WAITING 0x06 00157 /*! Multiple data message message waiting */ 00158 #define CLASS_MDMF_MSG_WAITING 0x82 00159 00160 /*! CLASS MDMF message IDs */ 00161 /*! Date and time (MMDDHHMM) */ 00162 #define MCLASS_DATETIME 0x01 00163 /*! Caller number */ 00164 #define MCLASS_CALLER_NUMBER 0x02 00165 /*! Dialed number */ 00166 #define MCLASS_DIALED_NUMBER 0x03 00167 /*! Caller number absent: 'O' or 'P' */ 00168 #define MCLASS_ABSENCE1 0x04 00169 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */ 00170 #define MCLASS_REDIRECT 0x05 00171 /*! Long distance: 'L' */ 00172 #define MCLASS_QUALIFIER 0x06 00173 /*! Caller's name */ 00174 #define MCLASS_CALLER_NAME 0x07 00175 /*! Caller's name absent: 'O' or 'P' */ 00176 #define MCLASS_ABSENCE2 0x08 00177 00178 /*! CLASS MDMF message waiting message IDs */ 00179 /*! Message waiting/not waiting */ 00180 #define MCLASS_VISUAL_INDICATOR 0x0B 00181 00182 /*! Definitions for CLIP (Calling Line Identity Presentation) */ 00183 /*! Multiple data message caller ID */ 00184 #define CLIP_MDMF_CALLERID 0x80 00185 /*! Multiple data message message waiting */ 00186 #define CLIP_MDMF_MSG_WAITING 0x82 00187 /*! Multiple data message charge information */ 00188 #define CLIP_MDMF_CHARGE_INFO 0x86 00189 /*! Multiple data message SMS */ 00190 #define CLIP_MDMF_SMS 0x89 00191 00192 /*! CLIP message IDs */ 00193 /*! Date and time (MMDDHHMM) */ 00194 #define CLIP_DATETIME 0x01 00195 /*! Caller number */ 00196 #define CLIP_CALLER_NUMBER 0x02 00197 /*! Dialed number */ 00198 #define CLIP_DIALED_NUMBER 0x03 00199 /*! Caller number absent: 'O' or 'P' */ 00200 #define CLIP_ABSENCE1 0x04 00201 /*! Caller's name */ 00202 #define CLIP_CALLER_NAME 0x07 00203 /*! Caller's name absent: 'O' or 'P' */ 00204 #define CLIP_ABSENCE2 0x08 00205 /*! Visual indicator */ 00206 #define CLIP_VISUAL_INDICATOR 0x0B 00207 /*! Message ID */ 00208 #define CLIP_MESSAGE_ID 0x0D 00209 /*! Voice call, ring-back-when-free call, or msg waiting call */ 00210 #define CLIP_CALLTYPE 0x11 00211 /*! Number of messages */ 00212 #define CLIP_NUM_MSG 0x13 00213 /*! Redirecting number */ 00214 #define CLIP_REDIR_NUMBER 0x03 00215 /*! Charge */ 00216 #define CLIP_CHARGE 0x20 00217 /*! Duration of the call */ 00218 #define CLIP_DURATION 0x23 00219 /*! Additional charge */ 00220 #define CLIP_ADD_CHARGE 0x21 00221 /*! Display information */ 00222 #define CLIP_DISPLAY_INFO 0x50 00223 /*! Service information */ 00224 #define CLIP_SERVICE_INFO 0x55 00225 00226 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */ 00227 /*! Single data message caller ID frame */ 00228 #define ACLIP_SDMF_CALLERID 0x04 00229 /*! Multiple data message caller ID frame */ 00230 #define ACLIP_MDMF_CALLERID 0x80 00231 00232 /*! A-CLIP MDM message IDs */ 00233 /*! Date and time (MMDDHHMM) */ 00234 #define ACLIP_DATETIME 0x01 00235 /*! Caller number */ 00236 #define ACLIP_CALLER_NUMBER 0x02 00237 /*! Dialed number */ 00238 #define ACLIP_DIALED_NUMBER 0x03 00239 /*! Caller number absent: 'O' or 'P' */ 00240 #define ACLIP_ABSENCE1 0x04 00241 /*! Call forward: universal, on busy, or on unanswered */ 00242 #define ACLIP_REDIRECT 0x05 00243 /*! Long distance call: 'L' */ 00244 #define ACLIP_QUALIFIER 0x06 00245 /*! Caller's name */ 00246 #define ACLIP_CALLER_NAME 0x07 00247 /*! Caller's name absent: 'O' or 'P' */ 00248 #define ACLIP_ABSENCE2 0x08 00249 00250 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */ 00251 /*! Multiple data message caller ID frame */ 00252 #define JCLIP_MDMF_CALLERID 0x40 00253 00254 /*! J-CLIP MDM message IDs */ 00255 /*! Caller number */ 00256 #define JCLIP_CALLER_NUMBER 0x02 00257 /*! Caller number data extension signal */ 00258 #define JCLIP_CALLER_NUM_DES 0x21 00259 /*! Dialed number */ 00260 #define JCLIP_DIALED_NUMBER 0x09 00261 /*! Dialed number data extension signal */ 00262 #define JCLIP_DIALED_NUM_DES 0x22 00263 /*! Caller number absent: 'C', 'O', 'P' or 'S' */ 00264 #define JCLIP_ABSENCE 0x04 00265 00266 /*! Definitions for CLIP-DTMF */ 00267 /*! Caller number */ 00268 #define CLIP_DTMF_CALLER_NUMBER 'A' 00269 /*! Caller number absent: private (1), overseas (2) or not available (3) */ 00270 #define CLIP_DTMF_ABSENCE1 'D' 00271 00272 /*! 00273 ADSI transmitter descriptor. This contains all the state information for an ADSI 00274 (caller ID, CLASS, CLIP, ACLIP) transmit channel. 00275 */ 00276 typedef struct 00277 { 00278 int standard; 00279 00280 tone_gen_descriptor_t alert_tone_desc; 00281 tone_gen_state_t alert_tone_gen; 00282 fsk_tx_state_t fsktx; 00283 dtmf_tx_state_t dtmftx; 00284 async_tx_state_t asynctx; 00285 00286 int tx_signal_on; 00287 00288 int byteno; 00289 int bitpos; 00290 int bitno; 00291 uint8_t msg[256]; 00292 int msg_len; 00293 int ones_len; 00294 int baudot_shift; 00295 00296 logging_state_t logging; 00297 } adsi_tx_state_t; 00298 00299 /*! 00300 ADSI receiver descriptor. This contains all the state information for an ADSI 00301 (caller ID, CLASS, CLIP, ACLIP) receive channel. 00302 */ 00303 typedef struct 00304 { 00305 put_msg_func_t put_msg; 00306 void *user_data; 00307 int standard; 00308 00309 fsk_rx_state_t fskrx; 00310 dtmf_rx_state_t dtmfrx; 00311 async_rx_state_t asyncrx; 00312 00313 int consecutive_ones; 00314 int bitpos; 00315 int in_progress; 00316 uint8_t msg[256]; 00317 int msg_len; 00318 int baudot_shift; 00319 00320 /*! A count of the framing errors. */ 00321 int framing_errors; 00322 00323 logging_state_t logging; 00324 } adsi_rx_state_t; 00325 00326 #ifdef __cplusplus 00327 extern "C" 00328 { 00329 #endif 00330 00331 /*! \brief Initialise an ADSI receive context. 00332 \param s The ADSI receive context. 00333 \param standard The code for the ADSI standard to be used. 00334 \param put_msg A callback routine called to deliver the received messages 00335 to the application. 00336 \param user_data An opaque pointer for the callback routine. 00337 */ 00338 void adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data); 00339 00340 /*! \brief Receive a chunk of ADSI audio. 00341 \param s The ADSI receive context. 00342 \param amp The audio sample buffer. 00343 \param len The number of samples in the buffer. 00344 */ 00345 void adsi_rx(adsi_rx_state_t *s, const int16_t *amp, int len); 00346 00347 /*! \brief Initialise an ADSI transmit context. 00348 \param s The ADSI transmit context. 00349 \param standard The code for the ADSI standard to be used. 00350 */ 00351 void adsi_tx_init(adsi_tx_state_t *s, int standard); 00352 00353 /*! \brief Generate a block of ADSI audio samples. 00354 \param s The ADSI transmit context. 00355 \param amp The audio sample buffer. 00356 \param max_len The number of samples to be generated. 00357 \return The number of samples actually generated. 00358 */ 00359 int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len); 00360 00361 /*! \brief Request generation of an ADSI alert tone. 00362 \param s The ADSI transmit context. 00363 */ 00364 void adsi_send_alert_tone(adsi_tx_state_t *s); 00365 00366 /*! \brief Put a message into the input buffer of an ADSI transmit context. 00367 \param s The ADSI transmit context. 00368 \param msg The message. 00369 \param len The length of the message. 00370 \return The length actually added. If a message is already in progress 00371 in the transmitter, this function will return zero, as it will 00372 not successfully add the message to the buffer. 00373 */ 00374 int adsi_put_message(adsi_tx_state_t *s, uint8_t *msg, int len); 00375 00376 /*! \brief Get a field from an ADSI message. 00377 \param s The ADSI receive context. 00378 \param msg The message buffer. 00379 \param msg_len The length of the message. 00380 \param pos Current position within the message. Set to -1 when starting a message. 00381 \param field_type The type code for the field. 00382 \param field_body Pointer to the body of the field. 00383 \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt. 00384 */ 00385 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); 00386 00387 /*! \brief Insert the header or a field into an ADSI message. 00388 \param s The ADSI transmit context. 00389 \param msg The message buffer. 00390 \param len The current length of the message. 00391 \param field_type The type code for the new field. 00392 \param field_body Pointer to the body of the new field. 00393 \param field_len The length of the new field. 00394 */ 00395 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); 00396 00397 /*! \brief Return a short name for an ADSI standard 00398 \param standard The code for the standard. 00399 \return A pointer to the name. 00400 */ 00401 const char *adsi_standard_to_str(int standard); 00402 00403 #ifdef __cplusplus 00404 } 00405 #endif 00406 00407 #endif 00408 /*- End of file ------------------------------------------------------------*/