c5e24a30a00850a8db742713396a7fbffea84d4d
[asterisk/asterisk.git] / include / asterisk / callerid.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief CallerID (and other GR30) management and generation
21  * Includes code and algorithms from the Zapata library.
22  *
23  * \ref CID
24  *
25  */
26
27 /*!
28  * \page CID Caller ID names and numbers
29  *
30  * Caller ID names are currently 8 bit characters, propably
31  * ISO8859-1, depending on what your channel drivers handle.
32  *
33  * IAX2 and SIP caller ID names are UTF8
34  * On ISDN Caller ID names are 7 bit, Almost ASCII
35  * (See http://www.zytrax.com/tech/ia5.html )
36  *
37  * \note Asterisk does not currently support SIP utf8 caller ID names or caller ID's.
38  *
39  * \par See also
40  *      \arg \ref callerid.c
41  *      \arg \ref callerid.h
42  *      \arg \ref Def_CallerPres
43  */
44
45 #ifndef _ASTERISK_CALLERID_H
46 #define _ASTERISK_CALLERID_H
47
48 #include "asterisk/frame_defs.h"
49
50 #define MAX_CALLERID_SIZE 32000
51
52 #define CID_PRIVATE_NAME                (1 << 0)
53 #define CID_PRIVATE_NUMBER              (1 << 1)
54 #define CID_UNKNOWN_NAME                (1 << 2)
55 #define CID_UNKNOWN_NUMBER              (1 << 3)
56 #define CID_MSGWAITING                  (1 << 4)
57 #define CID_NOMSGWAITING                (1 << 5)
58
59 #define CID_SIG_BELL    1
60 #define CID_SIG_V23     2
61 #define CID_SIG_DTMF    3
62 #define CID_SIG_V23_JP  4
63 #define CID_SIG_SMDI    5
64
65 #define CID_START_RING                  1
66 #define CID_START_POLARITY              2
67 #define CID_START_POLARITY_IN   3
68 #define CID_START_DTMF_NOALERT  4
69
70 /* defines dealing with message waiting indication generation */
71 /*! MWI SDMF format */
72 #define CID_MWI_TYPE_SDMF               0x00
73 /*! MWI MDMF format -- generate only MWI field */
74 #define CID_MWI_TYPE_MDMF               0x01
75 /*! MWI MDMF format -- generate name, callerid, date and MWI fields */
76 #define CID_MWI_TYPE_MDMF_FULL  0x02
77
78 #define AST_LIN2X(a) ((codec == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
79 #define AST_XLAW(a) ((codec == AST_FORMAT_ALAW) ? (AST_ALAW(a)) : (AST_MULAW(a)))
80
81
82 struct callerid_state;
83 typedef struct callerid_state CIDSTATE;
84
85 /*! \brief CallerID Initialization
86  * \par
87  * Initializes the callerid system.  Mostly stuff for inverse FFT
88  */
89 void callerid_init(void);
90
91 /*! \brief Generates a CallerID FSK stream in ulaw format suitable for transmission.
92  * \param buf Buffer to use. If "buf" is supplied, it will use that buffer instead of allocating its own.
93  *   "buf" must be at least 32000 bytes in size of you want to be sure you don't have an overrun.
94  * \param number Use NULL for no number or "P" for "private"
95  * \param name name to be used
96  * \param flags passed flags
97  * \param callwaiting callwaiting flag
98  * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW
99  * \details
100  * This function creates a stream of callerid (a callerid spill) data in ulaw format.
101  * \return It returns the size
102  * (in bytes) of the data (if it returns a size of 0, there is probably an error)
103  */
104 int callerid_generate(unsigned char *buf, const char *number, const char *name, int flags, int callwaiting, format_t codec);
105
106 /*! \brief Create a callerID state machine
107  * \param cid_signalling Type of signalling in use
108  *
109  * \details
110  * This function returns a malloc'd instance of the callerid_state data structure.
111  * \return Returns a pointer to a malloc'd callerid_state structure, or NULL on error.
112  */
113 struct callerid_state *callerid_new(int cid_signalling);
114
115 /*! \brief Read samples into the state machine.
116  * \param cid Which state machine to act upon
117  * \param ubuf containing your samples
118  * \param samples number of samples contained within the buffer.
119  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
120  *
121  * \details
122  * Send received audio to the Caller*ID demodulator.
123  * \retval -1 on error
124  * \retval 0 for "needs more samples"
125  * \retval 1 if the CallerID spill reception is complete.
126  */
127 int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, format_t codec);
128
129 /*! \brief Read samples into the state machine.
130  * \param cid Which state machine to act upon
131  * \param ubuf containing your samples
132  * \param samples number of samples contained within the buffer.
133  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
134  *
135  * \details
136  * Send received audio to the Caller*ID demodulator (for japanese style lines).
137  * \retval -1 on error
138  * \retval 0 for "needs more samples"
139  * \retval 1 if the CallerID spill reception is complete.
140  */
141 int callerid_feed_jp(struct callerid_state *cid, unsigned char *ubuf, int samples, format_t codec);
142
143 /*! \brief Extract info out of callerID state machine.  Flags are listed above
144  * \param cid Callerid state machine to act upon
145  * \param number Pass the address of a pointer-to-char (will contain the phone number)
146  * \param name Pass the address of a pointer-to-char (will contain the name)
147  * \param flags Pass the address of an int variable(will contain the various callerid flags)
148  *
149  * \details
150  * This function extracts a callerid string out of a callerid_state state machine.
151  * If no number is found, *number will be set to NULL.  Likewise for the name.
152  * Flags can contain any of the following:
153  *
154  * \return Returns nothing.
155  */
156 void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags);
157
158 /*!
159  * \brief Get and parse DTMF-based callerid
160  * \param cidstring The actual transmitted string.
161  * \param number The cid number is returned here.
162  * \param flags The cid flags are returned here.
163  */
164 void callerid_get_dtmf(char *cidstring, char *number, int *flags);
165
166 /*! \brief This function frees callerid_state cid.
167  * \param cid This is the callerid_state state machine to free
168  */
169 void callerid_free(struct callerid_state *cid);
170
171 /*! \brief Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format)
172  * \param buf buffer for output samples. See callerid_generate() for details regarding buffer.
173  * \param name Caller-ID Name
174  * \param number Caller-ID Number
175  * \param codec Asterisk codec (either AST_FORMAT_ALAW or AST_FORMAT_ULAW)
176  *
177  * \details
178  * Acts like callerid_generate except uses an asterisk format callerid string.
179  */
180 int ast_callerid_generate(unsigned char *buf, const char *name, const char *number, format_t codec);
181
182 /*!
183  * \brief Generate message waiting indicator
184  * \param active The message indicator state
185  *  -- either 0 no messages in mailbox or 1 messages in mailbox
186  * \param type Format of message (any of CID_MWI_TYPE_*)
187  * \see callerid_generate() for more info as it uses the same encoding
188  * \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
189  */
190 int ast_callerid_vmwi_generate(unsigned char *buf, int active, int type, format_t codec, const char *name,
191         const char *number, int flags);
192
193 /*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm)
194  * \see ast_callerid_generate() for other details
195  */
196 int ast_callerid_callwaiting_generate(unsigned char *buf, const char *name, const char *number, format_t codec);
197
198 /*! \brief Destructively parse inbuf into name and location (or number)
199  * \details
200  * Parses callerid stream from inbuf and changes into useable form, outputed in name and location.
201  * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed.
202  * \param name address of a pointer-to-char for the name value of the stream.
203  * \param location address of a pointer-to-char for the phone number value of the stream.
204  * \note XXX 'name' is not parsed consistently e.g. we have
205  * input                   location        name
206  * " foo bar " <123>       123             ' foo bar ' (with spaces around)
207  * " foo bar "             NULL            'foo bar' (without spaces around)
208  * The parsing of leading and trailing space/quotes should be more consistent.
209  * \return Returns 0 on success, -1 on failure.
210  */
211 int ast_callerid_parse(char *instr, char **name, char **location);
212
213 /*!
214  * \brief Generate a CAS (CPE Alert Signal) tone for 'n' samples
215  * \param outbuf Allocated buffer for data.  Must be at least 2400 bytes unless no SAS is desired
216  * \param sas Non-zero if CAS should be preceeded by SAS
217  * \param len How many samples to generate.
218  * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
219  * \return Returns -1 on error (if len is less than 2400), 0 on success.
220  */
221 int ast_gen_cas(unsigned char *outbuf, int sas, int len, format_t codec);
222
223 /*!
224  * \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s...
225  * \param n The number to be stripped/shrunk
226  * \return Returns nothing important
227  */
228 void ast_shrink_phone_number(char *n);
229
230 /*!
231  * \brief Check if a string consists only of digits and + \#
232  * \param n number to be checked.
233  * \return Returns 0 if n is a number, 1 if it's not.
234  */
235 int ast_isphonenumber(const char *n);
236
237 /*!
238  * \brief Check if a string consists only of digits and and + \# ( ) - .
239  * (meaning it can be cleaned with ast_shrink_phone_number)
240  * \param exten The extension (or URI) to be checked.
241  * \retval 1 if string is valid AST shrinkable phone number
242  * \retval 0 if not
243  */
244 int ast_is_shrinkable_phonenumber(const char *exten);
245
246 int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen);
247
248 char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown);
249
250 /*
251  * Caller*ID and other GR-30 compatible generation
252  * routines (used by ADSI for example)
253  */
254
255 extern float cid_dr[4];
256 extern float cid_di[4];
257 extern float clidsb;
258
259 static inline float callerid_getcarrier(float *cr, float *ci, int bit)
260 {
261         /* Move along.  There's nothing to see here... */
262         float t;
263         t = *cr * cid_dr[bit] - *ci * cid_di[bit];
264         *ci = *cr * cid_di[bit] + *ci * cid_dr[bit];
265         *cr = t;
266
267         t = 2.0 - (*cr * *cr + *ci * *ci);
268         *cr *= t;
269         *ci *= t;
270         return *cr;
271 }
272
273 #define PUT_BYTE(a) do { \
274         *(buf++) = (a); \
275         bytes++; \
276 } while(0)
277
278 #define PUT_AUDIO_SAMPLE(y) do { \
279         int __sample_idx = (short)(rint(8192.0 * (y))); \
280         *(buf++) = AST_LIN2X(__sample_idx); \
281         bytes++; \
282 } while(0)
283
284 #define PUT_CLID_MARKMS do { \
285         int __clid_x; \
286         for (__clid_x=0;__clid_x<8;__clid_x++) \
287                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \
288 } while(0)
289
290 #define PUT_CLID_BAUD(bit) do { \
291         while(scont < clidsb) { \
292                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \
293                 scont += 1.0; \
294         } \
295         scont -= clidsb; \
296 } while(0)
297
298
299 #define PUT_CLID(byte) do { \
300         int z; \
301         unsigned char b = (byte); \
302         PUT_CLID_BAUD(0);       /* Start bit */ \
303         for (z=0;z<8;z++) { \
304                 PUT_CLID_BAUD(b & 1); \
305                 b >>= 1; \
306         } \
307         PUT_CLID_BAUD(1);       /* Stop bit */ \
308 } while(0)
309
310 /* Various defines and bits for handling PRI- and SS7-type restriction */
311
312 #define AST_PRES_NUMBER_TYPE                                    0x03
313 #define AST_PRES_USER_NUMBER_UNSCREENED                 0x00
314 #define AST_PRES_USER_NUMBER_PASSED_SCREEN              0x01
315 #define AST_PRES_USER_NUMBER_FAILED_SCREEN              0x02
316 #define AST_PRES_NETWORK_NUMBER                                 0x03
317
318 #define AST_PRES_RESTRICTION                                    0x60
319 #define AST_PRES_ALLOWED                                                0x00
320 #define AST_PRES_RESTRICTED                                             0x20
321 #define AST_PRES_UNAVAILABLE                                    0x40
322 #define AST_PRES_RESERVED                                               0x60
323
324 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \
325         (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_UNSCREENED)
326
327 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \
328         (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_PASSED_SCREEN)
329
330 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \
331         (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_FAILED_SCREEN)
332
333 #define AST_PRES_ALLOWED_NETWORK_NUMBER \
334         (AST_PRES_ALLOWED | AST_PRES_NETWORK_NUMBER)
335
336 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \
337         (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_UNSCREENED)
338
339 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \
340         (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_PASSED_SCREEN)
341
342 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \
343         (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_FAILED_SCREEN)
344
345 #define AST_PRES_PROHIB_NETWORK_NUMBER \
346         (AST_PRES_RESTRICTED | AST_PRES_NETWORK_NUMBER)
347
348 #define AST_PRES_NUMBER_NOT_AVAILABLE \
349         (AST_PRES_UNAVAILABLE | AST_PRES_NETWORK_NUMBER)
350
351 int ast_parse_caller_presentation(const char *data);
352 const char *ast_describe_caller_presentation(int data);
353 const char *ast_named_caller_presentation(int data);
354
355 /*!
356  * \page Def_CallerPres Caller ID Presentation
357  *
358  * Caller ID presentation values are used to set properties to a
359  * caller ID in PSTN networks, and as RPID value in SIP transactions.
360  *
361  * The following values are available to use:
362  * \arg \b Defined value, text string in config file, explanation
363  *
364  * \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened,
365  * \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen,
366  * \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen,
367  * \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number,
368  * \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened,
369  * \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen,
370  * \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen,
371  * \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number,
372  *
373  * \par References
374  * \arg \ref callerid.h Definitions
375  * \arg \ref callerid.c Functions
376  * \arg \ref CID Caller ID names and numbers
377  */
378
379 /*!
380  * \brief redirecting reason codes.
381  *
382  * This list attempts to encompass redirecting reasons
383  * as defined by several channel technologies.
384  */
385 enum AST_REDIRECTING_REASON {
386         AST_REDIRECTING_REASON_UNKNOWN,
387         AST_REDIRECTING_REASON_USER_BUSY,
388         AST_REDIRECTING_REASON_NO_ANSWER,
389         AST_REDIRECTING_REASON_UNAVAILABLE,
390         AST_REDIRECTING_REASON_UNCONDITIONAL,
391         AST_REDIRECTING_REASON_TIME_OF_DAY,
392         AST_REDIRECTING_REASON_DO_NOT_DISTURB,
393         AST_REDIRECTING_REASON_DEFLECTION,
394         AST_REDIRECTING_REASON_FOLLOW_ME,
395         AST_REDIRECTING_REASON_OUT_OF_ORDER,
396         AST_REDIRECTING_REASON_AWAY,
397         AST_REDIRECTING_REASON_CALL_FWD_DTE,           /* This is something defined in Q.931, and no I don't know what it means */
398 };
399
400 /*!
401  * \since 1.6.3
402  * \brief Convert redirecting reason text code to value (used in config file parsing)
403  *
404  * \param data text string from config file
405  *
406  * \retval Q931_REDIRECTING_REASON from callerid.h
407  * \retval -1 if not in table
408  */
409 int ast_redirecting_reason_parse(const char *data);
410
411 /*!
412  * \since 1.6.3
413  * \brief Convert redirecting reason value to explanatory string
414  *
415  * \param data Q931_REDIRECTING_REASON from callerid.h
416  *
417  * \return string for human presentation
418  */
419 const char *ast_redirecting_reason_describe(int data);
420
421 /*!
422  * \since 1.6.3
423  * \brief Convert redirecting reason value to text code
424  *
425  * \param data Q931_REDIRECTING_REASON from callerid.h
426  *
427  * \return string for config file
428  */
429 const char *ast_redirecting_reason_name(int data);
430
431 /*!
432  * \brief Connected line update source code
433  */
434 enum AST_CONNECTED_LINE_UPDATE_SOURCE {
435         /*! Update for unknown reason (May be interpreted to mean from answer) */
436         AST_CONNECTED_LINE_UPDATE_SOURCE_UNKNOWN,
437         /*! Update from normal call answering */
438         AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER,
439         /*! Update from call diversion (Deprecated, use REDIRECTING updates instead.) */
440         AST_CONNECTED_LINE_UPDATE_SOURCE_DIVERSION,
441         /*! Update from call transfer(active) (Party has already answered) */
442         AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER,
443         /*! Update from call transfer(alerting) (Party has not answered yet) */
444         AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER_ALERTING
445 };
446
447 /*!
448  * \since 1.6.3
449  * \brief Convert connected line update source text code to value (used in config file parsing)
450  *
451  * \param data text string from config file
452  *
453  * \retval AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
454  * \retval -1 if not in table
455  */
456 int ast_connected_line_source_parse(const char *data);
457
458 /*!
459  * \since 1.6.3
460  * \brief Convert connected line update source value to explanatory string
461  *
462  * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
463  *
464  * \return string for human presentation
465  */
466 const char *ast_connected_line_source_describe(int data);
467
468 /*!
469  * \since 1.6.3
470  * \brief Convert connected line update source value to text code
471  *
472  * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
473  *
474  * \return string for config file
475  */
476 const char *ast_connected_line_source_name(int data);
477
478
479 #endif /* _ASTERISK_CALLERID_H */