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 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.23 2007/06/08 13:49:38 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 /* Dutch/Danish scheme from the ETSI documents.
00267    We are looking for a string of digits ending with "#". There
00268    is no special start marker. Only the caller number is supplied */
00269 
00270 /* Finland/Denmark/Iceland/Netherlands/India/Belgium/Sweden/
00271    Brazil/Saudi Arabia/Uruguay scheme.
00272    We are looking for a string of digits like "AnnnnBnnnDnnnnC"
00273    where:
00274         "A" is used as a start code for the Calling party number
00275         "B" is used as a start code for the special information concerning the "not availability / restriction information" of the Calling party number
00276         "C" is used as an end code for the information transfer
00277         "D" is used as a start code for the Diverting party number in case of call diversion
00278 
00279    The following special information codes are defined
00280         Decimal value "00" is used to indicate, that the calling party number is not available
00281         Decimal value "10" is used to indicate, that the presentation of the calling party number is restricted */
00282 
00283 /* Taiwan/Kuwait scheme.
00284    We are looking for a string of digits like "DnnnnC", containing
00285    the caller number. */
00286 
00287 /*! Definitions for CLIP-DTMF */
00288 
00289 #define CLIP_DTMF_HASH_TERMINATED       '#'
00290 #define CLIP_DTMF_C_TERMINATED          'C'
00291 
00292 /*! Caller number */
00293 #define CLIP_DTMF_HASH_CALLER_NUMBER    'A'
00294 /*! Caller number absent: private (1), overseas (2) or not available (3) */
00295 #define CLIP_DTMF_HASH_ABSENCE          'D'
00296 
00297 /*! Caller number */
00298 #define CLIP_DTMF_C_CALLER_NUMBER       'A'
00299 /*! Diverting number */
00300 #define CLIP_DTMF_C_REDIRECT_NUMBER     'D'
00301 /*! Caller number absent: private/restricted (00) or not available (10) */
00302 #define CLIP_DTMF_C_ABSENCE             'B'
00303 
00304 /*!
00305     ADSI transmitter descriptor. This contains all the state information for an ADSI
00306     (caller ID, CLASS, CLIP, ACLIP) transmit channel.
00307  */
00308 typedef struct
00309 {
00310     int standard;
00311 
00312     tone_gen_descriptor_t alert_tone_desc;
00313     tone_gen_state_t alert_tone_gen;
00314     fsk_tx_state_t fsktx;
00315     dtmf_tx_state_t dtmftx;
00316     async_tx_state_t asynctx;
00317     
00318     int tx_signal_on;
00319     
00320     int byte_no;
00321     int bit_pos;
00322     int bit_no;
00323     uint8_t msg[256];
00324     int msg_len;
00325     int preamble_len;
00326     int preamble_ones_len;
00327     int postamble_ones_len;
00328     int stop_bits;
00329     int baudot_shift;
00330     
00331     logging_state_t logging;
00332 } adsi_tx_state_t;
00333 
00334 /*!
00335     ADSI receiver descriptor. This contains all the state information for an ADSI
00336     (caller ID, CLASS, CLIP, ACLIP, JCLIP) receive channel.
00337  */
00338 typedef struct
00339 {
00340     put_msg_func_t put_msg;
00341     void *user_data;
00342     int standard;
00343 
00344     fsk_rx_state_t fskrx;
00345     dtmf_rx_state_t dtmfrx;
00346     async_rx_state_t asyncrx;
00347     
00348     int consecutive_ones;
00349     int bit_pos;
00350     int in_progress;
00351     uint8_t msg[256];
00352     int msg_len;
00353     int baudot_shift;
00354     
00355     /*! A count of the framing errors. */
00356     int framing_errors;
00357 
00358     logging_state_t logging;
00359 } adsi_rx_state_t;
00360 
00361 #if defined(__cplusplus)
00362 extern "C"
00363 {
00364 #endif
00365 
00366 /*! \brief Initialise an ADSI receive context.
00367     \param s The ADSI receive context.
00368     \param standard The code for the ADSI standard to be used.
00369     \param put_msg A callback routine called to deliver the received messages
00370            to the application.
00371     \param user_data An opaque pointer for the callback routine.
00372 */
00373 void adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data);
00374 
00375 /*! \brief Receive a chunk of ADSI audio.
00376     \param s The ADSI receive context.
00377     \param amp The audio sample buffer.
00378     \param len The number of samples in the buffer.
00379 */
00380 void adsi_rx(adsi_rx_state_t *s, const int16_t *amp, int len);
00381 
00382 /*! \brief Initialise an ADSI transmit context.
00383     \param s The ADSI transmit context.
00384     \param standard The code for the ADSI standard to be used.
00385 */
00386 void adsi_tx_init(adsi_tx_state_t *s, int standard);
00387 
00388 /*! \brief Adjust the preamble associated with an ADSI transmit context.
00389     \param s The ADSI transmit context.
00390     \param preamble_len The number of bits of preamble.
00391     \param preamble_ones_len The number of bits of continuous one before a message.
00392     \param postamble_ones_len The number of bits of continuous one after a message.
00393     \param stop_bits The number of stop bits per character.
00394 */
00395 void adsi_tx_set_preamble(adsi_tx_state_t *s,
00396                           int preamble_len,
00397                           int preamble_ones_len,
00398                           int postamble_ones_len,
00399                           int stop_bits);
00400 
00401 /*! \brief Generate a block of ADSI audio samples.
00402     \param s The ADSI transmit context.
00403     \param amp The audio sample buffer.
00404     \param max_len The number of samples to be generated.
00405     \return The number of samples actually generated.
00406 */
00407 int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len);
00408 
00409 /*! \brief Request generation of an ADSI alert tone.
00410     \param s The ADSI transmit context.
00411 */
00412 void adsi_send_alert_tone(adsi_tx_state_t *s);
00413 
00414 /*! \brief Put a message into the input buffer of an ADSI transmit context.
00415     \param s The ADSI transmit context.
00416     \param msg The message.
00417     \param len The length of the message.
00418     \return The length actually added. If a message is already in progress
00419             in the transmitter, this function will return zero, as it will
00420             not successfully add the message to the buffer.
00421 */
00422 int adsi_put_message(adsi_tx_state_t *s, uint8_t *msg, int len);
00423 
00424 /*! \brief Get a field from an ADSI message.
00425     \param s The ADSI receive context.
00426     \param msg The message buffer.
00427     \param msg_len The length of the message.
00428     \param pos Current position within the message. Set to -1 when starting a message.
00429     \param field_type The type code for the field.
00430     \param field_body Pointer to the body of the field.
00431     \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
00432 */
00433 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);
00434 
00435 /*! \brief Insert the header or a field into an ADSI message.
00436     \param s The ADSI transmit context.
00437     \param msg The message buffer.
00438     \param len The current length of the message.
00439     \param field_type The type code for the new field.
00440     \param field_body Pointer to the body of the new field.
00441     \param field_len The length of the new field.
00442 */
00443 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);
00444 
00445 /*! \brief Return a short name for an ADSI standard
00446     \param standard The code for the standard.
00447     \return A pointer to the name.
00448 */
00449 const char *adsi_standard_to_str(int standard);
00450 
00451 #if defined(__cplusplus)
00452 }
00453 #endif
00454 
00455 #endif
00456 /*- End of file ------------------------------------------------------------*/

Generated on Tue Jul 24 11:29:28 2007 for libspandsp by  doxygen 1.5.2