Thu Apr 28 2011 16:56:42

Asterisk developer's documentation


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 #define MAX_CALLERID_SIZE 32000
00049 
00050 #define CID_PRIVATE_NAME      (1 << 0)
00051 #define CID_PRIVATE_NUMBER    (1 << 1)
00052 #define CID_UNKNOWN_NAME      (1 << 2)
00053 #define CID_UNKNOWN_NUMBER    (1 << 3)
00054 #define CID_MSGWAITING        (1 << 4)
00055 #define CID_NOMSGWAITING      (1 << 5)
00056 
00057 #define CID_SIG_BELL 1
00058 #define CID_SIG_V23  2
00059 #define CID_SIG_DTMF 3
00060 #define CID_SIG_V23_JP  4
00061 #define CID_SIG_SMDI 5
00062 
00063 #define CID_START_RING  1
00064 #define CID_START_POLARITY 2
00065 #define CID_START_POLARITY_IN 3
00066 
00067 /* defines dealing with message waiting indication generation */
00068 /*! MWI SDMF format */
00069 #define CID_MWI_TYPE_SDMF     0x00
00070 /*! MWI MDMF format -- generate only MWI field */
00071 #define CID_MWI_TYPE_MDMF     0x01
00072 /*! MWI MDMF format -- generate name, callerid, date and MWI fields */
00073 #define CID_MWI_TYPE_MDMF_FULL   0x02
00074 
00075 #define AST_LIN2X(a) ((codec == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
00076 #define AST_XLAW(a) ((codec == AST_FORMAT_ALAW) ? (AST_ALAW(a)) : (AST_MULAW(a)))
00077 
00078 
00079 struct callerid_state;
00080 typedef struct callerid_state CIDSTATE;
00081 
00082 /*! \brief CallerID Initialization
00083  * \par
00084  * Initializes the callerid system.  Mostly stuff for inverse FFT
00085  */
00086 void callerid_init(void);
00087 
00088 /*! \brief Generates a CallerID FSK stream in ulaw format suitable for transmission.
00089  * \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.
00090  * \param number Use NULL for no number or "P" for "private"
00091  * \param name name to be used
00092  * \param flags passed flags
00093  * \param callwaiting callwaiting flag
00094  * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW
00095  * This function creates a stream of callerid (a callerid spill) data in ulaw format.
00096  * \return It returns the size
00097  * (in bytes) of the data (if it returns a size of 0, there is probably an error)
00098 */
00099 int callerid_generate(unsigned char *buf, const char *number, const char *name, int flags, int callwaiting, int codec);
00100 
00101 /*! \brief Create a callerID state machine
00102  * \param cid_signalling Type of signalling in use
00103  *
00104  * This function returns a malloc'd instance of the callerid_state data structure.
00105  * \return Returns a pointer to a malloc'd callerid_state structure, or NULL on error.
00106  */
00107 struct callerid_state *callerid_new(int cid_signalling);
00108 
00109 /*! \brief Read samples into the state machine.
00110  * \param cid Which state machine to act upon
00111  * \param ubuf containing your samples
00112  * \param samples number of samples contained within the buffer.
00113  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
00114  *
00115  * Send received audio to the Caller*ID demodulator.
00116  * \return Returns -1 on error, 0 for "needs more samples",
00117  * and 1 if the CallerID spill reception is complete.
00118  */
00119 int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
00120 
00121 /*! \brief Read samples into the state machine.
00122  * \param cid Which state machine to act upon
00123  * \param ubuf containing your samples
00124  * \param samples number of samples contained within the buffer.
00125  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
00126  *
00127  * Send received audio to the Caller*ID demodulator (for japanese style lines).
00128  * \return Returns -1 on error, 0 for "needs more samples",
00129  * and 1 if the CallerID spill reception is complete.
00130  */
00131 int callerid_feed_jp(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
00132 
00133 /*! \brief Extract info out of callerID state machine.  Flags are listed above
00134  * \param cid Callerid state machine to act upon
00135  * \param number Pass the address of a pointer-to-char (will contain the phone number)
00136  * \param name Pass the address of a pointer-to-char (will contain the name)
00137  * \param flags Pass the address of an int variable(will contain the various callerid flags)
00138  *
00139  * This function extracts a callerid string out of a callerid_state state machine.
00140  * If no number is found, *number will be set to NULL.  Likewise for the name.
00141  * Flags can contain any of the following:
00142  *
00143  * \return Returns nothing.
00144  */
00145 void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags);
00146 
00147 /*! Get and parse DTMF-based callerid  */
00148 /*!
00149  * \param cidstring The actual transmitted string.
00150  * \param number The cid number is returned here.
00151  * \param flags The cid flags are returned here.
00152  * This function parses DTMF callerid.
00153  */
00154 void callerid_get_dtmf(char *cidstring, char *number, int *flags);
00155 
00156 /*! \brief Free a callerID state
00157  * \param cid This is the callerid_state state machine to free
00158  * This function frees callerid_state cid.
00159  */
00160 void callerid_free(struct callerid_state *cid);
00161 
00162 /*! \brief Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format)
00163  * \param buf buffer for output samples. See callerid_generate() for details regarding buffer.
00164  * \param name Caller-ID Name
00165  * \param number Caller-ID Number
00166  * \param codec Asterisk codec (either AST_FORMAT_ALAW or AST_FORMAT_ULAW)
00167  *
00168  * Acts like callerid_generate except uses an asterisk format callerid string.
00169  */
00170 int ast_callerid_generate(unsigned char *buf, const char *name, const char *number, int codec);
00171 
00172 /*! \brief Generate message waiting indicator
00173  *  \param active The message indicator state
00174  *  -- either 0 no messages in mailbox or 1 messages in mailbox
00175  *  \param type Format of message (any of CID_MWI_TYPE_*)
00176  *  \see callerid_generate() for more info as it use the same encoding
00177  *  \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
00178 */
00179 int vmwi_generate(unsigned char *buf, int active, int type, int codec, const char *name,
00180    const char *number, int flags);
00181 
00182 /*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm)
00183  * See ast_callerid_generate() for other details
00184  */
00185 int ast_callerid_callwaiting_generate(unsigned char *buf, const char *name, const char *number, int codec);
00186 
00187 /*! \brief Destructively parse inbuf into name and location (or number)
00188  * Parses callerid stream from inbuf and changes into useable form, outputed in name and location.
00189  * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed.
00190  * \param name address of a pointer-to-char for the name value of the stream.
00191  * \param location address of a pointer-to-char for the phone number value of the stream.
00192  * \return Returns 0 on success, -1 on failure.
00193  */
00194 int ast_callerid_parse(char *instr, char **name, char **location);
00195 
00196 /*! Generate a CAS (CPE Alert Signal) tone for 'n' samples */
00197 /*!
00198  * \param outbuf Allocated buffer for data.  Must be at least 2400 bytes unless no SAS is desired
00199  * \param sas Non-zero if CAS should be preceeded by SAS
00200  * \param len How many samples to generate.
00201  * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
00202  * \return Returns -1 on error (if len is less than 2400), 0 on success.
00203  */
00204 int ast_gen_cas(unsigned char *outbuf, int sas, int len, int codec);
00205 
00206 /*! \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... */
00207 /*!
00208  * \param n The number to be stripped/shrunk
00209  * \return Returns nothing important
00210  */
00211 void ast_shrink_phone_number(char *n);
00212 
00213 /*! \brief Check if a string consists only of digits and + \#
00214     \param n number to be checked.
00215     \return Returns 0 if n is a number, 1 if it's not.
00216  */
00217 int ast_isphonenumber(const char *n);
00218 
00219 /*! \brief Check if a string consists only of digits and and + \# ( ) - .
00220    (meaning it can be cleaned with ast_shrink_phone_number)
00221     \param exten The extension (or URI) to be checked.
00222     \return Returns 0 if n is a number, 1 if it's not.
00223  */
00224 int ast_is_shrinkable_phonenumber(const char *exten);
00225 
00226 int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen);
00227 
00228 char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown);
00229 
00230 /*
00231  * Caller*ID and other GR-30 compatible generation
00232  * routines (used by ADSI for example)
00233  */
00234 
00235 extern float cid_dr[4];
00236 extern float cid_di[4];
00237 extern float clidsb;
00238 
00239 static inline float callerid_getcarrier(float *cr, float *ci, int bit)
00240 {
00241    /* Move along.  There's nothing to see here... */
00242    float t;
00243    t = *cr * cid_dr[bit] - *ci * cid_di[bit];
00244    *ci = *cr * cid_di[bit] + *ci * cid_dr[bit];
00245    *cr = t;
00246 
00247    t = 2.0 - (*cr * *cr + *ci * *ci);
00248    *cr *= t;
00249    *ci *= t;
00250    return *cr;
00251 }
00252 
00253 #define PUT_BYTE(a) do { \
00254    *(buf++) = (a); \
00255    bytes++; \
00256 } while(0)
00257 
00258 #define PUT_AUDIO_SAMPLE(y) do { \
00259    int __sample_idx = (short)(rint(8192.0 * (y))); \
00260    *(buf++) = AST_LIN2X(__sample_idx); \
00261    bytes++; \
00262 } while(0)
00263 
00264 #define PUT_CLID_MARKMS do { \
00265    int __clid_x; \
00266    for (__clid_x=0;__clid_x<8;__clid_x++) \
00267       PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \
00268 } while(0)
00269 
00270 #define PUT_CLID_BAUD(bit) do { \
00271    while(scont < clidsb) { \
00272       PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \
00273       scont += 1.0; \
00274    } \
00275    scont -= clidsb; \
00276 } while(0)
00277 
00278 
00279 #define PUT_CLID(byte) do { \
00280    int z; \
00281    unsigned char b = (byte); \
00282    PUT_CLID_BAUD(0);    /* Start bit */ \
00283    for (z=0;z<8;z++) { \
00284       PUT_CLID_BAUD(b & 1); \
00285       b >>= 1; \
00286    } \
00287    PUT_CLID_BAUD(1); /* Stop bit */ \
00288 } while(0)
00289 
00290 /* Various defines and bits for handling PRI- and SS7-type restriction */
00291 
00292 #define AST_PRES_NUMBER_TYPE           0x03
00293 #define AST_PRES_USER_NUMBER_UNSCREENED         0x00
00294 #define AST_PRES_USER_NUMBER_PASSED_SCREEN      0x01
00295 #define AST_PRES_USER_NUMBER_FAILED_SCREEN      0x02
00296 #define AST_PRES_NETWORK_NUMBER           0x03
00297 
00298 #define AST_PRES_RESTRICTION           0x60
00299 #define AST_PRES_ALLOWED            0x00
00300 #define AST_PRES_RESTRICTED            0x20
00301 #define AST_PRES_UNAVAILABLE           0x40
00302 #define AST_PRES_RESERVED           0x60
00303 
00304 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \
00305    AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_ALLOWED
00306 
00307 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \
00308    AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_ALLOWED
00309 
00310 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \
00311    AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_ALLOWED
00312 
00313 #define AST_PRES_ALLOWED_NETWORK_NUMBER   \
00314    AST_PRES_NETWORK_NUMBER + AST_PRES_ALLOWED
00315 
00316 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \
00317    AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_RESTRICTED
00318 
00319 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \
00320    AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_RESTRICTED
00321 
00322 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \
00323    AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_RESTRICTED
00324 
00325 #define AST_PRES_PROHIB_NETWORK_NUMBER \
00326    AST_PRES_NETWORK_NUMBER + AST_PRES_RESTRICTED
00327 
00328 #define AST_PRES_NUMBER_NOT_AVAILABLE \
00329    AST_PRES_NETWORK_NUMBER + AST_PRES_UNAVAILABLE
00330 
00331 int ast_parse_caller_presentation(const char *data);
00332 const char *ast_describe_caller_presentation(int data);
00333 const char *ast_named_caller_presentation(int data);
00334 
00335 /*! \page Def_CallerPres Caller ID Presentation
00336 
00337    Caller ID presentation values are used to set properties to a
00338    caller ID in PSTN networks, and as RPID value in SIP transactions.
00339 
00340    The following values are available to use:
00341    \arg \b Defined value, text string in config file, explanation
00342 
00343    \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened,
00344    \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen,
00345    \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen,
00346    \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number,
00347    \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened,
00348    \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen,
00349    \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen,
00350    \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number,
00351 
00352    \par References
00353    \arg \ref callerid.h Definitions
00354    \arg \ref callerid.c Functions
00355    \arg \ref CID Caller ID names and numbers
00356 */
00357 
00358 
00359 #endif /* _ASTERISK_CALLERID_H */