adsi.h

Go to the documentation of this file.
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 as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: adsi.h,v 1.14 2005/11/28 13:43:34 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 #if !defined(_ADSI_H_)
00032 #define _ADSI_H_
00033 
00034 /*! \page adsi_page ADSI transmission and reception
00035 \section adsi_page_sec_1 What does it do?
00036 Although ADSI has a specific meaning in some places, the term is used here to indicate
00037 any form of Analogue Display Service Interface, which includes caller ID, SMS, and others.
00038 
00039 The ADSI module provides for the transmission and reception of ADSI messages
00040 in various formats. Currently, the supported formats are:
00041     - CLASS (Custom Local Area Signaling Services) standard, published by Bellcore:
00042 
00043     - ACLIP (Analog Calling Line Identity Presentation) standard, published by the
00044       Telecommunications Authority of Singapore:
00045 
00046     - CLIP (Calling Line Identity Presentation) standard, published by ETSI.
00047 
00048     - JCLIP (Japanese Calling Line Identity Presentation) standard, published by NTT.
00049         
00050     - TDD (Telecommunications Device for the Deaf).
00051 
00052 \section adsi_page_sec_2 How does it work?
00053 
00054 \section adsi_page_sec_2a The Bellcore CLASS specification
00055 Most FSK based CLI formats are similar to the US CLASS one, which is as follows:
00056 
00057 The alert tone for CLI during a call is at least 100ms of silence, then
00058 2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time,
00059 this tone is not sent. In the US, CLI is usually sent between the first
00060 two rings. This silence period is long in the US, so the message fits easily.
00061 In other places, where the standard ring tone has much smaller silences,
00062 a line voltage reversal is used to wake up a power saving receiver, then the
00063 message is sent, then the phone begins to ring.
00064     
00065 The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits
00066 per second. The message protocol uses 8-bit data words (bytes), each bounded
00067 by a start bit and a stop bit.
00068 
00069 Channel     Carrier     Message     Message     Data        Checksum
00070 Seizure     Signal      Type        Length      Word(s)     Word
00071 Signal                  Word        Word
00072     
00073 \section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL
00074 The channel seizure is 30 continuous bytes of 55h (01010101), including
00075 the start and stop bits (i.e. 300 bits of alternations in total).
00076 This provides a detectable alternating function to the CPE (i.e. the
00077 modem data pump).
00078     
00079 \section adsi_page_sec_2a2 CARRIER SIGNAL
00080 The carrier signal consists of 180 bits of 1s. This may be reduced to 80
00081 bits of 1s for caller ID on call waiting.
00082     
00083 \section adsi_page_sec_2a3 MESSAGE TYPE WORD
00084 Various message types are defined. The common ones for the US CLASS 
00085 standard are:
00086     - Type 0x04 (SDMF) - single data message. Simple caller ID (CND)
00087     - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID,
00088                          with extra information.
00089     
00090 \section adsi_page_sec_2a4 MESSAGE LENGTH WORD
00091 The message length word specifies the total number of data words
00092 to follow.
00093     
00094 \section adsi_page_sec_2a5 DATA WORDS
00095 The data words contain the actual message.
00096     
00097 \section adsi_page_sec_2a6 CHECKSUM WORD
00098 The Checksum Word contains the twos complement of the modulo 256
00099 sum of the other words in the data message (i.e., message type,
00100 message length, and data words).  The receiving equipment may
00101 calculate the modulo 256 sum of the received words and add this
00102 sum to the received checksum word.  A result of zero generally
00103 indicates that the message was correctly received.  Message
00104 retransmission is not supported. The sumcheck word should be followed
00105 by a minimum of two stop bits.
00106 
00107 \section adsi_page_sec_2b The ETSI CLIP specification
00108 The ETSI CLIP specification uses similar messages to the Bellcore specification.
00109 They are not, however, identical. First, ETSI use the V.23 modem standard, rather
00110 than Bell 202. Second, different fields, and different message types are available.
00111 
00112 \section adsi_page_sec_2e The ETSI caller ID by DTMF specification
00113 CLI by DTMF is usually sent in a very simple way. The exchange does not give
00114 any prior warning (no reversal, or ring) to wake up the receiver. It just
00115 sends one of the following DTMF strings:
00116     
00117     - A<phone number>#
00118     - D1#     Number not available because the caller has restricted it.
00119     - D2#     Number not available because the call is international.
00120     - D3#     Number not available due to technical reasons.
00121 */
00122 
00123 enum
00124 {
00125     ADSI_STANDARD_NONE = 0,
00126     ADSI_STANDARD_CLASS = 1,
00127     ADSI_STANDARD_CLIP = 2,
00128     ADSI_STANDARD_ACLIP = 3,
00129     ADSI_STANDARD_JCLIP = 4,
00130     ADSI_STANDARD_CLIP_DTMF = 5,
00131     ADSI_STANDARD_TDD = 6
00132 };
00133 
00134 /* In some of the messages code characters are used, as follows:
00135         'C' for public callbox
00136         'L' for long distance
00137         'O' for overseas
00138         'P' for private
00139         'S' for service conflict */
00140 
00141 /*! Definitions for generic caller ID message type IDs */
00142 /*! Complete caller ID message */
00143 #define CLIDINFO_CMPLT          0x100
00144 /*! Date, time, phone #, name */
00145 #define CLIDINFO_GENERAL        0x101
00146 /*! Caller ID */
00147 #define CLIDINFO_CALLID         0x102
00148 /*! See frame type equates */
00149 #define CLIDINFO_FRAMETYPE      0x103
00150 
00151 /*! Definitions for CLASS (Custom Local Area Signaling Services) */
00152 /*! Single data message caller ID */
00153 #define CLASS_SDMF_CALLERID     0x04
00154 /*! Multiple data message caller ID */
00155 #define CLASS_MDMF_CALLERID     0x80
00156 /*! Single data message message waiting */
00157 #define CLASS_SDMF_MSG_WAITING  0x06
00158 /*! Multiple data message message waiting */
00159 #define CLASS_MDMF_MSG_WAITING  0x82
00160 
00161 /*! CLASS MDMF message IDs */
00162 /*! Date and time (MMDDHHMM) */
00163 #define MCLASS_DATETIME         0x01
00164 /*! Caller number */
00165 #define MCLASS_CALLER_NUMBER    0x02
00166 /*! Dialed number */
00167 #define MCLASS_DIALED_NUMBER    0x03
00168 /*! Caller number absent: 'O' or 'P' */
00169 #define MCLASS_ABSENCE1         0x04
00170 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
00171 #define MCLASS_REDIRECT         0x05
00172 /*! Long distance: 'L' */
00173 #define MCLASS_QUALIFIER        0x06
00174 /*! Caller's name */
00175 #define MCLASS_CALLER_NAME      0x07
00176 /*! Caller's name absent: 'O' or 'P' */
00177 #define MCLASS_ABSENCE2         0x08
00178 
00179 /*! CLASS MDMF message waiting message IDs */
00180 /*! Message waiting/not waiting */
00181 #define MCLASS_VISUAL_INDICATOR 0x0B
00182 
00183 /*! Definitions for CLIP (Calling Line Identity Presentation) */
00184 /*! Multiple data message caller ID */
00185 #define CLIP_MDMF_CALLERID      0x80
00186 /*! Multiple data message message waiting */
00187 #define CLIP_MDMF_MSG_WAITING   0x82
00188 /*! Multiple data message charge information */
00189 #define CLIP_MDMF_CHARGE_INFO   0x86
00190 /*! Multiple data message SMS */
00191 #define CLIP_MDMF_SMS           0x89
00192 
00193 /*! CLIP message IDs */
00194 /*! Date and time (MMDDHHMM) */
00195 #define CLIP_DATETIME           0x01
00196 /*! Caller number */
00197 #define CLIP_CALLER_NUMBER      0x02
00198 /*! Dialed number */
00199 #define CLIP_DIALED_NUMBER      0x03
00200 /*! Caller number absent: 'O' or 'P' */
00201 #define CLIP_ABSENCE1           0x04
00202 /*! Caller's name */
00203 #define CLIP_CALLER_NAME        0x07
00204 /*! Caller's name absent: 'O' or 'P' */
00205 #define CLIP_ABSENCE2           0x08
00206 /*! Visual indicator */
00207 #define CLIP_VISUAL_INDICATOR   0x0B
00208 /*! Message ID */
00209 #define CLIP_MESSAGE_ID         0x0D
00210 /*! Voice call, ring-back-when-free call, or msg waiting call */
00211 #define CLIP_CALLTYPE           0x11
00212 /*! Number of messages */
00213 #define CLIP_NUM_MSG            0x13
00214 /*! Redirecting number */
00215 #define CLIP_REDIR_NUMBER       0x03
00216 /*! Charge */
00217 #define CLIP_CHARGE             0x20
00218 /*! Duration of the call */
00219 #define CLIP_DURATION           0x23
00220 /*! Additional charge */
00221 #define CLIP_ADD_CHARGE         0x21
00222 /*! Display information */
00223 #define CLIP_DISPLAY_INFO       0x50
00224 /*! Service information */
00225 #define CLIP_SERVICE_INFO       0x55
00226 
00227 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
00228 /*! Single data message caller ID frame   */
00229 #define ACLIP_SDMF_CALLERID     0x04
00230 /*! Multiple data message caller ID frame */
00231 #define ACLIP_MDMF_CALLERID     0x80
00232 
00233 /*! A-CLIP MDM message IDs */
00234 /*! Date and time (MMDDHHMM) */
00235 #define ACLIP_DATETIME          0x01
00236 /*! Caller number */
00237 #define ACLIP_CALLER_NUMBER     0x02
00238 /*! Dialed number */
00239 #define ACLIP_DIALED_NUMBER     0x03
00240 /*! Caller number absent: 'O' or 'P' */
00241 #define ACLIP_ABSENCE1          0x04
00242 /*! Call forward: universal, on busy, or on unanswered */
00243 #define ACLIP_REDIRECT          0x05
00244 /*! Long distance call: 'L' */
00245 #define ACLIP_QUALIFIER         0x06
00246 /*! Caller's name */
00247 #define ACLIP_CALLER_NAME       0x07
00248 /*! Caller's name absent: 'O' or 'P' */
00249 #define ACLIP_ABSENCE2          0x08
00250 
00251 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
00252 /*! Multiple data message caller ID frame */
00253 #define JCLIP_MDMF_CALLERID     0x40
00254 
00255 /*! J-CLIP MDM message IDs */
00256 /*! Caller number */
00257 #define JCLIP_CALLER_NUMBER     0x02
00258 /*! Caller number data extension signal */
00259 #define JCLIP_CALLER_NUM_DES    0x21
00260 /*! Dialed number */
00261 #define JCLIP_DIALED_NUMBER     0x09
00262 /*! Dialed number data extension signal */
00263 #define JCLIP_DIALED_NUM_DES    0x22
00264 /*! Caller number absent: 'C', 'O', 'P' or 'S' */
00265 #define JCLIP_ABSENCE           0x04
00266 
00267 /*! Definitions for CLIP-DTMF */
00268 /*! Caller number */
00269 #define CLIP_DTMF_CALLER_NUMBER 'A'
00270 /*! Caller number absent: private (1), overseas (2) or not available (3) */
00271 #define CLIP_DTMF_ABSENCE1      'D'
00272 
00273 /*!
00274     ADSI transmitter descriptor. This contains all the state information for an ADSI
00275     (caller ID, CLASS, CLIP, ACLIP) transmit channel.
00276  */
00277 typedef struct
00278 {
00279     int standard;
00280 
00281     tone_gen_descriptor_t alert_tone_desc;
00282     tone_gen_state_t alert_tone_gen;
00283     fsk_tx_state_t fsktx;
00284     dtmf_tx_state_t dtmftx;
00285     async_tx_state_t asynctx;
00286     
00287     int tx_signal_on;
00288     
00289     int byteno;
00290     int bitpos;
00291     int bitno;
00292     uint8_t msg[256];
00293     int msg_len;
00294     int ones_len;
00295     int baudot_shift;
00296     
00297     logging_state_t logging;
00298 } adsi_tx_state_t;
00299 
00300 /*!
00301     ADSI receiver descriptor. This contains all the state information for an ADSI
00302     (caller ID, CLASS, CLIP, ACLIP) receive channel.
00303  */
00304 typedef struct
00305 {
00306     put_msg_func_t put_msg;
00307     void *user_data;
00308     int standard;
00309 
00310     fsk_rx_state_t fskrx;
00311     dtmf_rx_state_t dtmfrx;
00312     async_rx_state_t asyncrx;
00313     
00314     int consecutive_ones;
00315     int bitpos;
00316     int in_progress;
00317     uint8_t msg[256];
00318     int msg_len;
00319     int baudot_shift;
00320     
00321     /*! A count of the framing errors. */
00322     int framing_errors;
00323 
00324     logging_state_t logging;
00325 } adsi_rx_state_t;
00326 
00327 #ifdef __cplusplus
00328 extern "C" {
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 ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:23 2006 for libspandsp by  doxygen 1.5.1