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.27 2007/11/26 13:28:59 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 /*! Single data message caller ID */
00214 #define CLASS_SDMF_CALLERID             0x04
00215 /*! Multiple data message caller ID */
00216 #define CLASS_MDMF_CALLERID             0x80
00217 /*! Single data message message waiting */
00218 #define CLASS_SDMF_MSG_WAITING          0x06
00219 /*! Multiple data message message waiting */
00220 #define CLASS_MDMF_MSG_WAITING          0x82
00221 
00222 /*! CLASS MDMF message IDs */
00223 /*! Date and time (MMDDHHMM) */
00224 #define MCLASS_DATETIME                 0x01
00225 /*! Caller number */
00226 #define MCLASS_CALLER_NUMBER            0x02
00227 /*! Dialed number */
00228 #define MCLASS_DIALED_NUMBER            0x03
00229 /*! Caller number absent: 'O' or 'P' */
00230 #define MCLASS_ABSENCE1                 0x04
00231 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
00232 #define MCLASS_REDIRECT                 0x05
00233 /*! Long distance: 'L' */
00234 #define MCLASS_QUALIFIER                0x06
00235 /*! Caller's name */
00236 #define MCLASS_CALLER_NAME              0x07
00237 /*! Caller's name absent: 'O' or 'P' */
00238 #define MCLASS_ABSENCE2                 0x08
00239 
00240 /*! CLASS MDMF message waiting message IDs */
00241 /*! Message waiting/not waiting */
00242 #define MCLASS_VISUAL_INDICATOR         0x0B
00243 
00244 /*! Definitions for CLIP (Calling Line Identity Presentation) */
00245 /*! Multiple data message caller ID */
00246 #define CLIP_MDMF_CALLERID              0x80
00247 /*! Multiple data message message waiting */
00248 #define CLIP_MDMF_MSG_WAITING           0x82
00249 /*! Multiple data message charge information */
00250 #define CLIP_MDMF_CHARGE_INFO           0x86
00251 /*! Multiple data message SMS */
00252 #define CLIP_MDMF_SMS                   0x89
00253 
00254 /*! CLIP message IDs */
00255 /*! Date and time (MMDDHHMM) */
00256 #define CLIP_DATETIME                   0x01
00257 /*! Caller number */
00258 #define CLIP_CALLER_NUMBER              0x02
00259 /*! Dialed number */
00260 #define CLIP_DIALED_NUMBER              0x03
00261 /*! Caller number absent: 'O' or 'P' */
00262 #define CLIP_ABSENCE1                   0x04
00263 /*! Caller's name */
00264 #define CLIP_CALLER_NAME                0x07
00265 /*! Caller's name absent: 'O' or 'P' */
00266 #define CLIP_ABSENCE2                   0x08
00267 /*! Visual indicator */
00268 #define CLIP_VISUAL_INDICATOR           0x0B
00269 /*! Message ID */
00270 #define CLIP_MESSAGE_ID                 0x0D
00271 /*! Voice call, ring-back-when-free call, or msg waiting call */
00272 #define CLIP_CALLTYPE                   0x11
00273 /*! Number of messages */
00274 #define CLIP_NUM_MSG                    0x13
00275 /*! Redirecting number */
00276 #define CLIP_REDIR_NUMBER               0x03
00277 /*! Charge */
00278 #define CLIP_CHARGE                     0x20
00279 /*! Duration of the call */
00280 #define CLIP_DURATION                   0x23
00281 /*! Additional charge */
00282 #define CLIP_ADD_CHARGE                 0x21
00283 /*! Display information */
00284 #define CLIP_DISPLAY_INFO               0x50
00285 /*! Service information */
00286 #define CLIP_SERVICE_INFO               0x55
00287 
00288 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
00289 /*! Single data message caller ID frame   */
00290 #define ACLIP_SDMF_CALLERID             0x04
00291 /*! Multiple data message caller ID frame */
00292 #define ACLIP_MDMF_CALLERID             0x80
00293 
00294 /*! A-CLIP MDM message IDs */
00295 /*! Date and time (MMDDHHMM) */
00296 #define ACLIP_DATETIME                  0x01
00297 /*! Caller number */
00298 #define ACLIP_CALLER_NUMBER             0x02
00299 /*! Dialed number */
00300 #define ACLIP_DIALED_NUMBER             0x03
00301 /*! Caller number absent: 'O' or 'P' */
00302 #define ACLIP_NUMBER_ABSENCE            0x04
00303 /*! Call forward: universal, on busy, or on unanswered */
00304 #define ACLIP_REDIRECT                  0x05
00305 /*! Long distance call: 'L' */
00306 #define ACLIP_QUALIFIER                 0x06
00307 /*! Caller's name */
00308 #define ACLIP_CALLER_NAME               0x07
00309 /*! Caller's name absent: 'O' or 'P' */
00310 #define ACLIP_NAME_ABSENCE              0x08
00311 
00312 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
00313 /*! Multiple data message caller ID frame */
00314 #define JCLIP_MDMF_CALLERID             0x40
00315 
00316 /*! J-CLIP MDM message IDs */
00317 /*! Caller number */
00318 #define JCLIP_CALLER_NUMBER             0x02
00319 /*! Caller number data extension signal */
00320 #define JCLIP_CALLER_NUM_DES            0x21
00321 /*! Dialed number */
00322 #define JCLIP_DIALED_NUMBER             0x09
00323 /*! Dialed number data extension signal */
00324 #define JCLIP_DIALED_NUM_DES            0x22
00325 /*! Caller number absent: 'C', 'O', 'P' or 'S' */
00326 #define JCLIP_ABSENCE                   0x04
00327 
00328 /*! Definitions for CLIP-DTMF and its variants */
00329 
00330 #define CLIP_DTMF_HASH_TERMINATED       '#'
00331 #define CLIP_DTMF_C_TERMINATED          'C'
00332 
00333 /*! Caller number */
00334 #define CLIP_DTMF_HASH_CALLER_NUMBER    'A'
00335 /*! Caller number absent: private (1), overseas (2) or not available (3) */
00336 #define CLIP_DTMF_HASH_ABSENCE          'D'
00337 /*! Caller ID field with no explicit field type */
00338 #define CLIP_DTMF_HASH_UNSPECIFIED      0
00339 
00340 /*! Caller number */
00341 #define CLIP_DTMF_C_CALLER_NUMBER       'A'
00342 /*! Diverting number */
00343 #define CLIP_DTMF_C_REDIRECT_NUMBER     'D'
00344 /*! Caller number absent: private/restricted (00) or not available (10) */
00345 #define CLIP_DTMF_C_ABSENCE             'B'
00346 
00347 /*!
00348     ADSI transmitter descriptor. This contains all the state information for an ADSI
00349     (caller ID, CLASS, CLIP, ACLIP) transmit channel.
00350  */
00351 typedef struct
00352 {
00353     int standard;
00354 
00355     tone_gen_descriptor_t alert_tone_desc;
00356     tone_gen_state_t alert_tone_gen;
00357     fsk_tx_state_t fsktx;
00358     dtmf_tx_state_t dtmftx;
00359     async_tx_state_t asynctx;
00360     
00361     int tx_signal_on;
00362     
00363     int byte_no;
00364     int bit_pos;
00365     int bit_no;
00366     uint8_t msg[256];
00367     int msg_len;
00368     int preamble_len;
00369     int preamble_ones_len;
00370     int postamble_ones_len;
00371     int stop_bits;
00372     int baudot_shift;
00373     
00374     logging_state_t logging;
00375 } adsi_tx_state_t;
00376 
00377 /*!
00378     ADSI receiver descriptor. This contains all the state information for an ADSI
00379     (caller ID, CLASS, CLIP, ACLIP, JCLIP) receive channel.
00380  */
00381 typedef struct
00382 {
00383     int standard;
00384     put_msg_func_t put_msg;
00385     void *user_data;
00386 
00387     fsk_rx_state_t fskrx;
00388     dtmf_rx_state_t dtmfrx;
00389     async_rx_state_t asyncrx;
00390     
00391     int consecutive_ones;
00392     int bit_pos;
00393     int in_progress;
00394     uint8_t msg[256];
00395     int msg_len;
00396     int baudot_shift;
00397     
00398     /*! A count of the framing errors. */
00399     int framing_errors;
00400 
00401     logging_state_t logging;
00402 } adsi_rx_state_t;
00403 
00404 #if defined(__cplusplus)
00405 extern "C"
00406 {
00407 #endif
00408 
00409 /*! \brief Initialise an ADSI receive context.
00410     \param s The ADSI receive context.
00411     \param standard The code for the ADSI standard to be used.
00412     \param put_msg A callback routine called to deliver the received messages
00413            to the application.
00414     \param user_data An opaque pointer for the callback routine.
00415     \return A pointer to the initialised context, or NULL if there was a problem.
00416 */
00417 adsi_rx_state_t *adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data);
00418 
00419 /*! \brief Receive a chunk of ADSI audio.
00420     \param s The ADSI receive context.
00421     \param amp The audio sample buffer.
00422     \param len The number of samples in the buffer.
00423 */
00424 void 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 adsi_tx_state_t *adsi_tx_init(adsi_tx_state_t *s, int standard);
00432 
00433 /*! \brief Adjust the preamble associated with an ADSI transmit context.
00434     \param s The ADSI transmit context.
00435     \param preamble_len The number of bits of preamble.
00436     \param preamble_ones_len The number of bits of continuous one before a message.
00437     \param postamble_ones_len The number of bits of continuous one after a message.
00438     \param stop_bits The number of stop bits per character.
00439 */
00440 void adsi_tx_set_preamble(adsi_tx_state_t *s,
00441                           int preamble_len,
00442                           int preamble_ones_len,
00443                           int postamble_ones_len,
00444                           int stop_bits);
00445 
00446 /*! \brief Generate a block of ADSI audio samples.
00447     \param s The ADSI transmit context.
00448     \param amp The audio sample buffer.
00449     \param max_len The number of samples to be generated.
00450     \return The number of samples actually generated.
00451 */
00452 int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len);
00453 
00454 /*! \brief Request generation of an ADSI alert tone.
00455     \param s The ADSI transmit context.
00456 */
00457 void adsi_tx_send_alert_tone(adsi_tx_state_t *s);
00458 
00459 /*! \brief Put a message into the input buffer of an ADSI transmit context.
00460     \param s The ADSI transmit context.
00461     \param msg The message.
00462     \param len The length of the message.
00463     \return The length actually added. If a message is already in progress
00464             in the transmitter, this function will return zero, as it will
00465             not successfully add the message to the buffer.
00466 */
00467 int adsi_tx_put_message(adsi_tx_state_t *s, const uint8_t *msg, int len);
00468 
00469 /*! \brief Get a field from an ADSI message.
00470     \param s The ADSI receive context.
00471     \param msg The message buffer.
00472     \param msg_len The length of the message.
00473     \param pos Current position within the message. Set to -1 when starting a message.
00474     \param field_type The type code for the field.
00475     \param field_body Pointer to the body of the field.
00476     \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
00477 */
00478 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);
00479 
00480 /*! \brief Insert the header or a field into an ADSI message.
00481     \param s The ADSI transmit context.
00482     \param msg The message buffer.
00483     \param len The current length of the message.
00484     \param field_type The type code for the new field.
00485     \param field_body Pointer to the body of the new field.
00486     \param field_len The length of the new field.
00487 */
00488 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);
00489 
00490 /*! \brief Return a short name for an ADSI standard
00491     \param standard The code for the standard.
00492     \return A pointer to the name.
00493 */
00494 const char *adsi_standard_to_str(int standard);
00495 
00496 #if defined(__cplusplus)
00497 }
00498 #endif
00499 
00500 #endif
00501 /*- End of file ------------------------------------------------------------*/

Generated on Thu Mar 20 17:20:08 2008 for libspandsp by  doxygen 1.5.5