Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:49 2009

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