Allow for redirecting reasons to be set to arbitrary strings.
[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/format.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->id == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
79 #define AST_XLAW(a) ((codec->id == 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, struct ast_format *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, struct ast_format *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, struct ast_format *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, struct ast_format *codec);
181
182 /*!
183  * \brief Generate message waiting indicator
184  * \param buf
185  * \param active The message indicator state
186  *  -- either 0 no messages in mailbox or 1 messages in mailbox
187  * \param type Format of message (any of CID_MWI_TYPE_*)
188  * \param codec
189  * \param name
190  * \param number
191  * \param flags
192  * \see callerid_generate() for more info as it uses the same encoding
193  * \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
194  */
195 int ast_callerid_vmwi_generate(unsigned char *buf, int active, int type, struct ast_format *codec, const char *name,
196         const char *number, int flags);
197
198 /*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm)
199  * \see ast_callerid_generate() for other details
200  */
201 int ast_callerid_callwaiting_generate(unsigned char *buf, const char *name, const char *number, struct ast_format *codec);
202
203 /*! \brief Destructively parse inbuf into name and location (or number)
204  * \details
205  * Parses callerid stream from inbuf and changes into useable form, outputed in name and location.
206  * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed.
207  * \param name address of a pointer-to-char for the name value of the stream.
208  * \param location address of a pointer-to-char for the phone number value of the stream.
209  * \note XXX 'name' is not parsed consistently e.g. we have
210  * input                   location        name
211  * " foo bar " <123>       123             ' foo bar ' (with spaces around)
212  * " foo bar "             NULL            'foo bar' (without spaces around)
213  * The parsing of leading and trailing space/quotes should be more consistent.
214  * \return Returns 0 on success, -1 on failure.
215  */
216 int ast_callerid_parse(char *instr, char **name, char **location);
217
218 /*!
219  * \brief Generate a CAS (CPE Alert Signal) tone for 'n' samples
220  * \param outbuf Allocated buffer for data.  Must be at least 2400 bytes unless no SAS is desired
221  * \param sas Non-zero if CAS should be preceeded by SAS
222  * \param len How many samples to generate.
223  * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
224  * \return Returns -1 on error (if len is less than 2400), 0 on success.
225  */
226 int ast_gen_cas(unsigned char *outbuf, int sas, int len, struct ast_format *codec);
227
228 /*!
229  * \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s...
230  * \param n The number to be stripped/shrunk
231  * \return Returns nothing important
232  */
233 void ast_shrink_phone_number(char *n);
234
235 /*!
236  * \brief Check if a string consists only of digits and + \#
237  * \param n number to be checked.
238  * \return Returns 0 if n is a number, 1 if it's not.
239  */
240 int ast_isphonenumber(const char *n);
241
242 /*!
243  * \brief Check if a string consists only of digits and and + \# ( ) - .
244  * (meaning it can be cleaned with ast_shrink_phone_number)
245  * \param exten The extension (or URI) to be checked.
246  * \retval 1 if string is valid AST shrinkable phone number
247  * \retval 0 if not
248  */
249 int ast_is_shrinkable_phonenumber(const char *exten);
250
251 int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen);
252
253 char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown);
254
255 /*
256  * Caller*ID and other GR-30 compatible generation
257  * routines (used by ADSI for example)
258  */
259
260 extern float cid_dr[4];
261 extern float cid_di[4];
262 extern float clidsb;
263
264 static inline float callerid_getcarrier(float *cr, float *ci, int bit)
265 {
266         /* Move along.  There's nothing to see here... */
267         float t;
268         t = *cr * cid_dr[bit] - *ci * cid_di[bit];
269         *ci = *cr * cid_di[bit] + *ci * cid_dr[bit];
270         *cr = t;
271
272         t = 2.0 - (*cr * *cr + *ci * *ci);
273         *cr *= t;
274         *ci *= t;
275         return *cr;
276 }
277
278 #define PUT_BYTE(a) do { \
279         *(buf++) = (a); \
280         bytes++; \
281 } while(0)
282
283 #define PUT_AUDIO_SAMPLE(y) do { \
284         int __sample_idx = (short)(rint(8192.0 * (y))); \
285         *(buf++) = AST_LIN2X(__sample_idx); \
286         bytes++; \
287 } while(0)
288
289 #define PUT_CLID_MARKMS do { \
290         int __clid_x; \
291         for (__clid_x=0;__clid_x<8;__clid_x++) \
292                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \
293 } while(0)
294
295 #define PUT_CLID_BAUD(bit) do { \
296         while(scont < clidsb) { \
297                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \
298                 scont += 1.0; \
299         } \
300         scont -= clidsb; \
301 } while(0)
302
303
304 #define PUT_CLID(byte) do { \
305         int z; \
306         unsigned char b = (byte); \
307         PUT_CLID_BAUD(0);       /* Start bit */ \
308         for (z=0;z<8;z++) { \
309                 PUT_CLID_BAUD(b & 1); \
310                 b >>= 1; \
311         } \
312         PUT_CLID_BAUD(1);       /* Stop bit */ \
313 } while(0)
314
315 /* Various defines and bits for handling PRI- and SS7-type restriction */
316
317 #define AST_PRES_NUMBER_TYPE                                    0x03
318 #define AST_PRES_USER_NUMBER_UNSCREENED                 0x00
319 #define AST_PRES_USER_NUMBER_PASSED_SCREEN              0x01
320 #define AST_PRES_USER_NUMBER_FAILED_SCREEN              0x02
321 #define AST_PRES_NETWORK_NUMBER                                 0x03
322
323 #define AST_PRES_RESTRICTION                                    0x60
324 #define AST_PRES_ALLOWED                                                0x00
325 #define AST_PRES_RESTRICTED                                             0x20
326 #define AST_PRES_UNAVAILABLE                                    0x40
327 #define AST_PRES_RESERVED                                               0x60
328
329 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \
330         (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_UNSCREENED)
331
332 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \
333         (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_PASSED_SCREEN)
334
335 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \
336         (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_FAILED_SCREEN)
337
338 #define AST_PRES_ALLOWED_NETWORK_NUMBER \
339         (AST_PRES_ALLOWED | AST_PRES_NETWORK_NUMBER)
340
341 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \
342         (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_UNSCREENED)
343
344 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \
345         (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_PASSED_SCREEN)
346
347 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \
348         (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_FAILED_SCREEN)
349
350 #define AST_PRES_PROHIB_NETWORK_NUMBER \
351         (AST_PRES_RESTRICTED | AST_PRES_NETWORK_NUMBER)
352
353 #define AST_PRES_NUMBER_NOT_AVAILABLE \
354         (AST_PRES_UNAVAILABLE | AST_PRES_NETWORK_NUMBER)
355
356 int ast_parse_caller_presentation(const char *data);
357 const char *ast_describe_caller_presentation(int data);
358 const char *ast_named_caller_presentation(int data);
359
360 /*!
361  * \page Def_CallerPres Caller ID Presentation
362  *
363  * Caller ID presentation values are used to set properties to a
364  * caller ID in PSTN networks, and as RPID value in SIP transactions.
365  *
366  * The following values are available to use:
367  * \arg \b Defined value, text string in config file, explanation
368  *
369  * \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened,
370  * \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen,
371  * \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen,
372  * \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number,
373  * \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened,
374  * \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen,
375  * \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen,
376  * \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number,
377  *
378  * \par References
379  * \arg \ref callerid.h Definitions
380  * \arg \ref callerid.c Functions
381  * \arg \ref CID Caller ID names and numbers
382  */
383
384 /*!
385  * \brief redirecting reason codes.
386  *
387  * This list attempts to encompass redirecting reasons
388  * as defined by several channel technologies.
389  */
390 enum AST_REDIRECTING_REASON {
391         AST_REDIRECTING_REASON_UNKNOWN,
392         AST_REDIRECTING_REASON_USER_BUSY,
393         AST_REDIRECTING_REASON_NO_ANSWER,
394         AST_REDIRECTING_REASON_UNAVAILABLE,
395         AST_REDIRECTING_REASON_UNCONDITIONAL,
396         AST_REDIRECTING_REASON_TIME_OF_DAY,
397         AST_REDIRECTING_REASON_DO_NOT_DISTURB,
398         AST_REDIRECTING_REASON_DEFLECTION,
399         AST_REDIRECTING_REASON_FOLLOW_ME,
400         AST_REDIRECTING_REASON_OUT_OF_ORDER,
401         AST_REDIRECTING_REASON_AWAY,
402         AST_REDIRECTING_REASON_CALL_FWD_DTE,           /* This is something defined in Q.931, and no I don't know what it means */
403         AST_REDIRECTING_REASON_SEND_TO_VM,
404 };
405
406 /*!
407  * \since 1.8
408  * \brief Convert redirecting reason text code to value (used in config file parsing)
409  *
410  * \param data text string from config file
411  *
412  * \retval Q931_REDIRECTING_REASON from callerid.h
413  * \retval -1 if not in table
414  */
415 int ast_redirecting_reason_parse(const char *data);
416
417 /*!
418  * \since 1.8
419  * \brief Convert redirecting reason value to explanatory string
420  *
421  * \param data Q931_REDIRECTING_REASON from callerid.h
422  *
423  * \return string for human presentation
424  */
425 const char *ast_redirecting_reason_describe(int data);
426
427 struct ast_party_redirecting_reason;
428
429 /*!
430  * \since 1.8
431  * \brief Convert redirecting reason value to text code
432  *
433  * \param data ast_party_redirecting_reason structure from channel.h
434  *
435  * \return string for config file
436  */
437 const char *ast_redirecting_reason_name(const struct ast_party_redirecting_reason *data);
438
439 /*!
440  * \brief Connected line update source code
441  */
442 enum AST_CONNECTED_LINE_UPDATE_SOURCE {
443         /*! Update for unknown reason (May be interpreted to mean from answer) */
444         AST_CONNECTED_LINE_UPDATE_SOURCE_UNKNOWN,
445         /*! Update from normal call answering */
446         AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER,
447         /*! Update from call diversion (Deprecated, use REDIRECTING updates instead.) */
448         AST_CONNECTED_LINE_UPDATE_SOURCE_DIVERSION,
449         /*! Update from call transfer(active) (Party has already answered) */
450         AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER,
451         /*! Update from call transfer(alerting) (Party has not answered yet) */
452         AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER_ALERTING
453 };
454
455 /*!
456  * \since 1.8
457  * \brief Convert connected line update source text code to value (used in config file parsing)
458  *
459  * \param data text string from config file
460  *
461  * \retval AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
462  * \retval -1 if not in table
463  */
464 int ast_connected_line_source_parse(const char *data);
465
466 /*!
467  * \since 1.8
468  * \brief Convert connected line update source value to explanatory string
469  *
470  * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
471  *
472  * \return string for human presentation
473  */
474 const char *ast_connected_line_source_describe(int data);
475
476 /*!
477  * \since 1.8
478  * \brief Convert connected line update source value to text code
479  *
480  * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
481  *
482  * \return string for config file
483  */
484 const char *ast_connected_line_source_name(int data);
485
486 /*!
487  * \since 1.8
488  * \brief Convert ast_party_name.char_set text code to value (used in config file parsing)
489  *
490  * \param data text string from config file
491  *
492  * \retval AST_PARTY_CHAR_SET from channel.h
493  * \retval -1 if not in table
494  */
495 int ast_party_name_charset_parse(const char *data);
496
497 /*!
498  * \since 1.8
499  * \brief Convert ast_party_name.char_set value to explanatory string
500  *
501  * \param data AST_PARTY_CHAR_SET from channel.h
502  *
503  * \return string for human presentation
504  */
505 const char *ast_party_name_charset_describe(int data);
506
507 /*!
508  * \since 1.8
509  * \brief Convert ast_party_name.char_set value to text code
510  *
511  * \param data AST_PARTY_CHAR_SET from channel.h
512  *
513  * \return string for config file
514  */
515 const char *ast_party_name_charset_str(int data);
516
517
518 #endif /* _ASTERISK_CALLERID_H */