This file is indexed.

/usr/include/spandsp/adsi.h is in libspandsp-dev 0.0.6+dfsg-0.1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
/*
 * 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 Lesser General Public License version 2.1,
 * 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 Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

/*! \file */

#if !defined(_SPANDSP_ADSI_H_)
#define _SPANDSP_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:

    - Bellcore/Telcordia GR-30 CORE CLASS (Custom Local Area Signaling Services) standard
      (North America, Australia, China, Taiwan, and Hong Kong).

    - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) FSK standard
      (France, Germany, Norway, Italy, Spain, South Africa, Turkey, and the UK).

    - ETSI Caller-ID support for the UK, British Telecom SIN227 and SIN242.

    - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
      variant 1 (Belgium, Brazil, Denmark, Finland, Iceland, India, Netherlands, Saudi Arabia,
      Sweden and Uruguay).
    
    - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
      variant 2 (Denmark and Holland).
    
    - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
      variant 3.
    
    - ETSI ETS 300 648, ETS 300 659-1 CLIP (Calling Line Identity Presentation) DTMF standard
      variant 4. (Taiwan and Kuwait).
    
    - ETSI Caller-ID support in UK (British Telecom), British Telecomm SIN227, SIN242.

    - Nippon Telegraph & Telephone Corporation JCLIP (Japanese Calling Line Identity
      Presentation) standard.

    - Telecommunications Authority of Singapore ACLIP (Analog Calling Line Identity
      Presentation) standard.

    - 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 commonest 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.

Other messages support message waiting, for voice mail, and other display features. 

\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.

The wake up indication generally differs from the Bellcore specification, to
accomodate differences in European ring cadences.

\section adsi_page_sec_2c 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 a string of DTMF digits. Around the world several variants of this
basic scheme are used.

One variant of the digit string is used in Belgium, Brazil, Denmark, Finland, Iceland,
India, Netherlands, Saudi Arabia, Sweden and Uruguay:

    - A<caller's phone number>D<redirected number>B<special information>C

Each of these fields may be omitted. The following special information codes are defined

    - "00" indicates the calling party number is not available.
    - "10" indicates that the presentation of the calling party number is restricted.

A second variant of the digit string is one of the following:

    - A<caller's 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.

A third variant of the digit string is used in Taiwan and Kuwait:

    - D<caller's phone number>C

A forth variant of the digit string is used in Denmark and Holland:

    - <caller's phone number>#

There is no distinctive start marker in this format.

\section adsi_page_sec_2d The Japanese specification from NTT

The Japanese caller ID specification is considerably different from any of the others. It
uses V.23 modem signals, but the message structure is uniqeue. Also, the message is delivered
while off hook. This results in a sequence

    - The phone line rings
    - CPE answers and waits for the caller ID message
    - CPE hangs up on receipt of the caller ID message
    - The phone line rings a second time
    - The CPE answers a second time, connecting the called party with the caller.
    
Timeouts are, obviously, required to ensure this system behaves well when the caller ID message
or the second ring are missing.
*/

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

    Taiwan and Kuwait change this pattern to:
        'C' for coin/public callbox
        'I' for international call
        'O' for out of area call
        'P' for private
 */

/*! Definitions for CLASS (Custom Local Area Signaling Services) */
enum
{
    /*! Single data message caller ID */
    CLASS_SDMF_CALLERID =               0x04,
    /*! Multiple data message caller ID */
    CLASS_MDMF_CALLERID =               0x80,
    /*! Single data message message waiting */
    CLASS_SDMF_MSG_WAITING =            0x06,
    /*! Multiple data message message waiting */
    CLASS_MDMF_MSG_WAITING =            0x82
};

/*! CLASS MDMF message IDs */
enum
{
    /*! Date and time (MMDDHHMM) */
    MCLASS_DATETIME =                   0x01,
    /*! Caller number */
    MCLASS_CALLER_NUMBER =              0x02,
    /*! Dialed number */
    MCLASS_DIALED_NUMBER =              0x03,
    /*! Caller number absent: 'O' or 'P' */
    MCLASS_ABSENCE1 =                   0x04,
    /*! Call forward: universal ('0'), on busy ('1'), or on unanswered ('2') */
    MCLASS_REDIRECT =                   0x05,
    /*! Long distance: 'L' */
    MCLASS_QUALIFIER =                  0x06,
    /*! Caller's name */
    MCLASS_CALLER_NAME =                0x07,
    /*! Caller's name absent: 'O' or 'P' */
    MCLASS_ABSENCE2 =                   0x08,
    /*! Alternate route */
    MCLASS_ALT_ROUTE =                  0x09
};

