00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief CallerID (and other GR30) management and generation 00021 * Includes code and algorithms from the Zapata library. 00022 * 00023 * \ref CID 00024 * 00025 */ 00026 00027 /*! 00028 * \page CID Caller ID names and numbers 00029 * 00030 * Caller ID names are currently 8 bit characters, propably 00031 * ISO8859-1, depending on what your channel drivers handle. 00032 * 00033 * IAX2 and SIP caller ID names are UTF8 00034 * On ISDN Caller ID names are 7 bit, Almost ASCII 00035 * (See http://www.zytrax.com/tech/ia5.html ) 00036 * 00037 * \note Asterisk does not currently support SIP utf8 caller ID names or caller ID's. 00038 * 00039 * \par See also 00040 * \arg \ref callerid.c 00041 * \arg \ref callerid.h 00042 * \arg \ref Def_CallerPres 00043 */ 00044 00045 #ifndef _ASTERISK_CALLERID_H 00046 #define _ASTERISK_CALLERID_H 00047 00048 #include "asterisk/frame_defs.h" 00049 00050 #define MAX_CALLERID_SIZE 32000 00051 00052 #define CID_PRIVATE_NAME (1 << 0) 00053 #define CID_PRIVATE_NUMBER (1 << 1) 00054 #define CID_UNKNOWN_NAME (1 << 2) 00055 #define CID_UNKNOWN_NUMBER (1 << 3) 00056 #define CID_MSGWAITING (1 << 4) 00057 #define CID_NOMSGWAITING (1 << 5) 00058 00059 #define CID_SIG_BELL 1 00060 #define CID_SIG_V23 2 00061 #define CID_SIG_DTMF 3 00062 #define CID_SIG_V23_JP 4 00063 #define CID_SIG_SMDI 5 00064 00065 #define CID_START_RING 1 00066 #define CID_START_POLARITY 2 00067 #define CID_START_POLARITY_IN 3 00068 #define CID_START_DTMF_NOALERT 4 00069 00070 /* defines dealing with message waiting indication generation */ 00071 /*! MWI SDMF format */ 00072 #define CID_MWI_TYPE_SDMF 0x00 00073 /*! MWI MDMF format -- generate only MWI field */ 00074 #define CID_MWI_TYPE_MDMF 0x01 00075 /*! MWI MDMF format -- generate name, callerid, date and MWI fields */ 00076 #define CID_MWI_TYPE_MDMF_FULL 0x02 00077 00078 #define AST_LIN2X(a) ((codec == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a))) 00079 #define AST_XLAW(a) ((codec == AST_FORMAT_ALAW) ? (AST_ALAW(a)) : (AST_MULAW(a))) 00080 00081 00082 struct callerid_state; 00083 typedef struct callerid_state CIDSTATE; 00084 00085 /*! \brief CallerID Initialization 00086 * \par 00087 * Initializes the callerid system. Mostly stuff for inverse FFT 00088 */ 00089 void callerid_init(void); 00090 00091 /*! \brief Generates a CallerID FSK stream in ulaw format suitable for transmission. 00092 * \param buf Buffer to use. If "buf" is supplied, it will use that buffer instead of allocating its own. 00093 * "buf" must be at least 32000 bytes in size of you want to be sure you don't have an overrun. 00094 * \param number Use NULL for no number or "P" for "private" 00095 * \param name name to be used 00096 * \param flags passed flags 00097 * \param callwaiting callwaiting flag 00098 * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW 00099 * \details 00100 * This function creates a stream of callerid (a callerid spill) data in ulaw format. 00101 * \return It returns the size 00102 * (in bytes) of the data (if it returns a size of 0, there is probably an error) 00103 */ 00104 int callerid_generate(unsigned char *buf, const char *number, const char *name, int flags, int callwaiting, format_t codec); 00105 00106 /*! \brief Create a callerID state machine 00107 * \param cid_signalling Type of signalling in use 00108 * 00109 * \details 00110 * This function returns a malloc'd instance of the callerid_state data structure. 00111 * \return Returns a pointer to a malloc'd callerid_state structure, or NULL on error. 00112 */ 00113 struct callerid_state *callerid_new(int cid_signalling); 00114 00115 /*! \brief Read samples into the state machine. 00116 * \param cid Which state machine to act upon 00117 * \param ubuf containing your samples 00118 * \param samples number of samples contained within the buffer. 00119 * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW) 00120 * 00121 * \details 00122 * Send received audio to the Caller*ID demodulator. 00123 * \retval -1 on error 00124 * \retval 0 for "needs more samples" 00125 * \retval 1 if the CallerID spill reception is complete. 00126 */ 00127 int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, format_t codec); 00128 00129 /*! \brief Read samples into the state machine. 00130 * \param cid Which state machine to act upon 00131 * \param ubuf containing your samples 00132 * \param samples number of samples contained within the buffer. 00133 * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW) 00134 * 00135 * \details 00136 * Send received audio to the Caller*ID demodulator (for japanese style lines). 00137 * \retval -1 on error 00138 * \retval 0 for "needs more samples" 00139 * \retval 1 if the CallerID spill reception is complete. 00140 */ 00141 int callerid_feed_jp(struct callerid_state *cid, unsigned char *ubuf, int samples, format_t codec); 00142 00143 /*! \brief Extract info out of callerID state machine. Flags are listed above 00144 * \param cid Callerid state machine to act upon 00145 * \param number Pass the address of a pointer-to-char (will contain the phone number) 00146 * \param name Pass the address of a pointer-to-char (will contain the name) 00147 * \param flags Pass the address of an int variable(will contain the various callerid flags) 00148 * 00149 * \details 00150 * This function extracts a callerid string out of a callerid_state state machine. 00151 * If no number is found, *number will be set to NULL. Likewise for the name. 00152 * Flags can contain any of the following: 00153 * 00154 * \return Returns nothing. 00155 */ 00156 void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags); 00157 00158 /*! 00159 * \brief Get and parse DTMF-based callerid 00160 * \param cidstring The actual transmitted string. 00161 * \param number The cid number is returned here. 00162 * \param flags The cid flags are returned here. 00163 */ 00164 void callerid_get_dtmf(char *cidstring, char *number, int *flags); 00165 00166 /*! \brief This function frees callerid_state cid. 00167 * \param cid This is the callerid_state state machine to free 00168 */ 00169 void callerid_free(struct callerid_state *cid); 00170 00171 /*! \brief Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format) 00172 * \param buf buffer for output samples. See callerid_generate() for details regarding buffer. 00173 * \param name Caller-ID Name 00174 * \param number Caller-ID Number 00175 * \param codec Asterisk codec (either AST_FORMAT_ALAW or AST_FORMAT_ULAW) 00176 * 00177 * \details 00178 * Acts like callerid_generate except uses an asterisk format callerid string. 00179 */ 00180 int ast_callerid_generate(unsigned char *buf, const char *name, const char *number, format_t codec); 00181 00182 /*! 00183 * \brief Generate message waiting indicator 00184 * \param buf 00185 * \param active The message indicator state 00186 * -- either 0 no messages in mailbox or 1 messages in mailbox 00187 * \param type Format of message (any of CID_MWI_TYPE_*) 00188 * \param codec 00189 * \param name 00190 * \param number 00191 * \param flags 00192 * \see callerid_generate() for more info as it uses the same encoding 00193 * \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation 00194 */ 00195 int ast_callerid_vmwi_generate(unsigned char *buf, int active, int type, format_t codec, const char *name, 00196 const char *number, int flags); 00197 00198 /*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm) 00199 * \see ast_callerid_generate() for other details 00200 */ 00201 int ast_callerid_callwaiting_generate(unsigned char *buf, const char *name, const char *number, format_t codec); 00202 00203 /*! \brief Destructively parse inbuf into name and location (or number) 00204 * \details 00205 * Parses callerid stream from inbuf and changes into useable form, outputed in name and location. 00206 * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed. 00207 * \param name address of a pointer-to-char for the name value of the stream. 00208 * \param location address of a pointer-to-char for the phone number value of the stream. 00209 * \note XXX 'name' is not parsed consistently e.g. we have 00210 * input location name 00211 * " foo bar " <123> 123 ' foo bar ' (with spaces around) 00212 * " foo bar " NULL 'foo bar' (without spaces around) 00213 * The parsing of leading and trailing space/quotes should be more consistent. 00214 * \return Returns 0 on success, -1 on failure. 00215 */ 00216 int ast_callerid_parse(char *instr, char **name, char **location); 00217 00218 /*! 00219 * \brief Generate a CAS (CPE Alert Signal) tone for 'n' samples 00220 * \param outbuf Allocated buffer for data. Must be at least 2400 bytes unless no SAS is desired 00221 * \param sas Non-zero if CAS should be preceeded by SAS 00222 * \param len How many samples to generate. 00223 * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW) 00224 * \return Returns -1 on error (if len is less than 2400), 0 on success. 00225 */ 00226 int ast_gen_cas(unsigned char *outbuf, int sas, int len, format_t codec); 00227 00228 /*! 00229 * \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... 00230 * \param n The number to be stripped/shrunk 00231 * \return Returns nothing important 00232 */ 00233 void ast_shrink_phone_number(char *n); 00234 00235 /*! 00236 * \brief Check if a string consists only of digits and + \# 00237 * \param n number to be checked. 00238 * \return Returns 0 if n is a number, 1 if it's not. 00239 */ 00240 int ast_isphonenumber(const char *n); 00241 00242 /*! 00243 * \brief Check if a string consists only of digits and and + \# ( ) - . 00244 * (meaning it can be cleaned with ast_shrink_phone_number) 00245 * \param exten The extension (or URI) to be checked. 00246 * \retval 1 if string is valid AST shrinkable phone number 00247 * \retval 0 if not 00248 */ 00249 int ast_is_shrinkable_phonenumber(const char *exten); 00250 00251 int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen); 00252 00253 char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown); 00254 00255 /* 00256 * Caller*ID and other GR-30 compatible generation 00257 * routines (used by ADSI for example) 00258 */ 00259 00260 extern float cid_dr[4]; 00261 extern float cid_di[4]; 00262 extern float clidsb; 00263 00264 static inline float callerid_getcarrier(float *cr, float *ci, int bit) 00265 { 00266 /* Move along. There's nothing to see here... */ 00267 float t; 00268 t = *cr * cid_dr[bit] - *ci * cid_di[bit]; 00269 *ci = *cr * cid_di[bit] + *ci * cid_dr[bit]; 00270 *cr = t; 00271 00272 t = 2.0 - (*cr * *cr + *ci * *ci); 00273 *cr *= t; 00274 *ci *= t; 00275 return *cr; 00276 } 00277 00278 #define PUT_BYTE(a) do { \ 00279 *(buf++) = (a); \ 00280 bytes++; \ 00281 } while(0) 00282 00283 #define PUT_AUDIO_SAMPLE(y) do { \ 00284 int __sample_idx = (short)(rint(8192.0 * (y))); \ 00285 *(buf++) = AST_LIN2X(__sample_idx); \ 00286 bytes++; \ 00287 } while(0) 00288 00289 #define PUT_CLID_MARKMS do { \ 00290 int __clid_x; \ 00291 for (__clid_x=0;__clid_x<8;__clid_x++) \ 00292 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \ 00293 } while(0) 00294 00295 #define PUT_CLID_BAUD(bit) do { \ 00296 while(scont < clidsb) { \ 00297 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \ 00298 scont += 1.0; \ 00299 } \ 00300 scont -= clidsb; \ 00301 } while(0) 00302 00303 00304 #define PUT_CLID(byte) do { \ 00305 int z; \ 00306 unsigned char b = (byte); \ 00307 PUT_CLID_BAUD(0); /* Start bit */ \ 00308 for (z=0;z<8;z++) { \ 00309 PUT_CLID_BAUD(b & 1); \ 00310 b >>= 1; \ 00311 } \ 00312 PUT_CLID_BAUD(1); /* Stop bit */ \ 00313 } while(0) 00314 00315 /* Various defines and bits for handling PRI- and SS7-type restriction */ 00316 00317 #define AST_PRES_NUMBER_TYPE 0x03 00318 #define AST_PRES_USER_NUMBER_UNSCREENED 0x00 00319 #define AST_PRES_USER_NUMBER_PASSED_SCREEN 0x01 00320 #define AST_PRES_USER_NUMBER_FAILED_SCREEN 0x02 00321 #define AST_PRES_NETWORK_NUMBER 0x03 00322 00323 #define AST_PRES_RESTRICTION 0x60 00324 #define AST_PRES_ALLOWED 0x00 00325 #define AST_PRES_RESTRICTED 0x20 00326 #define AST_PRES_UNAVAILABLE 0x40 00327 #define AST_PRES_RESERVED 0x60 00328 00329 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \ 00330 (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_UNSCREENED) 00331 00332 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \ 00333 (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_PASSED_SCREEN) 00334 00335 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \ 00336 (AST_PRES_ALLOWED | AST_PRES_USER_NUMBER_FAILED_SCREEN) 00337 00338 #define AST_PRES_ALLOWED_NETWORK_NUMBER \ 00339 (AST_PRES_ALLOWED | AST_PRES_NETWORK_NUMBER) 00340 00341 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \ 00342 (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_UNSCREENED) 00343 00344 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \ 00345 (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_PASSED_SCREEN) 00346 00347 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \ 00348 (AST_PRES_RESTRICTED | AST_PRES_USER_NUMBER_FAILED_SCREEN) 00349 00350 #define AST_PRES_PROHIB_NETWORK_NUMBER \ 00351 (AST_PRES_RESTRICTED | AST_PRES_NETWORK_NUMBER) 00352 00353 #define AST_PRES_NUMBER_NOT_AVAILABLE \ 00354 (AST_PRES_UNAVAILABLE | AST_PRES_NETWORK_NUMBER) 00355 00356 int ast_parse_caller_presentation(const char *data); 00357 const char *ast_describe_caller_presentation(int data); 00358 const char *ast_named_caller_presentation(int data); 00359 00360 /*! 00361 * \page Def_CallerPres Caller ID Presentation 00362 * 00363 * Caller ID presentation values are used to set properties to a 00364 * caller ID in PSTN networks, and as RPID value in SIP transactions. 00365 * 00366 * The following values are available to use: 00367 * \arg \b Defined value, text string in config file, explanation 00368 * 00369 * \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened, 00370 * \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen, 00371 * \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen, 00372 * \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number, 00373 * \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened, 00374 * \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen, 00375 * \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen, 00376 * \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number, 00377 * 00378 * \par References 00379 * \arg \ref callerid.h Definitions 00380 * \arg \ref callerid.c Functions 00381 * \arg \ref CID Caller ID names and numbers 00382 */ 00383 00384 /*! 00385 * \brief redirecting reason codes. 00386 * 00387 * This list attempts to encompass redirecting reasons 00388 * as defined by several channel technologies. 00389 */ 00390 enum AST_REDIRECTING_REASON { 00391 AST_REDIRECTING_REASON_UNKNOWN, 00392 AST_REDIRECTING_REASON_USER_BUSY, 00393 AST_REDIRECTING_REASON_NO_ANSWER, 00394 AST_REDIRECTING_REASON_UNAVAILABLE, 00395 AST_REDIRECTING_REASON_UNCONDITIONAL, 00396 AST_REDIRECTING_REASON_TIME_OF_DAY, 00397 AST_REDIRECTING_REASON_DO_NOT_DISTURB, 00398 AST_REDIRECTING_REASON_DEFLECTION, 00399 AST_REDIRECTING_REASON_FOLLOW_ME, 00400 AST_REDIRECTING_REASON_OUT_OF_ORDER, 00401 AST_REDIRECTING_REASON_AWAY, 00402 AST_REDIRECTING_REASON_CALL_FWD_DTE, /* This is something defined in Q.931, and no I don't know what it means */ 00403 }; 00404 00405 /*! 00406 * \since 1.8 00407 * \brief Convert redirecting reason text code to value (used in config file parsing) 00408 * 00409 * \param data text string from config file 00410 * 00411 * \retval Q931_REDIRECTING_REASON from callerid.h 00412 * \retval -1 if not in table 00413 */ 00414 int ast_redirecting_reason_parse(const char *data); 00415 00416 /*! 00417 * \since 1.8 00418 * \brief Convert redirecting reason value to explanatory string 00419 * 00420 * \param data Q931_REDIRECTING_REASON from callerid.h 00421 * 00422 * \return string for human presentation 00423 */ 00424 const char *ast_redirecting_reason_describe(int data); 00425 00426 /*! 00427 * \since 1.8 00428 * \brief Convert redirecting reason value to text code 00429 * 00430 * \param data Q931_REDIRECTING_REASON from callerid.h 00431 * 00432 * \return string for config file 00433 */ 00434 const char *ast_redirecting_reason_name(int data); 00435 00436 /*! 00437 * \brief Connected line update source code 00438 */ 00439 enum AST_CONNECTED_LINE_UPDATE_SOURCE { 00440 /*! Update for unknown reason (May be interpreted to mean from answer) */ 00441 AST_CONNECTED_LINE_UPDATE_SOURCE_UNKNOWN, 00442 /*! Update from normal call answering */ 00443 AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER, 00444 /*! Update from call diversion (Deprecated, use REDIRECTING updates instead.) */ 00445 AST_CONNECTED_LINE_UPDATE_SOURCE_DIVERSION, 00446 /*! Update from call transfer(active) (Party has already answered) */ 00447 AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER, 00448 /*! Update from call transfer(alerting) (Party has not answered yet) */ 00449 AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER_ALERTING 00450 }; 00451 00452 /*! 00453 * \since 1.8 00454 * \brief Convert connected line update source text code to value (used in config file parsing) 00455 * 00456 * \param data text string from config file 00457 * 00458 * \retval AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h 00459 * \retval -1 if not in table 00460 */ 00461 int ast_connected_line_source_parse(const char *data); 00462 00463 /*! 00464 * \since 1.8 00465 * \brief Convert connected line update source value to explanatory string 00466 * 00467 * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h 00468 * 00469 * \return string for human presentation 00470 */ 00471 const char *ast_connected_line_source_describe(int data); 00472 00473 /*! 00474 * \since 1.8 00475 * \brief Convert connected line update source value to text code 00476 * 00477 * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h 00478 * 00479 * \return string for config file 00480 */ 00481 const char *ast_connected_line_source_name(int data); 00482 00483 /*! 00484 * \since 1.8 00485 * \brief Convert ast_party_name.char_set text code to value (used in config file parsing) 00486 * 00487 * \param data text string from config file 00488 * 00489 * \retval AST_PARTY_CHAR_SET from channel.h 00490 * \retval -1 if not in table 00491 */ 00492 int ast_party_name_charset_parse(const char *data); 00493 00494 /*! 00495 * \since 1.8 00496 * \brief Convert ast_party_name.char_set value to explanatory string 00497 * 00498 * \param data AST_PARTY_CHAR_SET from channel.h 00499 * 00500 * \return string for human presentation 00501 */ 00502 const char *ast_party_name_charset_describe(int data); 00503 00504 /*! 00505 * \since 1.8 00506 * \brief Convert ast_party_name.char_set value to text code 00507 * 00508 * \param data AST_PARTY_CHAR_SET from channel.h 00509 * 00510 * \return string for config file 00511 */ 00512 const char *ast_party_name_charset_str(int data); 00513 00514 00515 #endif /* _ASTERISK_CALLERID_H */