Fri May 26 01:45:29 2006

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

Generated on Fri May 26 01:45:29 2006 for Asterisk - the Open Source PBX by  doxygen 1.4.6