/*! CLASS MDMF message waiting message IDs */
/*! Message waiting/not waiting */
#define MCLASS_VISUAL_INDICATOR         0x0B

/*! Definitions for CLIP (Calling Line Identity Presentation) (from ETS 300 659-1) */
enum
{
    /*! Multiple data message caller ID */
    CLIP_MDMF_CALLERID =                0x80,
    /*! Multiple data message message waiting */
    CLIP_MDMF_MSG_WAITING =             0x82,
    /*! Multiple data message charge information */
    CLIP_MDMF_CHARGE_INFO =             0x86,
    /*! Multiple data message SMS */
    CLIP_MDMF_SMS =                     0x89
};

/*! CLIP message IDs (from ETS 300 659-1) */
enum
{
    /*! Date and time (MMDDHHMM) */
    CLIP_DATETIME =                     0x01,
    /*! Caller number (AKA calling line identity) */
    CLIP_CALLER_NUMBER =                0x02,
    /*! Dialed number (AKA called line identity) */
    CLIP_DIALED_NUMBER =                0x03,
    /*! Caller number absent: 'O' or 'P' (AKA reason for absence of calling line identity) */
    CLIP_ABSENCE1 =                     0x04,
    /*! Caller's name (AKA calling party name) */
    CLIP_CALLER_NAME =                  0x07,
    /*! Caller's name absent: 'O' or 'P' (AKA reason for absence of calling party name) */
    CLIP_ABSENCE2 =                     0x08,
    /*! Visual indicator */
    CLIP_VISUAL_INDICATOR =             0x0B,
    /*! Message ID */
    CLIP_MESSAGE_ID =                   0x0D,
    /*! Complementary calling line identity */
    CLIP_COMPLEMENTARY_CALLER_NUMBER =  0x10,
    /*! Call type - voice call (1), ring-back-when-free call (2), calling name delivery (3) or msg waiting call(0x81) */
    CLIP_CALLTYPE =                     0x11,
    /*! Number of messages */
    CLIP_NUM_MSG =                      0x13,
    /*! Type of forwarded call */
    CLIP_TYPE_OF_FORWARDED_CALL =       0x15,
    /*! Type of calling user */
    CLIP_TYPE_OF_CALLING_USER =         0x16,
    /*! Redirecting number */
    CLIP_REDIR_NUMBER =                 0x1A,
    /*! Charge */
    CLIP_CHARGE =                       0x20,
    /*! Duration of the call */
    CLIP_DURATION =                     0x23,
    /*! Additional charge */
    CLIP_ADD_CHARGE =                   0x21,
    /*! Display information */
    CLIP_DISPLAY_INFO =                 0x50,
    /*! Service information */
    CLIP_SERVICE_INFO =                 0x55
};

/*! Definitions for A-CLIP (Analog Calling Line Identity Presentation) */
enum
{
    /*! Single data message caller ID frame */
    ACLIP_SDMF_CALLERID =               0x04,
    /*! Multiple data message caller ID frame */
    ACLIP_MDMF_CALLERID =               0x80
};

