Add new callerpres parsing API (bug #3648)
[asterisk/asterisk.git] / include / asterisk / callerid.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * CallerID (and other GR30) Generation support 
5  * 
6  * Copyright (C) 1999 - 2005, Digium, Inc.
7  *
8  * Mark Spencer <markster@digium.com>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU General Public License.
12  *
13  * Includes code and algorithms from the Zapata library.
14  *
15  */
16
17 #ifndef _CALLERID_H
18 #define _CALLERID_H
19
20 #define MAX_CALLERID_SIZE 32000
21
22 #define CID_PRIVATE_NAME                (1 << 0)
23 #define CID_PRIVATE_NUMBER              (1 << 1)
24 #define CID_UNKNOWN_NAME                (1 << 2)
25 #define CID_UNKNOWN_NUMBER              (1 << 3)
26
27 #define CID_SIG_BELL    1
28 #define CID_SIG_V23     2
29 #define CID_SIG_DTMF    3
30
31 #define CID_START_RING  1
32 #define CID_START_POLARITY 2
33
34
35 #define AST_LIN2X(a) ((codec == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
36 #define AST_XLAW(a) ((codec == AST_FORMAT_ALAW) ? (AST_ALAW(a)) : (AST_MULAW(a)))
37
38
39 struct callerid_state;
40 typedef struct callerid_state CIDSTATE;
41
42 /*! CallerID Initialization */
43 /*!
44  * Initializes the callerid system.  Mostly stuff for inverse FFT
45  */
46 extern void callerid_init(void);
47
48 /*! Generates a CallerID FSK stream in ulaw format suitable for transmission. */
49 /*!
50  * \param buf Buffer to use. If "buf" is supplied, it will use that buffer instead of allocating its own.  "buf" must be at least 32000 bytes in size of you want to be sure you don't have an overrun.
51  * \param number Use NULL for no number or "P" for "private"
52  * \param name name to be used
53  * \param callwaiting callwaiting flag
54  * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW
55  * This function creates a stream of callerid (a callerid spill) data in ulaw format. It returns the size
56  * (in bytes) of the data (if it returns a size of 0, there is probably an error)
57 */
58 extern int callerid_generate(unsigned char *buf, char *number, char *name, int flags, int callwaiting, int codec);
59
60 /*! Create a callerID state machine */
61 /*!
62  * \param cid_signalling Type of signalling in use
63  *
64  * This function returns a malloc'd instance of the callerid_state data structure.
65  * Returns a pointer to a malloc'd callerid_state structure, or NULL on error.
66  */
67 extern struct callerid_state *callerid_new(int cid_signalling);
68
69 /*! Read samples into the state machine. */
70 /*!
71  * \param cid Which state machine to act upon
72  * \param buffer containing your samples
73  * \param samples number of samples contained within the buffer.
74  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
75  *
76  * Send received audio to the Caller*ID demodulator.
77  * Returns -1 on error, 0 for "needs more samples", 
78  * and 1 if the CallerID spill reception is complete.
79  */
80 extern int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
81
82 /*! Extract info out of callerID state machine.  Flags are listed above */
83 /*!
84  * \param cid Callerid state machine to act upon
85  * \param number Pass the address of a pointer-to-char (will contain the phone number)
86  * \param name Pass the address of a pointer-to-char (will contain the name)
87  * \param flags Pass the address of an int variable(will contain the various callerid flags)
88  *
89  * This function extracts a callerid string out of a callerid_state state machine.
90  * If no number is found, *number will be set to NULL.  Likewise for the name.
91  * Flags can contain any of the following:
92  * 
93  * Returns nothing.
94  */
95 void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags);
96
97 /*! Get and parse DTMF-based callerid  */
98 /*!
99  * \param cidstring The actual transmitted string.
100  * \param number The cid number is returned here.
101  * \param flags The cid flags are returned here.
102  * This function parses DTMF callerid.
103  */
104 void callerid_get_dtmf(char *cidstring, char *number, int *flags);
105
106 /*! Free a callerID state */
107 /*!
108  * \param cid This is the callerid_state state machine to free
109  * This function frees callerid_state cid.
110  */
111 extern void callerid_free(struct callerid_state *cid);
112
113 /*! Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format) */
114 /*!
115  * \param buf buffer for output samples. See callerid_generate() for details regarding buffer.
116  * \param astcid Asterisk format callerid string, taken from the callerid field of asterisk.
117  * \param codec Asterisk codec (either AST_FORMAT_ALAW or AST_FORMAT_ULAW)
118  *
119  * Acts like callerid_generate except uses an asterisk format callerid string.
120  */
121 extern int ast_callerid_generate(unsigned char *buf, char *name, char *number, int codec);
122
123 /*! Generate message waiting indicator  */
124 extern int vmwi_generate(unsigned char *buf, int active, int mdmf, int codec);
125
126 /*! Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm) */
127 /*!
128  * See ast_callerid_generate for other details
129  */
130 extern int ast_callerid_callwaiting_generate(unsigned char *buf, char *name, char *number, int codec);
131
132 /*! Destructively parse inbuf into name and location (or number) */
133 /*!
134  * \param inbuf buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed.
135  * \param name address of a pointer-to-char for the name value of the stream.
136  * \param location address of a pointer-to-char for the phone number value of the stream.
137  * Parses callerid stream from inbuf and changes into useable form, outputed in name and location.
138  * Returns 0 on success, -1 on failure.
139  */
140 extern int ast_callerid_parse(char *instr, char **name, char **location);
141
142 /*! Generate a CAS (CPE Alert Signal) tone for 'n' samples */
143 /*!
144  * \param outbuf Allocated buffer for data.  Must be at least 2400 bytes unless no SAS is desired
145  * \param sas Non-zero if CAS should be preceeded by SAS
146  * \param len How many samples to generate.
147  * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
148  * Returns -1 on error (if len is less than 2400), 0 on success.
149  */
150 extern int ast_gen_cas(unsigned char *outbuf, int sas, int len, int codec);
151
152 /*! Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... */
153 /*!
154  * \param n The number to be stripped/shrunk
155  * Returns nothing important
156  */
157 extern void ast_shrink_phone_number(char *n);
158
159 /*! Check if a string consists only of digits.  Returns non-zero if so */
160 /*!
161  * \param n number to be checked.
162  * Returns 0 if n is a number, 1 if it's not.
163  */
164 extern int ast_isphonenumber(char *n);
165
166 extern int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen);
167
168 extern char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown);
169
170 /*
171  * Caller*ID and other GR-30 compatible generation
172  * routines (used by ADSI for example)
173  */
174
175 extern float cid_dr[4];
176 extern float cid_di[4];
177 extern float clidsb;
178
179 static inline float callerid_getcarrier(float *cr, float *ci, int bit)
180 {
181         /* Move along.  There's nothing to see here... */
182         float t;
183         t = *cr * cid_dr[bit] - *ci * cid_di[bit];
184         *ci = *cr * cid_di[bit] + *ci * cid_dr[bit];
185         *cr = t;
186         
187         t = 2.0 - (*cr * *cr + *ci * *ci);
188         *cr *= t;
189         *ci *= t;
190         return *cr;
191 }       
192
193 #define PUT_BYTE(a) do { \
194         *(buf++) = (a); \
195         bytes++; \
196 } while(0)
197
198 #define PUT_AUDIO_SAMPLE(y) do { \
199         int index = (short)(rint(8192.0 * (y))); \
200         *(buf++) = AST_LIN2X(index); \
201         bytes++; \
202 } while(0)
203         
204 #define PUT_CLID_MARKMS do { \
205         int x; \
206         for (x=0;x<8;x++) \
207                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \
208 } while(0)
209
210 #define PUT_CLID_BAUD(bit) do { \
211         while(scont < clidsb) { \
212                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \
213                 scont += 1.0; \
214         } \
215         scont -= clidsb; \
216 } while(0)
217
218
219 #define PUT_CLID(byte) do { \
220         int z; \
221         unsigned char b = (byte); \
222         PUT_CLID_BAUD(0);       /* Start bit */ \
223         for (z=0;z<8;z++) { \
224                 PUT_CLID_BAUD(b & 1); \
225                 b >>= 1; \
226         } \
227         PUT_CLID_BAUD(1);       /* Stop bit */ \
228 } while(0);     
229
230 /* Various defines and bits for handling PRI- and SS7-type restriction */
231
232 #define AST_PRES_NUMBER_TYPE                            0x03
233 #define AST_PRES_USER_NUMBER_UNSCREENED                 0x00
234 #define AST_PRES_USER_NUMBER_PASSED_SCREEN              0x01
235 #define AST_PRES_USER_NUMBER_FAILED_SCREEN              0x02
236 #define AST_PRES_NETWORK_NUMBER                         0x03
237
238 #define AST_PRES_RESTRICTION                            0x60
239 #define AST_PRES_ALLOWED                                0x00
240 #define AST_PRES_RESTRICTED                             0x20
241 #define AST_PRES_UNAVAILABLE                            0x40
242 #define AST_PRES_RESERVED                               0x60
243
244 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \
245         AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_ALLOWED
246
247 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \
248         AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_ALLOWED
249
250 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \
251         AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_ALLOWED
252
253 #define AST_PRES_ALLOWED_NETWORK_NUMBER \
254         AST_PRES_NETWORK_NUMBER + AST_PRES_ALLOWED
255
256 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \
257         AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_RESTRICTED
258
259 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \
260         AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_RESTRICTED
261
262 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \
263         AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_RESTRICTED
264
265 #define AST_PRES_PROHIB_NETWORK_NUMBER \
266         AST_PRES_NETWORK_NUMBER + AST_PRES_RESTRICTED
267
268 #define AST_PRES_NUMBER_NOT_AVAILABLE \
269         AST_PRES_NETWORK_NUMBER + AST_PRES_UNAVAILABLE
270
271 int ast_parse_caller_presentation(const char *data);
272 const char *ast_describe_caller_presentation(int data);
273
274 #endif