Merged revisions 182882 via svnmerge from
[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 #define MAX_CALLERID_SIZE 32000
49
50 #define CID_PRIVATE_NAME                (1 << 0)
51 #define CID_PRIVATE_NUMBER              (1 << 1)
52 #define CID_UNKNOWN_NAME                (1 << 2)
53 #define CID_UNKNOWN_NUMBER              (1 << 3)
54 #define CID_MSGWAITING                  (1 << 4)
55 #define CID_NOMSGWAITING                (1 << 5)
56
57 #define CID_SIG_BELL    1
58 #define CID_SIG_V23     2
59 #define CID_SIG_DTMF    3
60 #define CID_SIG_V23_JP  4
61 #define CID_SIG_SMDI    5
62
63 #define CID_START_RING  1
64 #define CID_START_POLARITY 2
65 #define CID_START_POLARITY_IN 3
66
67 /* defines dealing with message waiting indication generation */
68 /*! MWI SDMF format */
69 #define CID_MWI_TYPE_SDMF               0x00
70 /*! MWI MDMF format -- generate only MWI field */
71 #define CID_MWI_TYPE_MDMF               0x01
72 /*! MWI MDMF format -- generate name, callerid, date and MWI fields */
73 #define CID_MWI_TYPE_MDMF_FULL  0x02
74
75 #define AST_LIN2X(a) ((codec == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
76 #define AST_XLAW(a) ((codec == AST_FORMAT_ALAW) ? (AST_ALAW(a)) : (AST_MULAW(a)))
77
78
79 struct callerid_state;
80 typedef struct callerid_state CIDSTATE;
81
82 /*! \brief CallerID Initialization
83  * \par
84  * Initializes the callerid system.  Mostly stuff for inverse FFT
85  */
86 void callerid_init(void);
87
88 /*! \brief Generates a CallerID FSK stream in ulaw format suitable for transmission.
89  * \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.
90  * \param number Use NULL for no number or "P" for "private"
91  * \param name name to be used
92  * \param flags passed flags
93  * \param callwaiting callwaiting flag
94  * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW
95  * This function creates a stream of callerid (a callerid spill) data in ulaw format.
96  * \return It returns the size
97  * (in bytes) of the data (if it returns a size of 0, there is probably an error)
98 */
99 int callerid_generate(unsigned char *buf, const char *number, const char *name, int flags, int callwaiting, int codec);
100
101 /*! \brief Create a callerID state machine
102  * \param cid_signalling Type of signalling in use
103  *
104  * This function returns a malloc'd instance of the callerid_state data structure.
105  * \return Returns a pointer to a malloc'd callerid_state structure, or NULL on error.
106  */
107 struct callerid_state *callerid_new(int cid_signalling);
108
109 /*! \brief Read samples into the state machine.
110  * \param cid Which state machine to act upon
111  * \param ubuf containing your samples
112  * \param samples number of samples contained within the buffer.
113  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
114  *
115  * Send received audio to the Caller*ID demodulator.
116  * \return Returns -1 on error, 0 for "needs more samples",
117  * and 1 if the CallerID spill reception is complete.
118  */
119 int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
120
121 /*! \brief Read samples into the state machine.
122  * \param cid Which state machine to act upon
123  * \param ubuf containing your samples
124  * \param samples number of samples contained within the buffer.
125  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
126  *
127  * Send received audio to the Caller*ID demodulator (for japanese style lines).
128  * \return Returns -1 on error, 0 for "needs more samples",
129  * and 1 if the CallerID spill reception is complete.
130  */
131 int callerid_feed_jp(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
132
133 /*! \brief Extract info out of callerID state machine.  Flags are listed above
134  * \param cid Callerid state machine to act upon
135  * \param number Pass the address of a pointer-to-char (will contain the phone number)
136  * \param name Pass the address of a pointer-to-char (will contain the name)
137  * \param flags Pass the address of an int variable(will contain the various callerid flags)
138  *
139  * This function extracts a callerid string out of a callerid_state state machine.
140  * If no number is found, *number will be set to NULL.  Likewise for the name.
141  * Flags can contain any of the following:
142  *
143  * \return Returns nothing.
144  */
145 void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags);
146
147 /*! Get and parse DTMF-based callerid  */
148 /*!
149  * \param cidstring The actual transmitted string.
150  * \param number The cid number is returned here.
151  * \param flags The cid flags are returned here.
152  * This function parses DTMF callerid.
153  */
154 void callerid_get_dtmf(char *cidstring, char *number, int *flags);
155
156 /*! \brief Free a callerID state
157  * \param cid This is the callerid_state state machine to free
158  * This function frees callerid_state cid.
159  */
160 void callerid_free(struct callerid_state *cid);
161
162 /*! \brief Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format)
163  * \param buf buffer for output samples. See callerid_generate() for details regarding buffer.
164  * \param name Caller-ID Name
165  * \param number Caller-ID Number
166  * \param codec Asterisk codec (either AST_FORMAT_ALAW or AST_FORMAT_ULAW)
167  *
168  * Acts like callerid_generate except uses an asterisk format callerid string.
169  */
170 int ast_callerid_generate(unsigned char *buf, const char *name, const char *number, int codec);
171
172 /*! \brief Generate message waiting indicator
173  *  \param active The message indicator state
174  *  -- either 0 no messages in mailbox or 1 messages in mailbox
175  *  \param type Format of message (any of CID_MWI_TYPE_*)
176  *  \see callerid_generate() for more info as it use the same encoding
177  *  \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
178 */
179 int ast_callerid_vmwi_generate(unsigned char *buf, int active, int type, int codec, const char *name,
180         const char *number, int flags);
181
182 /*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm)
183  * See ast_callerid_generate() for other details
184  */
185 int ast_callerid_callwaiting_generate(unsigned char *buf, const char *name, const char *number, int codec);
186
187 /*! \brief Destructively parse inbuf into name and location (or number)
188  * Parses callerid stream from inbuf and changes into useable form, outputed in name and location.
189  * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed.
190  * \param name address of a pointer-to-char for the name value of the stream.
191  * \param location address of a pointer-to-char for the phone number value of the stream.
192  * \return Returns 0 on success, -1 on failure.
193  */
194 int ast_callerid_parse(char *instr, char **name, char **location);
195
196 /*! Generate a CAS (CPE Alert Signal) tone for 'n' samples */
197 /*!
198  * \param outbuf Allocated buffer for data.  Must be at least 2400 bytes unless no SAS is desired
199  * \param sas Non-zero if CAS should be preceeded by SAS
200  * \param len How many samples to generate.
201  * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
202  * \return Returns -1 on error (if len is less than 2400), 0 on success.
203  */
204 int ast_gen_cas(unsigned char *outbuf, int sas, int len, int codec);
205
206 /*! \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... */
207 /*!
208  * \param n The number to be stripped/shrunk
209  * \return Returns nothing important
210  */
211 void ast_shrink_phone_number(char *n);
212
213 /*! \brief Check if a string consists only of digits and + \#
214     \param n number to be checked.
215     \return Returns 0 if n is a number, 1 if it's not.
216  */
217 int ast_isphonenumber(const char *n);
218
219 /*! \brief Check if a string consists only of digits and and + \# ( ) - .
220         (meaning it can be cleaned with ast_shrink_phone_number)
221     \param exten The extension (or URI) to be checked.
222     \return Returns 0 if n is a number, 1 if it's not.
223  */
224 int ast_is_shrinkable_phonenumber(const char *exten);
225
226 int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen);
227
228 char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown);
229
230 /*
231  * Caller*ID and other GR-30 compatible generation
232  * routines (used by ADSI for example)
233  */
234
235 extern float cid_dr[4];
236 extern float cid_di[4];
237 extern float clidsb;
238
239 static inline float callerid_getcarrier(float *cr, float *ci, int bit)
240 {
241         /* Move along.  There's nothing to see here... */
242         float t;
243         t = *cr * cid_dr[bit] - *ci * cid_di[bit];
244         *ci = *cr * cid_di[bit] + *ci * cid_dr[bit];
245         *cr = t;
246
247         t = 2.0 - (*cr * *cr + *ci * *ci);
248         *cr *= t;
249         *ci *= t;
250         return *cr;
251 }
252
253 #define PUT_BYTE(a) do { \
254         *(buf++) = (a); \
255         bytes++; \
256 } while(0)
257
258 #define PUT_AUDIO_SAMPLE(y) do { \
259         int __sample_idx = (short)(rint(8192.0 * (y))); \
260         *(buf++) = AST_LIN2X(__sample_idx); \
261         bytes++; \
262 } while(0)
263
264 #define PUT_CLID_MARKMS do { \
265         int __clid_x; \
266         for (__clid_x=0;__clid_x<8;__clid_x++) \
267                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \
268 } while(0)
269
270 #define PUT_CLID_BAUD(bit) do { \
271         while(scont < clidsb) { \
272                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \
273                 scont += 1.0; \
274         } \
275         scont -= clidsb; \
276 } while(0)
277
278
279 #define PUT_CLID(byte) do { \
280         int z; \
281         unsigned char b = (byte); \
282         PUT_CLID_BAUD(0);       /* Start bit */ \
283         for (z=0;z<8;z++) { \
284                 PUT_CLID_BAUD(b & 1); \
285                 b >>= 1; \
286         } \
287         PUT_CLID_BAUD(1);       /* Stop bit */ \
288 } while(0)
289
290 /* Various defines and bits for handling PRI- and SS7-type restriction */
291
292 #define AST_PRES_NUMBER_TYPE                            0x03
293 #define AST_PRES_USER_NUMBER_UNSCREENED                 0x00
294 #define AST_PRES_USER_NUMBER_PASSED_SCREEN              0x01
295 #define AST_PRES_USER_NUMBER_FAILED_SCREEN              0x02
296 #define AST_PRES_NETWORK_NUMBER                         0x03
297
298 #define AST_PRES_RESTRICTION                            0x60
299 #define AST_PRES_ALLOWED                                0x00
300 #define AST_PRES_RESTRICTED                             0x20
301 #define AST_PRES_UNAVAILABLE                            0x40
302 #define AST_PRES_RESERVED                               0x60
303
304 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \
305         AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_ALLOWED
306
307 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \
308         AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_ALLOWED
309
310 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \
311         AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_ALLOWED
312
313 #define AST_PRES_ALLOWED_NETWORK_NUMBER \
314         AST_PRES_NETWORK_NUMBER + AST_PRES_ALLOWED
315
316 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \
317         AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_RESTRICTED
318
319 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \
320         AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_RESTRICTED
321
322 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \
323         AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_RESTRICTED
324
325 #define AST_PRES_PROHIB_NETWORK_NUMBER \
326         AST_PRES_NETWORK_NUMBER + AST_PRES_RESTRICTED
327
328 #define AST_PRES_NUMBER_NOT_AVAILABLE \
329         AST_PRES_NETWORK_NUMBER + AST_PRES_UNAVAILABLE
330
331 int ast_parse_caller_presentation(const char *data);
332 const char *ast_describe_caller_presentation(int data);
333 const char *ast_named_caller_presentation(int data);
334
335 /*! \page Def_CallerPres Caller ID Presentation
336
337         Caller ID presentation values are used to set properties to a
338         caller ID in PSTN networks, and as RPID value in SIP transactions.
339
340         The following values are available to use:
341         \arg \b Defined value, text string in config file, explanation
342
343         \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened,
344         \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen,
345         \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen,
346         \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number,
347         \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened,
348         \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen,
349         \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen,
350         \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number,
351
352         \par References
353         \arg \ref callerid.h Definitions
354         \arg \ref callerid.c Functions
355         \arg \ref CID Caller ID names and numbers
356 */
357
358
359 #endif /* _ASTERISK_CALLERID_H */