include/asterisk/callerid.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2005, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief CallerID (and other GR30) management and generation
  21  * Includes code and algorithms from the Zapata library.
  22  *
  23  */
  24
  25 /*!
  26  * \page CID Caller ID names and numbers
  27  *
  28  * Caller ID names are currently 8 bit characters, propably
  29  * ISO8859-1, depending on what your channel drivers handle.
  30  *
  31  * IAX2 and SIP caller ID names are UTF8
  32  * On ISDN Caller ID names are 7 bit, Almost ASCII
  33  * (See http://www.zytrax.com/tech/ia5.html )
  34  *
  35  * \note Asterisk does not currently support SIP utf8 caller ID names or caller ID's.
  36  *
  37  * \par See also
  38  *      \arg \ref callerid.c
  39  *      \arg \ref callerid.h
  40  *      \arg \ref Def_CallerPres
  41  */
  42
  43 #ifndef _ASTERISK_CALLERID_H
  44 #define _ASTERISK_CALLERID_H
  45
  46 #define MAX_CALLERID_SIZE 32000
  47
  48 #define CID_PRIVATE_NAME                (1 << 0)
  49 #define CID_PRIVATE_NUMBER              (1 << 1)
  50 #define CID_UNKNOWN_NAME                (1 << 2)
  51 #define CID_UNKNOWN_NUMBER              (1 << 3)
  52
  53 #define CID_SIG_BELL    1
  54 #define CID_SIG_V23     2
  55 #define CID_SIG_DTMF    3
  56 #define CID_SIG_V23_JP  4
  57 #ifdef WITH_SMDI
  58 #define CID_SIG_SMDI    5
  59 #endif
  60
  61 #define CID_START_RING  1
  62 #define CID_START_POLARITY 2
  63
  64
  65 #define AST_LIN2X(a) ((codec == AST_FORMAT_ALAW) ? (AST_LIN2A(a)) : (AST_LIN2MU(a)))
  66 #define AST_XLAW(a) ((codec == AST_FORMAT_ALAW) ? (AST_ALAW(a)) : (AST_MULAW(a)))
  67
  68
  69 struct callerid_state;
  70 typedef struct callerid_state CIDSTATE;
  71
  72 /*! \brief CallerID Initialization
  73  * \par
  74  * Initializes the callerid system.  Mostly stuff for inverse FFT
  75  */
  76 extern void callerid_init(void);
  77
  78 /*! \brief Generates a CallerID FSK stream in ulaw format suitable for transmission.
  79  * \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.
  80  * \param number Use NULL for no number or "P" for "private"
  81  * \param name name to be used
  82  * \param flags passed flags
  83  * \param callwaiting callwaiting flag
  84  * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW
  85  * This function creates a stream of callerid (a callerid spill) data in ulaw format.
  86  * \return It returns the size
  87  * (in bytes) of the data (if it returns a size of 0, there is probably an error)
  88 */
  89 extern int callerid_generate(unsigned char *buf, char *number, char *name, int flags, int callwaiting, int codec);
  90
  91 /*! \brief Create a callerID state machine
  92  * \param cid_signalling Type of signalling in use
  93  *
  94  * This function returns a malloc'd instance of the callerid_state data structure.
  95  * \return Returns a pointer to a malloc'd callerid_state structure, or NULL on error.
  96  */
  97 extern struct callerid_state *callerid_new(int cid_signalling);
  98
  99 /*! \brief Read samples into the state machine.
 100  * \param cid Which state machine to act upon
 101  * \param ubuf containing your samples
 102  * \param samples number of samples contained within the buffer.
 103  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
 104  *
 105  * Send received audio to the Caller*ID demodulator.
 106  * \return Returns -1 on error, 0 for "needs more samples",
 107  * and 1 if the CallerID spill reception is complete.
 108  */
 109 extern int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
 110
 111 /*! \brief Read samples into the state machine.
 112  * \param cid Which state machine to act upon
 113  * \param ubuf containing your samples
 114  * \param samples number of samples contained within the buffer.
 115  * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
 116  *
 117  * Send received audio to the Caller*ID demodulator (for japanese style lines).
 118  * \return Returns -1 on error, 0 for "needs more samples",
 119  * and 1 if the CallerID spill reception is complete.
 120  */
 121 extern int callerid_feed_jp(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec);
 122
 123 /*! \brief Extract info out of callerID state machine.  Flags are listed above
 124  * \param cid Callerid state machine to act upon
 125  * \param number Pass the address of a pointer-to-char (will contain the phone number)
 126  * \param name Pass the address of a pointer-to-char (will contain the name)
 127  * \param flags Pass the address of an int variable(will contain the various callerid flags)
 128  *
 129  * This function extracts a callerid string out of a callerid_state state machine.
 130  * If no number is found, *number will be set to NULL.  Likewise for the name.
 131  * Flags can contain any of the following:
 132  *
 133  * \return Returns nothing.
 134  */
 135 void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags);
 136
 137 /*! Get and parse DTMF-based callerid  */
 138 /*!
 139  * \param cidstring The actual transmitted string.
 140  * \param number The cid number is returned here.
 141  * \param flags The cid flags are returned here.
 142  * This function parses DTMF callerid.
 143  */
 144 void callerid_get_dtmf(char *cidstring, char *number, int *flags);
 145
 146 /*! \brief Free a callerID state
 147  * \param cid This is the callerid_state state machine to free
 148  * This function frees callerid_state cid.
 149  */
 150 extern void callerid_free(struct callerid_state *cid);
 151
 152 /*! \brief Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format)
 153  * \param buf buffer for output samples. See callerid_generate() for details regarding buffer.
 154  * \param name Caller-ID Name
 155  * \param number Caller-ID Number
 156  * \param codec Asterisk codec (either AST_FORMAT_ALAW or AST_FORMAT_ULAW)
 157  *
 158  * Acts like callerid_generate except uses an asterisk format callerid string.
 159  */
 160 extern int ast_callerid_generate(unsigned char *buf, char *name, char *number, int codec);
 161
 162 /*! \brief Generate message waiting indicator  (stutter tone) */
 163 extern int vmwi_generate(unsigned char *buf, int active, int mdmf, int codec);
 164
 165 /*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm)
 166  * See ast_callerid_generate() for other details
 167  */
 168 extern int ast_callerid_callwaiting_generate(unsigned char *buf, char *name, char *number, int codec);
 169
 170 /*! \brief Destructively parse inbuf into name and location (or number)
 171  * Parses callerid stream from inbuf and changes into useable form, outputed in name and location.
 172  * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed.
 173  * \param name address of a pointer-to-char for the name value of the stream.
 174  * \param location address of a pointer-to-char for the phone number value of the stream.
 175  * \return Returns 0 on success, -1 on failure.
 176  */
 177 extern int ast_callerid_parse(char *instr, char **name, char **location);
 178
 179 /*! Generate a CAS (CPE Alert Signal) tone for 'n' samples */
 180 /*!
 181  * \param outbuf Allocated buffer for data.  Must be at least 2400 bytes unless no SAS is desired
 182  * \param sas Non-zero if CAS should be preceeded by SAS
 183  * \param len How many samples to generate.
 184  * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
 185  * \return Returns -1 on error (if len is less than 2400), 0 on success.
 186  */
 187 extern int ast_gen_cas(unsigned char *outbuf, int sas, int len, int codec);
 188
 189 /*! \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... */
 190 /*!
 191  * \param n The number to be stripped/shrunk
 192  * \return Returns nothing important
 193  */
 194 extern void ast_shrink_phone_number(char *n);
 195
 196 /*! \brief Check if a string consists only of digits.
 197     \param n number to be checked.
 198     \return Returns 0 if n is a number, 1 if it's not.
 199  */
 200 extern int ast_isphonenumber(char *n);
 201
 202 extern int ast_callerid_split(const char *src, char *name, int namelen, char *num, int numlen);
 203
 204 extern char *ast_callerid_merge(char *buf, int bufsiz, const char *name, const char *num, const char *unknown);
 205
 206 /*
 207  * Caller*ID and other GR-30 compatible generation
 208  * routines (used by ADSI for example)
 209  */
 210
 211 extern float cid_dr[4];
 212 extern float cid_di[4];
 213 extern float clidsb;
 214
 215 static inline float callerid_getcarrier(float *cr, float *ci, int bit)
 216 {
 217         /* Move along.  There's nothing to see here... */
 218         float t;
 219         t = *cr * cid_dr[bit] - *ci * cid_di[bit];
 220         *ci = *cr * cid_di[bit] + *ci * cid_dr[bit];
 221         *cr = t;
 222
 223         t = 2.0 - (*cr * *cr + *ci * *ci);
 224         *cr *= t;
 225         *ci *= t;
 226         return *cr;
 227 }
 228
 229 #define PUT_BYTE(a) do { \
 230         *(buf++) = (a); \
 231         bytes++; \
 232 } while(0)
 233
 234 #define PUT_AUDIO_SAMPLE(y) do { \
 235         int index = (short)(rint(8192.0 * (y))); \
 236         *(buf++) = AST_LIN2X(index); \
 237         bytes++; \
 238 } while(0)
 239
 240 #define PUT_CLID_MARKMS do { \
 241         int x; \
 242         for (x=0;x<8;x++) \
 243                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, 1)); \
 244 } while(0)
 245
 246 #define PUT_CLID_BAUD(bit) do { \
 247         while(scont < clidsb) { \
 248                 PUT_AUDIO_SAMPLE(callerid_getcarrier(&cr, &ci, bit)); \
 249                 scont += 1.0; \
 250         } \
 251         scont -= clidsb; \
 252 } while(0)
 253
 254
 255 #define PUT_CLID(byte) do { \
 256         int z; \
 257         unsigned char b = (byte); \
 258         PUT_CLID_BAUD(0);       /* Start bit */ \
 259         for (z=0;z<8;z++) { \
 260                 PUT_CLID_BAUD(b & 1); \
 261                 b >>= 1; \
 262         } \
 263         PUT_CLID_BAUD(1);       /* Stop bit */ \
 264 } while(0);
 265
 266 /* Various defines and bits for handling PRI- and SS7-type restriction */
 267
 268 #define AST_PRES_NUMBER_TYPE                            0x03
 269 #define AST_PRES_USER_NUMBER_UNSCREENED                 0x00
 270 #define AST_PRES_USER_NUMBER_PASSED_SCREEN              0x01
 271 #define AST_PRES_USER_NUMBER_FAILED_SCREEN              0x02
 272 #define AST_PRES_NETWORK_NUMBER                         0x03
 273
 274 #define AST_PRES_RESTRICTION                            0x60
 275 #define AST_PRES_ALLOWED                                0x00
 276 #define AST_PRES_RESTRICTED                             0x20
 277 #define AST_PRES_UNAVAILABLE                            0x40
 278 #define AST_PRES_RESERVED                               0x60
 279
 280 #define AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED \
 281         AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_ALLOWED
 282
 283 #define AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN \
 284         AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_ALLOWED
 285
 286 #define AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN \
 287         AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_ALLOWED
 288
 289 #define AST_PRES_ALLOWED_NETWORK_NUMBER \
 290         AST_PRES_NETWORK_NUMBER + AST_PRES_ALLOWED
 291
 292 #define AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED \
 293         AST_PRES_USER_NUMBER_UNSCREENED + AST_PRES_RESTRICTED
 294
 295 #define AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN \
 296         AST_PRES_USER_NUMBER_PASSED_SCREEN + AST_PRES_RESTRICTED
 297
 298 #define AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN \
 299         AST_PRES_USER_NUMBER_FAILED_SCREEN + AST_PRES_RESTRICTED
 300
 301 #define AST_PRES_PROHIB_NETWORK_NUMBER \
 302         AST_PRES_NETWORK_NUMBER + AST_PRES_RESTRICTED
 303
 304 #define AST_PRES_NUMBER_NOT_AVAILABLE \
 305         AST_PRES_NETWORK_NUMBER + AST_PRES_UNAVAILABLE
 306
 307 int ast_parse_caller_presentation(const char *data);
 308 const char *ast_describe_caller_presentation(int data);
 309
 310 /*! \page Def_CallerPres Caller ID Presentation
 311
 312         Caller ID presentation values are used to set properties to a
 313         caller ID in PSTN networks, and as RPID value in SIP transactions.
 314
 315         The following values are available to use:
 316         \arg \b Defined value, text string in config file, explanation
 317
 318         \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened,
 319         \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen,
 320         \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen,
 321         \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number,
 322         \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened,
 323         \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen,
 324         \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen,
 325         \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number,
 326
 327         \par References
 328         \arg \ref callerid.h Definitions
 329         \arg \ref callerid.c Functions
 330         \arg \ref CID Caller ID names and numbers
 331 */
 332
 333
 334 #endif /* _ASTERISK_CALLERID_H */