spandsp
0.0.6
Main Page
Related Pages
Classes
Files
File List
File Members
adsi.h
Go to the documentation of this file.
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 Lesser General Public License version 2.1,
14
* as 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 Lesser General Public License for more details.
20
*
21
* You should have received a copy of the GNU Lesser General Public
22
* License along with this program; if not, write to the Free Software
23
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24
*/
25
26
/*! \file */
27
28
#if !defined(_SPANDSP_ADSI_H_)
29
#define _SPANDSP_ADSI_H_
30
31
/*! \page adsi_page ADSI transmission and reception
32
\section adsi_page_sec_1 What does it do?
33
Although ADSI has a specific meaning in some places, the term is used here to indicate
34
any form of Analogue Display Service Interface, which includes caller ID, SMS, and others.
35
36
The ADSI module provides for the transmission and reception of ADSI messages
37
in various formats. Currently, the supported formats are:
38
39
- Bellcore/Telcordia GR-30 CORE CLASS (Custom Local Area Signaling Services) standard
40
(North America, Australia, China, Taiwan, and Hong Kong).
41
42
- ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) FSK standard
43
(France, Germany, Norway, Italy, Spain, South Africa, Turkey, and the UK).
44
45
- ETSI Caller-ID support for the UK, British Telecom SIN227 and SIN242.
46
47
- ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
48
variant 1 (Belgium, Brazil, Denmark, Finland, Iceland, India, Netherlands, Saudi Arabia,
49
Sweden and Uruguay).
50
51
- ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
52
variant 2 (Denmark and Holland).
53
54
- ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
55
variant 3.
56
57
- ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
58
variant 4. (Taiwan and Kuwait).
59
60
- ETSI Caller-ID support in UK (British Telecom), British Telecomm SIN227, SIN242.
61
62
- Nippon Telegraph & Telephone Corporation JCLIP (Japanese Calling Line Identity
63
Presentation) standard.
64
65
- Telecommunications Authority of Singapore ACLIP (Analog Calling Line Identity
66
Presentation) standard.
67
68
- TDD (Telecommunications Device for the Deaf).
69
70
\section adsi_page_sec_2 How does it work?
71
72
\section adsi_page_sec_2a The Bellcore CLASS specification
73
Most FSK based CLI formats are similar to the US CLASS one, which is as follows:
74
75
The alert tone for CLI during a call is at least 100ms of silence, then
76
2130Hz + 2750Hz for 88ms to 110ms. When CLI is presented at ringing time,
77
this tone is not sent. In the US, CLI is usually sent between the first
78
two rings. This silence period is long in the US, so the message fits easily.
79
In other places, where the standard ring tone has much smaller silences,
80
a line voltage reversal is used to wake up a power saving receiver, then the
81
message is sent, then the phone begins to ring.
82
83
The message is sent using a Bell 202 FSK modem. The data rate is 1200 bits
84
per second. The message protocol uses 8-bit data words (bytes), each bounded
85
by a start bit and a stop bit.
86
87
Channel Carrier Message Message Data Checksum
88
Seizure Signal Type Length Word(s) Word
89
Signal Word Word
90
91
\section adsi_page_sec_2a1 CHANNEL SEIZURE SIGNAL
92
The channel seizure is 30 continuous bytes of 55h (01010101), including
93
the start and stop bits (i.e. 300 bits of alternations in total).
94
This provides a detectable alternating function to the CPE (i.e. the
95
modem data pump).
96
97
\section adsi_page_sec_2a2 CARRIER SIGNAL
98
The carrier signal consists of 180 bits of 1s. This may be reduced to 80
99
bits of 1s for caller ID on call waiting.
100
101
\section adsi_page_sec_2a3 MESSAGE TYPE WORD
102
Various message types are defined. The commonest ones for the US CLASS
103
standard are:
104
105
- Type 0x04 (SDMF) - single data message. Simple caller ID (CND)
106
- Type 0x80 (MDMF) - multiple data message. A more flexible caller ID,
107
with extra information.
108
109
Other messages support message waiting, for voice mail, and other display features.
110
111
\section adsi_page_sec_2a4 MESSAGE LENGTH WORD
112
The message length word specifies the total number of data words
113
to follow.
114
115
\section adsi_page_sec_2a5 DATA WORDS
116
The data words contain the actual message.
117
118
\section adsi_page_sec_2a6 CHECKSUM WORD
119
The Checksum Word contains the twos complement of the modulo 256
120
sum of the other words in the data message (i.e., message type,
121
message length, and data words). The receiving equipment may
122
calculate the modulo 256 sum of the received words and add this
123
sum to the received checksum word. A result of zero generally
124
indicates that the message was correctly received. Message
125
retransmission is not supported. The sumcheck word should be followed
126
by a minimum of two stop bits.
127
128
\section adsi_page_sec_2b The ETSI CLIP specification
129
The ETSI CLIP specification uses similar messages to the Bellcore specification.
130
They are not, however, identical. First, ETSI use the V.23 modem standard, rather
131
than Bell 202. Second, different fields, and different message types are available.
132
133
The wake up indication generally differs from the Bellcore specification, to
134
accomodate differences in European ring cadences.
135
136
\section adsi_page_sec_2c The ETSI caller ID by DTMF specification
137
CLI by DTMF is usually sent in a very simple way. The exchange does not give
138
any prior warning (no reversal, or ring) to wake up the receiver. It just
139
sends a string of DTMF digits. Around the world several variants of this
140
basic scheme are used.
141
142
One variant of the digit string is used in Belgium, Brazil, Denmark, Finland, Iceland,
143
India, Netherlands, Saudi Arabia, Sweden and Uruguay:
144
145
- A<caller's phone number>D<redirected number>B<special information>C
146
147
Each of these fields may be omitted. The following special information codes are defined
148
149
- "00" indicates the calling party number is not available.
150
- "10" indicates that the presentation of the calling party number is restricted.
151
152
A second variant of the digit string is one of the following:
153
154
- A<caller's phone number>#
155
- D1# Number not available because the caller has restricted it.
156
- D2# Number not available because the call is international.
157
- D3# Number not available due to technical reasons.
158
159
A third variant of the digit string is used in Taiwan and Kuwait:
160
161
- D<caller's phone number>C
162
163
A forth variant of the digit string is used in Denmark and Holland:
164
165
- <caller's phone number>#
166
167
There is no distinctive start marker in this format.
168
169
\section adsi_page_sec_2d The Japanese specification from NTT
170
171
The Japanese caller ID specification is considerably different from any of the others. It
172
uses V.23 modem signals, but the message structure is uniqeue. Also, the message is delivered
173
while off hook. This results in a sequence
174
175
- The phone line rings
176
- CPE answers and waits for the caller ID message
177
- CPE hangs up on receipt of the caller ID message
178
- The phone line rings a second time
179
- The CPE answers a second time, connecting the called party with the caller.
180
181
Timeouts are, obviously, required to ensure this system behaves well when the caller ID message
182
or the second ring are missing.
183
*/
184
185
enum
186
{
187
ADSI_STANDARD_NONE = 0,
188
ADSI_STANDARD_CLASS = 1,
189
ADSI_STANDARD_CLIP = 2,
190
ADSI_STANDARD_ACLIP = 3,
191
ADSI_STANDARD_JCLIP = 4,
192
ADSI_STANDARD_CLIP_DTMF = 5,
193
ADSI_STANDARD_TDD = 6
194
};
195
196
/* In some of the messages code characters are used, as follows:
197
'C' for public callbox
198
'L' for long distance
199
'O' for overseas
200
'P' for private
201
'S' for service conflict
202
203
Taiwan and Kuwait change this pattern to:
204
'C' for coin/public callbox
205
'I' for international call
206
'O' for out of area call
207
'P' for private
208
*/
209
210
/*! Definitions for CLASS (Custom Local Area Signaling Services) */
211
enum
212
{
213
/*! Single data message caller ID */
214
CLASS_SDMF_CALLERID
= 0x04,
215
/*! Multiple data message caller ID */
216
CLASS_MDMF_CALLERID
= 0x80,
217
/*! Single data message message waiting */
218
CLASS_SDMF_MSG_WAITING
= 0x06,
219
/*! Multiple data message message waiting */
220
CLASS_MDMF_MSG_WAITING
= 0x82
221
};
222
223
/*! CLASS MDMF message IDs */
224
enum
225
{
226
/*! Date and time (MMDDHHMM) */
227
MCLASS_DATETIME
= 0x01,
228
/*! Caller number */
229
MCLASS_CALLER_NUMBER
= 0x02,
230
/*! Dialed number */
231
MCLASS_DIALED_NUMBER
= 0x03,
232
/*! Caller number absent: 'O' or 'P' */
233
MCLASS_ABSENCE1
= 0x04,
234
/*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
235
MCLASS_REDIRECT
= 0x05,
236
/*! Long distance: 'L' */
237
MCLASS_QUALIFIER
= 0x06,
238
/*! Caller's name */
239
MCLASS_CALLER_NAME
= 0x07,
240
/*! Caller's name absent: 'O' or 'P' */
241
MCLASS_ABSENCE2
= 0x08,
242
/*! Alternate route */
243
MCLASS_ALT_ROUTE
= 0x09
244
};
245
246
/*! CLASS MDMF message waiting message IDs */
247
/*! Message waiting/not waiting */
248
#define MCLASS_VISUAL_INDICATOR 0x0B
249
250
/*! Definitions for CLIP (Calling Line Identity Presentation) (from ETS 300 659-1) */
251
enum
252
{
253
/*! Multiple data message caller ID */
254
CLIP_MDMF_CALLERID
= 0x80,
255
/*! Multiple data message message waiting */
256
CLIP_MDMF_MSG_WAITING
= 0x82,
257
/*! Multiple data message charge information */
258
CLIP_MDMF_CHARGE_INFO
= 0x86,
259
/*! Multiple data message SMS */
260
CLIP_MDMF_SMS
= 0x89
261
};
262
263
/*! CLIP message IDs (from ETS 300 659-1) */
264
enum
265
{
266
/*! Date and time (MMDDHHMM) */
267
CLIP_DATETIME
= 0x01,
268
/*! Caller number (AKA calling line identity) */
269
CLIP_CALLER_NUMBER
= 0x02,
270
/*! Dialed number (AKA called line identity) */
271
CLIP_DIALED_NUMBER
= 0x03,
272
/*! Caller number absent: 'O' or 'P' (AKA reason for absence of calling line identity) */
273
CLIP_ABSENCE1
= 0x04,
274
/*! Caller's name (AKA calling party name) */
275
CLIP_CALLER_NAME
= 0x07,
276
/*! Caller's name absent: 'O' or 'P' (AKA reason for absence of calling party name) */
277
CLIP_ABSENCE2
= 0x08,
278
/*! Visual indicator */
279
CLIP_VISUAL_INDICATOR
= 0x0B,
280
/*! Message ID */
281
CLIP_MESSAGE_ID
= 0x0D,
282
/*! Complementary calling line identity */
283
CLIP_COMPLEMENTARY_CALLER_NUMBER
= 0x10,
284
/*! Call type - voice call (1), ring-back-when-free call (2), calling name delivery (3) or msg waiting call(0x81) */
285
CLIP_CALLTYPE
= 0x11,
286
/*! Number of messages */
287
CLIP_NUM_MSG
= 0x13,
288
/*! Type of forwarded call */
289
CLIP_TYPE_OF_FORWARDED_CALL
= 0x15,
290
/*! Type of calling user */
291
CLIP_TYPE_OF_CALLING_USER
= 0x16,
292
/*! Redirecting number */
293
CLIP_REDIR_NUMBER
= 0x1A,
294
/*! Charge */
295
CLIP_CHARGE
= 0x20,
296
/*! Duration of the call */
297
CLIP_DURATION
= 0x23,
298
/*! Additional charge */
299
CLIP_ADD_CHARGE
= 0x21,
300
/*! Display information */
301
CLIP_DISPLAY_INFO
= 0x50,
302
/*! Service information */
303
CLIP_SERVICE_INFO
= 0x55
304
};
305
306
/*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
307
enum
308
{
309
/*! Single data message caller ID frame */
310
ACLIP_SDMF_CALLERID
= 0x04,
311
/*! Multiple data message caller ID frame */
312
ACLIP_MDMF_CALLERID
= 0x80
313
};
314
315
/*! A-CLIP MDM message IDs */
316
enum
317
{
318
/*! Date and time (MMDDHHMM) */
319
ACLIP_DATETIME
= 0x01,
320
/*! Caller number */
321
ACLIP_CALLER_NUMBER
= 0x02,
322
/*! Dialed number */
323
ACLIP_DIALED_NUMBER
= 0x03,
324
/*! Caller number absent: 'O' or 'P' */
325
ACLIP_NUMBER_ABSENCE
= 0x04,
326
/*! Call forward: universal, on busy, or on unanswered */
327
ACLIP_REDIRECT
= 0x05,
328
/*! Long distance call: 'L' */
329
ACLIP_QUALIFIER
= 0x06,
330
/*! Caller's name */
331
ACLIP_CALLER_NAME
= 0x07,
332
/*! Caller's name absent: 'O' or 'P' */
333
ACLIP_NAME_ABSENCE
= 0x08
334
};
335
336
/*! Definitions for J-CLIP (Japan Calling Line Identity Presentation) */
337
/*! Multiple data message caller ID frame */
338
#define JCLIP_MDMF_CALLERID 0x40
339
340
/*! J-CLIP MDM message IDs */
341
enum
342
{
343
/*! Caller number */
344
JCLIP_CALLER_NUMBER
= 0x02,
345
/*! Caller number data extension signal */
346
JCLIP_CALLER_NUM_DES
= 0x21,
347
/*! Dialed number */
348
JCLIP_DIALED_NUMBER
= 0x09,
349
/*! Dialed number data extension signal */
350
JCLIP_DIALED_NUM_DES
= 0x22,
351
/*! Caller number absent: 'C', 'O', 'P' or 'S' */
352
JCLIP_ABSENCE
= 0x04
353
};
354
355
/* Definitions for CLIP-DTMF and its variants */
356
357
/*! Caller number is '#' terminated DTMF. */
358
#define CLIP_DTMF_HASH_TERMINATED '#'
359
/*! Caller number is 'C' terminated DTMF. */
360
#define CLIP_DTMF_C_TERMINATED 'C'
361
362
/*! Caller number */
363
#define CLIP_DTMF_HASH_CALLER_NUMBER 'A'
364
/*! Caller number absent: private (1), overseas (2) or not available (3) */
365
#define CLIP_DTMF_HASH_ABSENCE 'D'
366
/*! Caller ID field with no explicit field type */
367
#define CLIP_DTMF_HASH_UNSPECIFIED 0
368
369
/*! Caller number */
370
#define CLIP_DTMF_C_CALLER_NUMBER 'A'
371
/*! Diverting number */
372
#define CLIP_DTMF_C_REDIRECT_NUMBER 'D'
373
/*! Caller number absent: private/restricted (00) or not available (10) */
374
#define CLIP_DTMF_C_ABSENCE 'B'
375
376
/*!
377
ADSI transmitter descriptor. This contains all the state information for an ADSI
378
(caller ID, CLASS, CLIP, ACLIP) transmit channel.
379
*/
380
typedef
struct
adsi_tx_state_s
adsi_tx_state_t
;
381
382
/*!
383
ADSI receiver descriptor. This contains all the state information for an ADSI
384
(caller ID, CLASS, CLIP, ACLIP, JCLIP) receive channel.
385
*/
386
typedef
struct
adsi_rx_state_s
adsi_rx_state_t
;
387
388
#if defined(__cplusplus)
389
extern
"C"
390
{
391
#endif
392
393
/*! \brief Initialise an ADSI receive context.
394
\param s The ADSI receive context.
395
\param standard The code for the ADSI standard to be used.
396
\param put_msg A callback routine called to deliver the received messages
397
to the application.
398
\param user_data An opaque pointer for the callback routine.
399
\return A pointer to the initialised context, or NULL if there was a problem.
400
*/
401
SPAN_DECLARE(
adsi_rx_state_t
*)
adsi_rx_init
(
adsi_rx_state_t
*s,
402
int
standard,
403
put_msg_func_t
put_msg,
404
void
*user_data);
405
406
/*! \brief Release an ADSI receive context.
407
\param s The ADSI receive context.
408
\return 0 for OK.
409
*/
410
SPAN_DECLARE(
int
)
adsi_rx_release
(
adsi_rx_state_t
*s);
411
412
/*! \brief Free the resources of an ADSI receive context.
413
\param s The ADSI receive context.
414
\return 0 for OK.
415
*/
416
SPAN_DECLARE(
int
)
adsi_rx_free
(
adsi_rx_state_t
*s);
417
418
/*! \brief Receive a chunk of ADSI audio.
419
\param s The ADSI receive context.
420
\param amp The audio sample buffer.
421
\param len The number of samples in the buffer.
422
\return The number of samples unprocessed.
423
*/
424
SPAN_DECLARE(
int
)
adsi_rx
(
adsi_rx_state_t
*s, const int16_t amp[],
int
len);
425
426
/*! \brief Initialise an ADSI transmit context.
427
\param s The ADSI transmit context.
428
\param standard The code for the ADSI standard to be used.
429
\return A pointer to the initialised context, or NULL if there was a problem.
430
*/
431
SPAN_DECLARE(
adsi_tx_state_t
*)
adsi_tx_init
(
adsi_tx_state_t
*s,
int
standard);
432
433
/*! \brief Release an ADSI transmit context.
434
\param s The ADSI transmit context.
435
\return 0 for OK.
436
*/
437
SPAN_DECLARE(
int
)
adsi_tx_release
(
adsi_tx_state_t
*s);
438
439
/*! \brief Free the resources of an ADSI transmit context.
440
\param s The ADSI transmit context.
441
\return 0 for OK.
442
*/
443
SPAN_DECLARE(
int
)
adsi_tx_free
(
adsi_tx_state_t
*s);
444
445
/*! \brief Adjust the preamble associated with an ADSI transmit context.
446
\param s The ADSI transmit context.
447
\param preamble_len The number of bits of preamble.
448
\param preamble_ones_len The number of bits of continuous one before a message.
449
\param postamble_ones_len The number of bits of continuous one after a message.
450
\param stop_bits The number of stop bits per character.
451
*/
452
SPAN_DECLARE(
void
)
adsi_tx_set_preamble
(
adsi_tx_state_t
*s,
453
int
preamble_len,
454
int
preamble_ones_len,
455
int
postamble_ones_len,
456
int
stop_bits);
457
458
/*! \brief Generate a block of ADSI audio samples.
459
\param s The ADSI transmit context.
460
\param amp The audio sample buffer.
461
\param max_len The number of samples to be generated.
462
\return The number of samples actually generated.
463
*/
464
SPAN_DECLARE(
int
)
adsi_tx
(
adsi_tx_state_t
*s, int16_t amp[],
int
max_len);
465
466
/*! \brief Request generation of an ADSI alert tone.
467
\param s The ADSI transmit context.
468
*/
469
SPAN_DECLARE(
void
)
adsi_tx_send_alert_tone
(
adsi_tx_state_t
*s);
470
471
/*! \brief Put a message into the input buffer of an ADSI transmit context.
472
\param s The ADSI transmit context.
473
\param msg The message.
474
\param len The length of the message.
475
\return The length actually added. If a message is already in progress
476
in the transmitter, this function will return zero, as it will
477
not successfully add the message to the buffer. If the message is
478
invalid (e.g. it is too long), this function will return -1.
479
*/
480
SPAN_DECLARE(
int
)
adsi_tx_put_message
(
adsi_tx_state_t
*s, const uint8_t *msg,
int
len);
481
482
/*! \brief Get a field from an ADSI message.
483
\param s The ADSI receive context.
484
\param msg The message buffer.
485
\param msg_len The length of the message.
486
\param pos Current position within the message. Set to -1 when starting a message.
487
\param field_type The type code for the field.
488
\param field_body Pointer to the body of the field.
489
\param field_len The length of the field, or -1 for no more fields, or -2 for message structure corrupt.
490
*/
491
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);
492
493
/*! \brief Insert the header or a field into an ADSI message.
494
\param s The ADSI transmit context.
495
\param msg The message buffer.
496
\param len The current length of the message.
497
\param field_type The type code for the new field.
498
\param field_body Pointer to the body of the new field.
499
\param field_len The length of the new field.
500
*/
501
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);
502
503
/*! \brief Return a short name for an ADSI standard
504
\param standard The code for the standard.
505
\return A pointer to the name.
506
*/
507
SPAN_DECLARE(const
char
*)
adsi_standard_to_str
(
int
standard);
508
509
#if defined(__cplusplus)
510
}
511
#endif
512
513
#endif
514
/*- End of file ------------------------------------------------------------*/
src
spandsp
adsi.h
Generated by
1.8.1.2