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

Generated on Tue Aug 4 03:35:53 2009 for spandsp by  doxygen 1.5.9