--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/spandsp-0.0.3/spandsp-0.0.3/src/spandsp/adsi.h	Fri Jun 25 16:00:21 2010 +0200
@@ -0,0 +1,407 @@
+/*
+ * SpanDSP - a series of DSP components for telephony
+ *
+ * adsi.h - Analogue display services interface and other call ID related handling.
+ *
+ * Written by Steve Underwood <steveu@coppice.org>
+ *
+ * Copyright (C) 2003 Steve Underwood
+ *
+ * All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2, as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ *
+ * $Id: adsi.h,v 1.15 2006/10/24 13:22:01 steveu Exp $
+ */
+
+/*! \file */
+
+#if !defined(_ADSI_H_)
+#define _ADSI_H_
+
+/*! \page adsi_page ADSI transmission and reception
+\section adsi_page_sec_1 What does it do?
+Although ADSI has a specific meaning in some places, the term is used here to indicate
+any form of Analogue Display Service Interface, which includes caller ID, SMS, and others.
+
+The ADSI module provides for the transmission and reception of ADSI messages
+in various formats. Currently, the supported formats are:
+    - CLASS (Custom Local Area Signaling Services) standard, published by Bellcore:
+
+    - ACLIP (Analog Calling Line Identity Presentation) standard, published by the
+      Telecommunications Authority of Singapore:
+
+    - CLIP (Calling Line Identity Presentation) standard, published by ETSI.
+
+    - JCLIP (Japanese Calling Line Identity Presentation) standard, published by NTT.
+        
+    - TDD (Telecommunications Device for the Deaf).
+
+\section adsi_page_sec_2 How does it work?
+
+\section adsi_page_sec_2a The Bellcore CLASS specification
+Most FSK based CLI formats are similar to the US CLASS one, which is as follows:
+
+The alert tone for CLI during a call is at least 100ms of silence, then
+2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time,
+this tone is not sent. In the US, CLI is usually sent between the first
+two rings. This silence period is long in the US, so the message fits easily.
+In other places, where the standard ring tone has much smaller silences,
+a line voltage reversal is used to wake up a power saving receiver, then the
+message is sent, then the phone begins to ring.
+    
+The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits
+per second. The message protocol uses 8-bit data words (bytes), each bounded
+by a start bit and a stop bit.
+
+Channel     Carrier     Message     Message     Data        Checksum
+Seizure     Signal      Type        Length      Word(s)     Word
+Signal                  Word        Word
+    
+\section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL
+The channel seizure is 30 continuous bytes of 55h (01010101), including
+the start and stop bits (i.e. 300 bits of alternations in total).
+This provides a detectable alternating function to the CPE (i.e. the
+modem data pump).
+    
+\section adsi_page_sec_2a2 CARRIER SIGNAL
+The carrier signal consists of 180 bits of 1s. This may be reduced to 80
+bits of 1s for caller ID on call waiting.
+    
+\section adsi_page_sec_2a3 MESSAGE TYPE WORD
+Various message types are defined. The common ones for the US CLASS 
+standard are:
+    - Type 0x04 (SDMF) - single data message. Simple caller ID (CND)
+    - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID,
+                         with extra information.
+    
+\section adsi_page_sec_2a4 MESSAGE LENGTH WORD
+The message length word specifies the total number of data words
+to follow.
+    
+\section adsi_page_sec_2a5 DATA WORDS
+The data words contain the actual message.
+    
+\section adsi_page_sec_2a6 CHECKSUM WORD
+The Checksum Word contains the twos complement of the modulo 256
+sum of the other words in the data message (i.e., message type,
+message length, and data words).  The receiving equipment may
+calculate the modulo 256 sum of the received words and add this
+sum to the received checksum word.  A result of zero generally
+indicates that the message was correctly received.  Message
+retransmission is not supported. The sumcheck word should be followed
+by a minimum of two stop bits.
+
+\section adsi_page_sec_2b The ETSI CLIP specification
+The ETSI CLIP specification uses similar messages to the Bellcore specification.
+They are not, however, identical. First, ETSI use the V.23 modem standard, rather
+than Bell 202. Second, different fields, and different message types are available.
+
+\section adsi_page_sec_2e The ETSI caller ID by DTMF specification
+CLI by DTMF is usually sent in a very simple way. The exchange does not give
+any prior warning (no reversal, or ring) to wake up the receiver. It just
+sends one of the following DTMF strings:
+    
+    - A<phone number>#
+    - D1#     Number not available because the caller has restricted it.
+    - D2#     Number not available because the call is international.
+    - D3#     Number not available due to technical reasons.
+*/
+
+enum
+{
+    ADSI_STANDARD_NONE = 0,
+    ADSI_STANDARD_CLASS = 1,
+    ADSI_STANDARD_CLIP = 2,
+    ADSI_STANDARD_ACLIP = 3,
+    ADSI_STANDARD_JCLIP = 4,
+    ADSI_STANDARD_CLIP_DTMF = 5,
+    ADSI_STANDARD_TDD = 6
+};
+
+/* In some of the messages code characters are used, as follows:
+        'C' for public callbox
+        'L' for long distance
+        'O' for overseas
+        'P' for private
+        'S' for service conflict */
+
+/*! Definitions for generic caller ID message type IDs */
+/*! Complete caller ID message */
+#define CLIDINFO_CMPLT          0x100
+/*! Date, time, phone #, name */
+#define CLIDINFO_GENERAL        0x101
+/*! Caller ID */
+#define CLIDINFO_CALLID         0x102
+/*! See frame type equates */
+#define CLIDINFO_FRAMETYPE      0x103
+
+/*! Definitions for CLASS (Custom Local Area Signaling Services) */
+/*! Single data message caller ID */
+#define CLASS_SDMF_CALLERID     0x04
+/*! Multiple data message caller ID */
+#define CLASS_MDMF_CALLERID     0x80
+/*! Single data message message waiting */
+#define CLASS_SDMF_MSG_WAITING  0x06
+/*! Multiple data message message waiting */
+#define CLASS_MDMF_MSG_WAITING  0x82
+
+/*! CLASS MDMF message IDs */
+/*! Date and time (MMDDHHMM) */
+#define MCLASS_DATETIME         0x01
+/*! Caller number */
+#define MCLASS_CALLER_NUMBER    0x02
+/*! Dialed number */
+#define MCLASS_DIALED_NUMBER    0x03
+/*! Caller number absent: 'O' or 'P' */
+#define MCLASS_ABSENCE1         0x04
+/*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
+#define MCLASS_REDIRECT         0x05
+/*! Long distance: 'L' */
+#define MCLASS_QUALIFIER        0x06
+/*! Caller's name */
+#define MCLASS_CALLER_NAME      0x07
+/*! Caller's name absent: 'O' or 'P' */
+#define MCLASS_ABSENCE2         0x08
+
+/*! CLASS MDMF message waiting message IDs */
+/*! Message waiting/not waiting */
+#define MCLASS_VISUAL_INDICATOR 0x0B
+
+/*! Definitions for CLIP (Calling Line Identity Presentation) */
+/*! Multiple data message caller ID */
+#define CLIP_MDMF_CALLERID      0x80
+/*! Multiple data message message waiting */
+#define CLIP_MDMF_MSG_WAITING   0x82
+/*! Multiple data message charge information */
+#define CLIP_MDMF_CHARGE_INFO   0x86
+/*! Multiple data message SMS */
+#define CLIP_MDMF_SMS           0x89
+
+/*! CLIP message IDs */
+/*! Date and time (MMDDHHMM) */
+#define CLIP_DATETIME           0x01
+/*! Caller number */
+#define CLIP_CALLER_NUMBER      0x02
+/*! Dialed number */
+#define CLIP_DIALED_NUMBER      0x03
+/*! Caller number absent: 'O' or 'P' */
+#define CLIP_ABSENCE1           0x04
+/*! Caller's name */
+#define CLIP_CALLER_NAME        0x07
+/*! Caller's name absent: 'O' or 'P' */
+#define CLIP_ABSENCE2           0x08
+/*! Visual indicator */
+#define CLIP_VISUAL_INDICATOR   0x0B
+/*! Message ID */
+#define CLIP_MESSAGE_ID         0x0D
+/*! Voice call, ring-back-when-free call, or msg waiting call */
+#define CLIP_CALLTYPE           0x11
+/*! Number of messages */
+#define CLIP_NUM_MSG            0x13
+/*! Redirecting number */
+#define CLIP_REDIR_NUMBER       0x03
+/*! Charge */
+#define CLIP_CHARGE             0x20
+/*! Duration of the call */
+#define CLIP_DURATION           0x23
+/*! Additional charge */
+#define CLIP_ADD_CHARGE         0x21
+/*! Display information */
+#define CLIP_DISPLAY_INFO       0x50
+/*! Service information */
+#define CLIP_SERVICE_INFO       0x55
+
+/*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
+/*! Single data message caller ID frame   */
+#define ACLIP_SDMF_CALLERID     0x04
+/*! Multiple data message caller ID frame */
+#define ACLIP_MDMF_CALLERID     0x80
+
+/*! A-CLIP MDM message IDs */
+/*! Date and time (MMDDHHMM) */
+#define ACLIP_DATETIME          0x01
+/*! Caller number */
+#define ACLIP_CALLER_NUMBER     0x02
+/*! Dialed number */
+#define ACLIP_DIALED_NUMBER     0x03
+/*! Caller number absent: 'O' or 'P' */
+#define ACLIP_ABSENCE1          0x04
+/*! Call forward: universal, on busy, or on unanswered */
+#define ACLIP_REDIRECT          0x05
+/*! Long distance call: 'L' */
+#define ACLIP_QUALIFIER         0x06
+/*! Caller's name */
+#define ACLIP_CALLER_NAME       0x07
+/*! Caller's name absent: 'O' or 'P' */
+#define ACLIP_ABSENCE2          0x08
+
+/*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
+/*! Multiple data message caller ID frame */
+#define JCLIP_MDMF_CALLERID     0x40
+
+/*! J-CLIP MDM message IDs */
+/*! Caller number */
+#define JCLIP_CALLER_NUMBER     0x02
+/*! Caller number data extension signal */
+#define JCLIP_CALLER_NUM_DES    0x21
+/*! Dialed number */
+#define JCLIP_DIALED_NUMBER     0x09
+/*! Dialed number data extension signal */
+#define JCLIP_DIALED_NUM_DES    0x22
+/*! Caller number absent: 'C', 'O', 'P' or 'S' */
+#define JCLIP_ABSENCE           0x04
+
+/*! Definitions for CLIP-DTMF */
+/*! Caller number */
+#define CLIP_DTMF_CALLER_NUMBER 'A'
+/*! Caller number absent: private (1), overseas (2) or not available (3) */
+#define CLIP_DTMF_ABSENCE1      'D'
+
+/*!
+    ADSI transmitter descriptor. This contains all the state information for an ADSI
+    (caller ID, CLASS, CLIP, ACLIP) transmit channel.
+ */
+typedef struct
+{
+    int standard;
+
+    tone_gen_descriptor_t alert_tone_desc;
+    tone_gen_state_t alert_tone_gen;
+    fsk_tx_state_t fsktx;
+    dtmf_tx_state_t dtmftx;
+    async_tx_state_t asynctx;
+    
+    int tx_signal_on;
+    
+    int byteno;
+    int bitpos;
+    int bitno;
+    uint8_t msg[256];
+    int msg_len;
+    int ones_len;
+    int baudot_shift;
+    
+    logging_state_t logging;
+} adsi_tx_state_t;
+
+/*!
+    ADSI receiver descriptor. This contains all the state information for an ADSI
+    (caller ID, CLASS, CLIP, ACLIP) receive channel.
+ */
+typedef struct
+{
+    put_msg_func_t put_msg;
+    void *user_data;
+    int standard;
+
+    fsk_rx_state_t fskrx;
+    dtmf_rx_state_t dtmfrx;
+    async_rx_state_t asyncrx;
+    
+    int consecutive_ones;
+    int bitpos;
+    int in_progress;
+    uint8_t msg[256];
+    int msg_len;
+    int baudot_shift;
+    
+    /*! A count of the framing errors. */
+    int framing_errors;
+
+    logging_state_t logging;
+} adsi_rx_state_t;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*! \brief Initialise an ADSI receive context.
+    \param s The ADSI receive context.
+    \param standard The code for the ADSI standard to be used.
+    \param put_msg A callback routine called to deliver the received messages
+           to the application.
+    \param user_data An opaque pointer for the callback routine.
+*/
+void adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data);
+
+/*! \brief Receive a chunk of ADSI audio.
+    \param s The ADSI receive context.
+    \param amp The audio sample buffer.
+    \param len The number of samples in the buffer.
+*/
+void adsi_rx(adsi_rx_state_t *s, const int16_t *amp, int len);
+
+/*! \brief Initialise an ADSI transmit context.
+    \param s The ADSI transmit context.
+    \param standard The code for the ADSI standard to be used.
+*/
+void adsi_tx_init(adsi_tx_state_t *s, int standard);
+
+/*! \brief Generate a block of ADSI audio samples.
+    \param s The ADSI transmit context.
+    \param amp The audio sample buffer.
+    \param max_len The number of samples to be generated.
+    \return The number of samples actually generated.
+*/
+int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len);
+
+/*! \brief Request generation of an ADSI alert tone.
+    \param s The ADSI transmit context.
+*/
+void adsi_send_alert_tone(adsi_tx_state_t *s);
+
+/*! \brief Put a message into the input buffer of an ADSI transmit context.
+    \param s The ADSI transmit context.
+    \param msg The message.
+    \param len The length of the message.
+    \return The length actually added. If a message is already in progress
+            in the transmitter, this function will return zero, as it will
+            not successfully add the message to the buffer.
+*/
+int adsi_put_message(adsi_tx_state_t *s, uint8_t *msg, int len);
+
+/*! \brief Get a field from an ADSI message.
+    \param s The ADSI receive context.
+    \param msg The message buffer.
+    \param msg_len The length of the message.
+    \param pos Current position within the message. Set to -1 when starting a message.
+    \param field_type The type code for the field.
+    \param field_body Pointer to the body of the field.
+    \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
+*/
+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);
+
+/*! \brief Insert the header or a field into an ADSI message.
+    \param s The ADSI transmit context.
+    \param msg The message buffer.
+    \param len The current length of the message.
+    \param field_type The type code for the new field.
+    \param field_body Pointer to the body of the new field.
+    \param field_len The length of the new field.
+*/
+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);
+
+/*! \brief Return a short name for an ADSI standard
+    \param standard The code for the standard.
+    \return A pointer to the name.
+*/
+const char *adsi_standard_to_str(int standard);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+/*- End of file ------------------------------------------------------------*/