callerid.h

Go to the documentation of this file.
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/format.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) ((ast_format_cmp(codec, ast_format_alaw) == AST_FORMAT_CMP_EQUAL) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
00079 #define AST_XLAW(a) ((ast_format_cmp(codec, ast_format_alaw) == AST_FORMAT_CMP_EQUAL) ? (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, struct ast_format *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, struct ast_format *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, struct ast_format *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, struct ast_format *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, struct ast_format *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, struct ast_format *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, struct ast_format *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    AST_REDIRECTING_REASON_SEND_TO_VM,
00404 };
00405 
00406 /*!
00407  * \since 1.8
00408  * \brief Convert redirecting reason text code to value (used in config file parsing)
00409  *
00410  * \param data text string from config file
00411  *
00412  * \retval Q931_REDIRECTING_REASON from callerid.h
00413  * \retval -1 if not in table
00414  */
00415 int ast_redirecting_reason_parse(const char *data);
00416 
00417 /*!
00418  * \since 1.8
00419  * \brief Convert redirecting reason value to explanatory string
00420  *
00421  * \param data Q931_REDIRECTING_REASON from callerid.h
00422  *
00423  * \return string for human presentation
00424  */
00425 const char *ast_redirecting_reason_describe(int data);
00426 
00427 struct ast_party_redirecting_reason;
00428 
00429 /*!
00430  * \since 1.8
00431  * \brief Convert redirecting reason value to text code
00432  *
00433  * \param data ast_party_redirecting_reason structure from channel.h
00434  *
00435  * \return string for config file
00436  */
00437 const char *ast_redirecting_reason_name(const struct ast_party_redirecting_reason *data);
00438 
00439 /*!
00440  * \brief Connected line update source code
00441  */
00442 enum AST_CONNECTED_LINE_UPDATE_SOURCE {
00443    /*! Update for unknown reason (May be interpreted to mean from answer) */
00444    AST_CONNECTED_LINE_UPDATE_SOURCE_UNKNOWN,
00445    /*! Update from normal call answering */
00446    AST_CONNECTED_LINE_UPDATE_SOURCE_ANSWER,
00447    /*! Update from call diversion (Deprecated, use REDIRECTING updates instead.) */
00448    AST_CONNECTED_LINE_UPDATE_SOURCE_DIVERSION,
00449    /*! Update from call transfer(active) (Party has already answered) */
00450    AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER,
00451    /*! Update from call transfer(alerting) (Party has not answered yet) */
00452    AST_CONNECTED_LINE_UPDATE_SOURCE_TRANSFER_ALERTING
00453 };
00454 
00455 /*!
00456  * \since 1.8
00457  * \brief Convert connected line update source text code to value (used in config file parsing)
00458  *
00459  * \param data text string from config file
00460  *
00461  * \retval AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
00462  * \retval -1 if not in table
00463  */
00464 int ast_connected_line_source_parse(const char *data);
00465 
00466 /*!
00467  * \since 1.8
00468  * \brief Convert connected line update source value to explanatory string
00469  *
00470  * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
00471  *
00472  * \return string for human presentation
00473  */
00474 const char *ast_connected_line_source_describe(int data);
00475 
00476 /*!
00477  * \since 1.8
00478  * \brief Convert connected line update source value to text code
00479  *
00480  * \param data AST_CONNECTED_LINE_UPDATE_SOURCE from callerid.h
00481  *
00482  * \return string for config file
00483  */
00484 const char *ast_connected_line_source_name(int data);
00485 
00486 /*!
00487  * \since 1.8
00488  * \brief Convert ast_party_name.char_set text code to value (used in config file parsing)
00489  *
00490  * \param data text string from config file
00491  *
00492  * \retval AST_PARTY_CHAR_SET from channel.h
00493  * \retval -1 if not in table
00494  */
00495 int ast_party_name_charset_parse(const char *data);
00496 
00497 /*!
00498  * \since 1.8
00499  * \brief Convert ast_party_name.char_set value to explanatory string
00500  *
00501  * \param data AST_PARTY_CHAR_SET from channel.h
00502  *
00503  * \return string for human presentation
00504  */
00505 const char *ast_party_name_charset_describe(int data);
00506 
00507 /*!
00508  * \since 1.8
00509  * \brief Convert ast_party_name.char_set value to text code
00510  *
00511  * \param data AST_PARTY_CHAR_SET from channel.h
00512  *
00513  * \return string for config file
00514  */
00515 const char *ast_party_name_charset_str(int data);
00516 
00517 
00518 #endif /* _ASTERISK_CALLERID_H */

Generated on Thu Apr 16 06:27:16 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6