|
5
|
1 /*
|
|
|
2 * SpanDSP - a series of DSP components for telephony
|
|
|
3 *
|
|
|
4 * adsi.h - Analogue display services interface and other call ID related handling.
|
|
|
5 *
|
|
|
6 * Written by Steve Underwood <steveu@coppice.org>
|
|
|
7 *
|
|
|
8 * Copyright (C) 2003 Steve Underwood
|
|
|
9 *
|
|
|
10 * All rights reserved.
|
|
|
11 *
|
|
|
12 * This program is free software; you can redistribute it and/or modify
|
|
|
13 * it under the terms of the GNU General Public License version 2, as
|
|
|
14 * published by the Free Software Foundation.
|
|
|
15 *
|
|
|
16 * This program is distributed in the hope that it will be useful,
|
|
|
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
19 * GNU General Public License for more details.
|
|
|
20 *
|
|
|
21 * You should have received a copy of the GNU General Public License
|
|
|
22 * along with this program; if not, write to the Free Software
|
|
|
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
24 *
|
|
|
25 * $Id: adsi.h,v 1.15 2006/10/24 13:22:01 steveu Exp $
|
|
|
26 */
|
|
|
27
|
|
|
28 /*! \file */
|
|
|
29
|
|
|
30 #if !defined(_ADSI_H_)
|
|
|
31 #define _ADSI_H_
|
|
|
32
|
|
|
33 /*! \page adsi_page ADSI transmission and reception
|
|
|
34 \section adsi_page_sec_1 What does it do?
|
|
|
35 Although ADSI has a specific meaning in some places, the term is used here to indicate
|
|
|
36 any form of Analogue Display Service Interface, which includes caller ID, SMS, and others.
|
|
|
37
|
|
|
38 The ADSI module provides for the transmission and reception of ADSI messages
|
|
|
39 in various formats. Currently, the supported formats are:
|
|
|
40 - CLASS (Custom Local Area Signaling Services) standard, published by Bellcore:
|
|
|
41
|
|
|
42 - ACLIP (Analog Calling Line Identity Presentation) standard, published by the
|
|
|
43 Telecommunications Authority of Singapore:
|
|
|
44
|
|
|
45 - CLIP (Calling Line Identity Presentation) standard, published by ETSI.
|
|
|
46
|
|
|
47 - JCLIP (Japanese Calling Line Identity Presentation) standard, published by NTT.
|
|
|
48
|
|
|
49 - TDD (Telecommunications Device for the Deaf).
|
|
|
50
|
|
|
51 \section adsi_page_sec_2 How does it work?
|
|
|
52
|
|
|
53 \section adsi_page_sec_2a The Bellcore CLASS specification
|
|
|
54 Most FSK based CLI formats are similar to the US CLASS one, which is as follows:
|
|
|
55
|
|
|
56 The alert tone for CLI during a call is at least 100ms of silence, then
|
|
|
57 2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time,
|
|
|
58 this tone is not sent. In the US, CLI is usually sent between the first
|
|
|
59 two rings. This silence period is long in the US, so the message fits easily.
|
|
|
60 In other places, where the standard ring tone has much smaller silences,
|
|
|
61 a line voltage reversal is used to wake up a power saving receiver, then the
|
|
|
62 message is sent, then the phone begins to ring.
|
|
|
63
|
|
|
64 The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits
|
|
|
65 per second. The message protocol uses 8-bit data words (bytes), each bounded
|
|
|
66 by a start bit and a stop bit.
|
|
|
67
|
|
|
68 Channel Carrier Message Message Data Checksum
|
|
|
69 Seizure Signal Type Length Word(s) Word
|
|
|
70 Signal Word Word
|
|
|
71
|
|
|
72 \section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL
|
|
|
73 The channel seizure is 30 continuous bytes of 55h (01010101), including
|
|
|
74 the start and stop bits (i.e. 300 bits of alternations in total).
|
|
|
75 This provides a detectable alternating function to the CPE (i.e. the
|
|
|
76 modem data pump).
|
|
|
77
|
|
|
78 \section adsi_page_sec_2a2 CARRIER SIGNAL
|
|
|
79 The carrier signal consists of 180 bits of 1s. This may be reduced to 80
|
|
|
80 bits of 1s for caller ID on call waiting.
|
|
|
81
|
|
|
82 \section adsi_page_sec_2a3 MESSAGE TYPE WORD
|
|
|
83 Various message types are defined. The common ones for the US CLASS
|
|
|
84 standard are:
|
|
|
85 - Type 0x04 (SDMF) - single data message. Simple caller ID (CND)
|
|
|
86 - Type 0x80 (MDMF) - multiple data message. A more flexible caller ID,
|
|
|
87 with extra information.
|
|
|
88
|
|
|
89 \section adsi_page_sec_2a4 MESSAGE LENGTH WORD
|
|
|
90 The message length word specifies the total number of data words
|
|
|
91 to follow.
|
|
|
92
|
|
|
93 \section adsi_page_sec_2a5 DATA WORDS
|
|
|
94 The data words contain the actual message.
|
|
|
95
|
|
|
96 \section adsi_page_sec_2a6 CHECKSUM WORD
|
|
|
97 The Checksum Word contains the twos complement of the modulo 256
|
|
|
98 sum of the other words in the data message (i.e., message type,
|
|
|
99 message length, and data words). The receiving equipment may
|
|
|
100 calculate the modulo 256 sum of the received words and add this
|
|
|
101 sum to the received checksum word. A result of zero generally
|
|
|
102 indicates that the message was correctly received. Message
|
|
|
103 retransmission is not supported. The sumcheck word should be followed
|
|
|
104 by a minimum of two stop bits.
|
|
|
105
|
|
|
106 \section adsi_page_sec_2b The ETSI CLIP specification
|
|
|
107 The ETSI CLIP specification uses similar messages to the Bellcore specification.
|
|
|
108 They are not, however, identical. First, ETSI use the V.23 modem standard, rather
|
|
|
109 than Bell 202. Second, different fields, and different message types are available.
|
|
|
110
|
|
|
111 \section adsi_page_sec_2e The ETSI caller ID by DTMF specification
|
|
|
112 CLI by DTMF is usually sent in a very simple way. The exchange does not give
|
|
|
113 any prior warning (no reversal, or ring) to wake up the receiver. It just
|
|
|
114 sends one of the following DTMF strings:
|
|
|
115
|
|
|
116 - A<phone number>#
|
|
|
117 - D1# Number not available because the caller has restricted it.
|
|
|
118 - D2# Number not available because the call is international.
|
|
|
119 - D3# Number not available due to technical reasons.
|
|
|
120 */
|
|
|
121
|
|
|
122 enum
|
|
|
123 {
|
|
|
124 ADSI_STANDARD_NONE = 0,
|
|
|
125 ADSI_STANDARD_CLASS = 1,
|
|
|
126 ADSI_STANDARD_CLIP = 2,
|
|
|
127 ADSI_STANDARD_ACLIP = 3,
|
|
|
128 ADSI_STANDARD_JCLIP = 4,
|
|
|
129 ADSI_STANDARD_CLIP_DTMF = 5,
|
|
|
130 ADSI_STANDARD_TDD = 6
|
|
|
131 };
|
|
|
132
|
|
|
133 /* In some of the messages code characters are used, as follows:
|
|
|
134 'C' for public callbox
|
|
|
135 'L' for long distance
|
|
|
136 'O' for overseas
|
|
|
137 'P' for private
|
|
|
138 'S' for service conflict */
|
|
|
139
|
|
|
140 /*! Definitions for generic caller ID message type IDs */
|
|
|
141 /*! Complete caller ID message */
|
|
|
142 #define CLIDINFO_CMPLT 0x100
|
|
|
143 /*! Date, time, phone #, name */
|
|
|
144 #define CLIDINFO_GENERAL 0x101
|
|
|
145 /*! Caller ID */
|
|
|
146 #define CLIDINFO_CALLID 0x102
|
|
|
147 /*! See frame type equates */
|
|
|
148 #define CLIDINFO_FRAMETYPE 0x103
|
|
|
149
|
|
|
150 /*! Definitions for CLASS (Custom Local Area Signaling Services) */
|
|
|
151 /*! Single data message caller ID */
|
|
|
152 #define CLASS_SDMF_CALLERID 0x04
|
|
|
153 /*! Multiple data message caller ID */
|
|
|
154 #define CLASS_MDMF_CALLERID 0x80
|
|
|
155 /*! Single data message message waiting */
|
|
|
156 #define CLASS_SDMF_MSG_WAITING 0x06
|
|
|
157 /*! Multiple data message message waiting */
|
|
|
158 #define CLASS_MDMF_MSG_WAITING 0x82
|
|
|
159
|
|
|
160 /*! CLASS MDMF message IDs */
|
|
|
161 /*! Date and time (MMDDHHMM) */
|
|
|
162 #define MCLASS_DATETIME 0x01
|
|
|
163 /*! Caller number */
|
|
|
164 #define MCLASS_CALLER_NUMBER 0x02
|
|
|
165 /*! Dialed number */
|
|
|
166 #define MCLASS_DIALED_NUMBER 0x03
|
|
|
167 /*! Caller number absent: 'O' or 'P' */
|
|
|
168 #define MCLASS_ABSENCE1 0x04
|
|
|
169 /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
|
|
|
170 #define MCLASS_REDIRECT 0x05
|
|
|
171 /*! Long distance: 'L' */
|
|
|
172 #define MCLASS_QUALIFIER 0x06
|
|
|
173 /*! Caller's name */
|
|
|
174 #define MCLASS_CALLER_NAME 0x07
|
|
|
175 /*! Caller's name absent: 'O' or 'P' */
|
|
|
176 #define MCLASS_ABSENCE2 0x08
|
|
|
177
|
|
|
178 /*! CLASS MDMF message waiting message IDs */
|
|
|
179 /*! Message waiting/not waiting */
|
|
|
180 #define MCLASS_VISUAL_INDICATOR 0x0B
|
|
|
181
|
|
|
182 /*! Definitions for CLIP (Calling Line Identity Presentation) */
|
|
|
183 /*! Multiple data message caller ID */
|
|
|
184 #define CLIP_MDMF_CALLERID 0x80
|
|
|
185 /*! Multiple data message message waiting */
|
|
|
186 #define CLIP_MDMF_MSG_WAITING 0x82
|
|
|
187 /*! Multiple data message charge information */
|
|
|
188 #define CLIP_MDMF_CHARGE_INFO 0x86
|
|
|
189 /*! Multiple data message SMS */
|
|
|
190 #define CLIP_MDMF_SMS 0x89
|
|
|
191
|
|
|
192 /*! CLIP message IDs */
|
|
|
193 /*! Date and time (MMDDHHMM) */
|
|
|
194 #define CLIP_DATETIME 0x01
|
|
|
195 /*! Caller number */
|
|
|
196 #define CLIP_CALLER_NUMBER 0x02
|
|
|
197 /*! Dialed number */
|
|
|
198 #define CLIP_DIALED_NUMBER 0x03
|
|
|
199 /*! Caller number absent: 'O' or 'P' */
|
|
|
200 #define CLIP_ABSENCE1 0x04
|
|
|
201 /*! Caller's name */
|
|
|
202 #define CLIP_CALLER_NAME 0x07
|
|
|
203 /*! Caller's name absent: 'O' or 'P' */
|
|
|
204 #define CLIP_ABSENCE2 0x08
|
|
|
205 /*! Visual indicator */
|
|
|
206 #define CLIP_VISUAL_INDICATOR 0x0B
|
|
|
207 /*! Message ID */
|
|
|
208 #define CLIP_MESSAGE_ID 0x0D
|
|
|
209 /*! Voice call, ring-back-when-free call, or msg waiting call */
|
|
|
210 #define CLIP_CALLTYPE 0x11
|
|
|
211 /*! Number of messages */
|
|
|
212 #define CLIP_NUM_MSG 0x13
|
|
|
213 /*! Redirecting number */
|
|
|
214 #define CLIP_REDIR_NUMBER 0x03
|
|
|
215 /*! Charge */
|
|
|
216 #define CLIP_CHARGE 0x20
|
|
|
217 /*! Duration of the call */
|
|
|
218 #define CLIP_DURATION 0x23
|
|
|
219 /*! Additional charge */
|
|
|
220 #define CLIP_ADD_CHARGE 0x21
|
|
|
221 /*! Display information */
|
|
|
222 #define CLIP_DISPLAY_INFO 0x50
|
|
|
223 /*! Service information */
|
|
|
224 #define CLIP_SERVICE_INFO 0x55
|
|
|
225
|
|
|
226 /*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
|
|
|
227 /*! Single data message caller ID frame */
|
|
|
228 #define ACLIP_SDMF_CALLERID 0x04
|
|
|
229 /*! Multiple data message caller ID frame */
|
|
|
230 #define ACLIP_MDMF_CALLERID 0x80
|
|
|
231
|
|
|
232 /*! A-CLIP MDM message IDs */
|
|
|
233 /*! Date and time (MMDDHHMM) */
|
|
|
234 #define ACLIP_DATETIME 0x01
|
|
|
235 /*! Caller number */
|
|
|
236 #define ACLIP_CALLER_NUMBER 0x02
|
|
|
237 /*! Dialed number */
|
|
|
238 #define ACLIP_DIALED_NUMBER 0x03
|
|
|
239 /*! Caller number absent: 'O' or 'P' */
|
|
|
240 #define ACLIP_ABSENCE1 0x04
|
|
|
241 /*! Call forward: universal, on busy, or on unanswered */
|
|
|
242 #define ACLIP_REDIRECT 0x05
|
|
|
243 /*! Long distance call: 'L' */
|
|
|
244 #define ACLIP_QUALIFIER 0x06
|
|
|
245 /*! Caller's name */
|
|
|
246 #define ACLIP_CALLER_NAME 0x07
|
|
|
247 /*! Caller's name absent: 'O' or 'P' */
|
|
|
248 #define ACLIP_ABSENCE2 0x08
|
|
|
249
|
|
|
250 /*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
|
|
|
251 /*! Multiple data message caller ID frame */
|
|
|
252 #define JCLIP_MDMF_CALLERID 0x40
|
|
|
253
|
|
|
254 /*! J-CLIP MDM message IDs */
|
|
|
255 /*! Caller number */
|
|
|
256 #define JCLIP_CALLER_NUMBER 0x02
|
|
|
257 /*! Caller number data extension signal */
|
|
|
258 #define JCLIP_CALLER_NUM_DES 0x21
|
|
|
259 /*! Dialed number */
|
|
|
260 #define JCLIP_DIALED_NUMBER 0x09
|
|
|
261 /*! Dialed number data extension signal */
|
|
|
262 #define JCLIP_DIALED_NUM_DES 0x22
|
|
|
263 /*! Caller number absent: 'C', 'O', 'P' or 'S' */
|
|
|
264 #define JCLIP_ABSENCE 0x04
|
|
|
265
|
|
|
266 /*! Definitions for CLIP-DTMF */
|
|
|
267 /*! Caller number */
|
|
|
268 #define CLIP_DTMF_CALLER_NUMBER 'A'
|
|
|
269 /*! Caller number absent: private (1), overseas (2) or not available (3) */
|
|
|
270 #define CLIP_DTMF_ABSENCE1 'D'
|
|
|
271
|
|
|
272 /*!
|
|
|
273 ADSI transmitter descriptor. This contains all the state information for an ADSI
|
|
|
274 (caller ID, CLASS, CLIP, ACLIP) transmit channel.
|
|
|
275 */
|
|
|
276 typedef struct
|
|
|
277 {
|
|
|
278 int standard;
|
|
|
279
|
|
|
280 tone_gen_descriptor_t alert_tone_desc;
|
|
|
281 tone_gen_state_t alert_tone_gen;
|
|
|
282 fsk_tx_state_t fsktx;
|
|
|
283 dtmf_tx_state_t dtmftx;
|
|
|
284 async_tx_state_t asynctx;
|
|
|
285
|
|
|
286 int tx_signal_on;
|
|
|
287
|
|
|
288 int byteno;
|
|
|
289 int bitpos;
|
|
|
290 int bitno;
|
|
|
291 uint8_t msg[256];
|
|
|
292 int msg_len;
|
|
|
293 int ones_len;
|
|
|
294 int baudot_shift;
|
|
|
295
|
|
|
296 logging_state_t logging;
|
|
|
297 } adsi_tx_state_t;
|
|
|
298
|
|
|
299 /*!
|
|
|
300 ADSI receiver descriptor. This contains all the state information for an ADSI
|
|
|
301 (caller ID, CLASS, CLIP, ACLIP) receive channel.
|
|
|
302 */
|
|
|
303 typedef struct
|
|
|
304 {
|
|
|
305 put_msg_func_t put_msg;
|
|
|
306 void *user_data;
|
|
|
307 int standard;
|
|
|
308
|
|
|
309 fsk_rx_state_t fskrx;
|
|
|
310 dtmf_rx_state_t dtmfrx;
|
|
|
311 async_rx_state_t asyncrx;
|
|
|
312
|
|
|
313 int consecutive_ones;
|
|
|
314 int bitpos;
|
|
|
315 int in_progress;
|
|
|
316 uint8_t msg[256];
|
|
|
317 int msg_len;
|
|
|
318 int baudot_shift;
|
|
|
319
|
|
|
320 /*! A count of the framing errors. */
|
|
|
321 int framing_errors;
|
|
|
322
|
|
|
323 logging_state_t logging;
|
|
|
324 } adsi_rx_state_t;
|
|
|
325
|
|
|
326 #ifdef __cplusplus
|
|
|
327 extern "C" {
|
|
|
328 #endif
|
|
|
329
|
|
|
330 /*! \brief Initialise an ADSI receive context.
|
|
|
331 \param s The ADSI receive context.
|
|
|
332 \param standard The code for the ADSI standard to be used.
|
|
|
333 \param put_msg A callback routine called to deliver the received messages
|
|
|
334 to the application.
|
|
|
335 \param user_data An opaque pointer for the callback routine.
|
|
|
336 */
|
|
|
337 void adsi_rx_init(adsi_rx_state_t *s, int standard, put_msg_func_t put_msg, void *user_data);
|
|
|
338
|
|
|
339 /*! \brief Receive a chunk of ADSI audio.
|
|
|
340 \param s The ADSI receive context.
|
|
|
341 \param amp The audio sample buffer.
|
|
|
342 \param len The number of samples in the buffer.
|
|
|
343 */
|
|
|
344 void adsi_rx(adsi_rx_state_t *s, const int16_t *amp, int len);
|
|
|
345
|
|
|
346 /*! \brief Initialise an ADSI transmit context.
|
|
|
347 \param s The ADSI transmit context.
|
|
|
348 \param standard The code for the ADSI standard to be used.
|
|
|
349 */
|
|
|
350 void adsi_tx_init(adsi_tx_state_t *s, int standard);
|
|
|
351
|
|
|
352 /*! \brief Generate a block of ADSI audio samples.
|
|
|
353 \param s The ADSI transmit context.
|
|
|
354 \param amp The audio sample buffer.
|
|
|
355 \param max_len The number of samples to be generated.
|
|
|
356 \return The number of samples actually generated.
|
|
|
357 */
|
|
|
358 int adsi_tx(adsi_tx_state_t *s, int16_t *amp, int max_len);
|
|
|
359
|
|
|
360 /*! \brief Request generation of an ADSI alert tone.
|
|
|
361 \param s The ADSI transmit context.
|
|
|
362 */
|
|
|
363 void adsi_send_alert_tone(adsi_tx_state_t *s);
|
|
|
364
|
|
|
365 /*! \brief Put a message into the input buffer of an ADSI transmit context.
|
|
|
366 \param s The ADSI transmit context.
|
|
|
367 \param msg The message.
|
|
|
368 \param len The length of the message.
|
|
|
369 \return The length actually added. If a message is already in progress
|
|
|
370 in the transmitter, this function will return zero, as it will
|
|
|
371 not successfully add the message to the buffer.
|
|
|
372 */
|
|
|
373 int adsi_put_message(adsi_tx_state_t *s, uint8_t *msg, int len);
|
|
|
374
|
|
|
375 /*! \brief Get a field from an ADSI message.
|
|
|
376 \param s The ADSI receive context.
|
|
|
377 \param msg The message buffer.
|
|
|
378 \param msg_len The length of the message.
|
|
|
379 \param pos Current position within the message. Set to -1 when starting a message.
|
|
|
380 \param field_type The type code for the field.
|
|
|
381 \param field_body Pointer to the body of the field.
|
|
|
382 \param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
|
|
|
383 */
|
|
|
384 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);
|
|
|
385
|
|
|
386 /*! \brief Insert the header or a field into an ADSI message.
|
|
|
387 \param s The ADSI transmit context.
|
|
|
388 \param msg The message buffer.
|
|
|
389 \param len The current length of the message.
|
|
|
390 \param field_type The type code for the new field.
|
|
|
391 \param field_body Pointer to the body of the new field.
|
|
|
392 \param field_len The length of the new field.
|
|
|
393 */
|
|
|
394 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);
|
|
|
395
|
|
|
396 /*! \brief Return a short name for an ADSI standard
|
|
|
397 \param standard The code for the standard.
|
|
|
398 \return A pointer to the name.
|
|
|
399 */
|
|
|
400 const char *adsi_standard_to_str(int standard);
|
|
|
401
|
|
|
402 #ifdef __cplusplus
|
|
|
403 }
|
|
|
404 #endif
|
|
|
405
|
|
|
406 #endif
|
|
|
407 /*- End of file ------------------------------------------------------------*/
|