/*! A-CLIP MDM message IDs */
enum
{
    /*! Date and time (MMDDHHMM) */
    ACLIP_DATETIME =                    0x01,
    /*! Caller number */
    ACLIP_CALLER_NUMBER =               0x02,
    /*! Dialed number */
    ACLIP_DIALED_NUMBER =               0x03,
    /*! Caller number absent: 'O' or 'P' */
    ACLIP_NUMBER_ABSENCE =              0x04,
    /*! Call forward: universal, on busy, or on unanswered */
    ACLIP_REDIRECT =                    0x05,
    /*! Long distance call: 'L' */
    ACLIP_QUALIFIER =                   0x06,
    /*! Caller's name */
    ACLIP_CALLER_NAME =                 0x07,
    /*! Caller's name absent: 'O' or 'P' */
    ACLIP_NAME_ABSENCE =                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 */
enum
{
    /*! Caller number */
    JCLIP_CALLER_NUMBER =               0x02,
    /*! Caller number data extension signal */
    JCLIP_CALLER_NUM_DES =              0x21,
    /*! Dialed number */
    JCLIP_DIALED_NUMBER =               0x09,
    /*! Dialed number data extension signal */
    JCLIP_DIALED_NUM_DES =              0x22,
    /*! Caller number absent: 'C', 'O', 'P' or 'S' */
    JCLIP_ABSENCE =                     0x04
};

/* Definitions for CLIP-DTMF and its variants */

/*! Caller number is '#' terminated DTMF. */
#define CLIP_DTMF_HASH_TERMINATED       '#'
/*! Caller number is 'C' terminated DTMF. */
#define CLIP_DTMF_C_TERMINATED          'C'

/*! Caller number */
#define CLIP_DTMF_HASH_CALLER_NUMBER    'A'
/*! Caller number absent: private (1), overseas (2) or not available (3) */
#define CLIP_DTMF_HASH_ABSENCE          'D'
/*! Caller ID field with no explicit field type */
#define CLIP_DTMF_HASH_UNSPECIFIED      0

/*! Caller number */
#define CLIP_DTMF_C_CALLER_NUMBER       'A'
/*! Diverting number */
#define CLIP_DTMF_C_REDIRECT_NUMBER     'D'
/*! Caller number absent: private/restricted (00) or not available (10) */
#define CLIP_DTMF_C_ABSENCE             'B'

/*!
    ADSI transmitter descriptor. This contains all the state information for an ADSI
    (caller ID, CLASS, CLIP, ACLIP) transmit channel.
 */
typedef struct adsi_tx_state_s adsi_tx_state_t;

/*!
    ADSI receiver descriptor. This contains all the state information for an ADSI
    (caller ID, CLASS, CLIP, ACLIP, JCLIP) receive channel.
 */
typedef struct adsi_rx_state_s adsi_rx_state_t;

#if defined(__cplusplus)
extern "C"
{
#endif

/*! Get the logging context associated with an ADSI receive context.
    \brief Get the logging context associated with an ADSI receive context.
    \param s The ADSI receive context.
    \return A pointer to the logging context */
SPAN_DECLARE(logging_state_t *) adsi_rx_get_logging_state(adsi_rx_state_t *s);

/*! \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.
    \return A pointer to the initialised context, or NULL if there was a problem.
*/
SPAN_DECLARE(adsi_rx_state_t *) adsi_rx_init(adsi_rx_state_t *s,
                                             int standard,
                                             put_msg_func_t put_msg,
                                             void *user_data);

/*! \brief Release an ADSI receive context.
    \param s The ADSI receive context.
    \return 0 for OK.
*/
SPAN_DECLARE(int) adsi_rx_release(adsi_rx_state_t *s);

/*! \brief Free the resources of an ADSI receive context.
    \param s The ADSI receive context.
    \return 0 for OK.
*/
SPAN_DECLARE(int) adsi_rx_free(adsi_rx_state_t *s);

/*! \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.
    \return The number of samples unprocessed.
*/
SPAN_DECLARE(int) 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.
    \return A pointer to the initialised context, or NULL if there was a problem.
*/
SPAN_DECLARE(adsi_tx_state_t *) adsi_tx_init(adsi_tx_state_t *s, int standard);

/*! \brief Release an ADSI transmit context.
    \param s The ADSI transmit context.
    \return 0 for OK.
*/
SPAN_DECLARE(int) adsi_tx_release(adsi_tx_state_t *s);

/*! \brief Free the resources of an ADSI transmit context.
    \param s The ADSI transmit context.
    \return 0 for OK.
*/
SPAN_DECLARE(int) adsi_tx_free(adsi_tx_state_t *s);

/*! \brief Adjust the preamble associated with an ADSI transmit context.
    \param s The ADSI transmit context.
    \param preamble_len The number of bits of preamble.
    \param preamble_ones_len The number of bits of continuous one before a message.
    \param postamble_ones_len The number of bits of continuous one after a message.
    \param stop_bits The number of stop bits per character.
*/
SPAN_DECLARE(void) adsi_tx_set_preamble(adsi_tx_state_t *s,
                                        int preamble_len,
                                        int preamble_ones_len,
                                        int postamble_ones_len,
                                        int stop_bits);

/*! \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.
*/
SPAN_DECLARE(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.
*/
SPAN_DECLARE(void) adsi_tx_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. If the message is
            invalid (e.g. it is too long), this function will return -1.
*/
SPAN_DECLARE(int) adsi_tx_put_message(adsi_tx_state_t *s, const 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.
*/
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);

/*! \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.
*/
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);

/*! \brief Return a short name for an ADSI standard
    \param standard The code for the standard.
    \return A pointer to the name.
*/
SPAN_DECLARE(const char *) adsi_standard_to_str(int standard);

#if defined(__cplusplus)
}
#endif

#endif
/*- End of file ------------------------------------------------------------*/