diff options
Diffstat (limited to 'include/asterisk/callerid.h')
| -rwxr-xr-x | include/asterisk/callerid.h | 91 |
1 files changed, 57 insertions, 34 deletions
diff --git a/include/asterisk/callerid.h b/include/asterisk/callerid.h index 094a22c92..45ff8b057 100755 --- a/include/asterisk/callerid.h +++ b/include/asterisk/callerid.h @@ -17,8 +17,15 @@ */ /*! \file - * \brief CallerID (and other GR30) Generation support + * \brief CallerID (and other GR30) management and generation * Includes code and algorithms from the Zapata library. + * Caller ID names are currently 8 bit characters, propably + * ISO8859-1, depending on what your channel drivers handle. + * \note Asterisk does not currently support SIP utf8 caller ID names or caller ID's. + * + * \par See also + * \arg \ref callerid.c + * \arg \ref Def_CallerPres */ #ifndef _ASTERISK_CALLERID_H @@ -46,49 +53,46 @@ struct callerid_state; typedef struct callerid_state CIDSTATE; -/*! CallerID Initialization */ -/*! +/*! \brief CallerID Initialization + * \par * Initializes the callerid system. Mostly stuff for inverse FFT */ extern void callerid_init(void); -/*! Generates a CallerID FSK stream in ulaw format suitable for transmission. */ -/*! +/*! \brief Generates a CallerID FSK stream in ulaw format suitable for transmission. * \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. * \param number Use NULL for no number or "P" for "private" * \param name name to be used * \param flags passed flags * \param callwaiting callwaiting flag * \param codec -- either AST_FORMAT_ULAW or AST_FORMAT_ALAW - * This function creates a stream of callerid (a callerid spill) data in ulaw format. It returns the size + * This function creates a stream of callerid (a callerid spill) data in ulaw format. + * \return It returns the size * (in bytes) of the data (if it returns a size of 0, there is probably an error) */ extern int callerid_generate(unsigned char *buf, char *number, char *name, int flags, int callwaiting, int codec); -/*! Create a callerID state machine */ -/*! +/*! \brief Create a callerID state machine * \param cid_signalling Type of signalling in use * * This function returns a malloc'd instance of the callerid_state data structure. - * Returns a pointer to a malloc'd callerid_state structure, or NULL on error. + * \return Returns a pointer to a malloc'd callerid_state structure, or NULL on error. */ extern struct callerid_state *callerid_new(int cid_signalling); -/*! Read samples into the state machine. */ -/*! +/*! \brief Read samples into the state machine. * \param cid Which state machine to act upon * \param ubuf containing your samples * \param samples number of samples contained within the buffer. * \param codec which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW) * * Send received audio to the Caller*ID demodulator. - * Returns -1 on error, 0 for "needs more samples", + * \return Returns -1 on error, 0 for "needs more samples", * and 1 if the CallerID spill reception is complete. */ extern int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int samples, int codec); -/*! Extract info out of callerID state machine. Flags are listed above */ -/*! +/*! \brief Extract info out of callerID state machine. Flags are listed above * \param cid Callerid state machine to act upon * \param number Pass the address of a pointer-to-char (will contain the phone number) * \param name Pass the address of a pointer-to-char (will contain the name) @@ -98,7 +102,7 @@ extern int callerid_feed(struct callerid_state *cid, unsigned char *ubuf, int sa * If no number is found, *number will be set to NULL. Likewise for the name. * Flags can contain any of the following: * - * Returns nothing. + * \return Returns nothing. */ void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags); @@ -111,15 +115,13 @@ void callerid_get(struct callerid_state *cid, char **number, char **name, int *f */ void callerid_get_dtmf(char *cidstring, char *number, int *flags); -/*! Free a callerID state */ -/*! +/*! \brief Free a callerID state * \param cid This is the callerid_state state machine to free * This function frees callerid_state cid. */ extern void callerid_free(struct callerid_state *cid); -/*! Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format) */ -/*! +/*! \brief Generate Caller-ID spill from the "callerid" field of asterisk (in e-mail address like format) * \param buf buffer for output samples. See callerid_generate() for details regarding buffer. * \param name Caller-ID Name * \param number Caller-ID Number @@ -129,22 +131,20 @@ extern void callerid_free(struct callerid_state *cid); */ extern int ast_callerid_generate(unsigned char *buf, char *name, char *number, int codec); -/*! Generate message waiting indicator */ +/*! \brief Generate message waiting indicator (stutter tone) */ extern int vmwi_generate(unsigned char *buf, int active, int mdmf, int codec); -/*! Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm) */ -/*! - * See ast_callerid_generate for other details +/*! \brief Generate Caller-ID spill but in a format suitable for Call Waiting(tm)'s Caller*ID(tm) + * See ast_callerid_generate() for other details */ extern int ast_callerid_callwaiting_generate(unsigned char *buf, char *name, char *number, int codec); -/*! Destructively parse inbuf into name and location (or number) */ -/*! +/*! \brief Destructively parse inbuf into name and location (or number) + * Parses callerid stream from inbuf and changes into useable form, outputed in name and location. * \param instr buffer of callerid stream (in audio form) to be parsed. Warning, data in buffer is changed. * \param name address of a pointer-to-char for the name value of the stream. * \param location address of a pointer-to-char for the phone number value of the stream. - * Parses callerid stream from inbuf and changes into useable form, outputed in name and location. - * Returns 0 on success, -1 on failure. + * \return Returns 0 on success, -1 on failure. */ extern int ast_callerid_parse(char *instr, char **name, char **location); @@ -154,21 +154,20 @@ extern int ast_callerid_parse(char *instr, char **name, char **location); * \param sas Non-zero if CAS should be preceeded by SAS * \param len How many samples to generate. * \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW) - * Returns -1 on error (if len is less than 2400), 0 on success. + * \return Returns -1 on error (if len is less than 2400), 0 on success. */ extern int ast_gen_cas(unsigned char *outbuf, int sas, int len, int codec); -/*! Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... */ +/*! \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s... */ /*! * \param n The number to be stripped/shrunk - * Returns nothing important + * \return Returns nothing important */ extern void ast_shrink_phone_number(char *n); -/*! Check if a string consists only of digits. Returns non-zero if so */ -/*! - * \param n number to be checked. - * Returns 0 if n is a number, 1 if it's not. +/*! \brief Check if a string consists only of digits. + \param n number to be checked. + \return Returns 0 if n is a number, 1 if it's not. */ extern int ast_isphonenumber(char *n); @@ -280,4 +279,28 @@ static inline float callerid_getcarrier(float *cr, float *ci, int bit) int ast_parse_caller_presentation(const char *data); const char *ast_describe_caller_presentation(int data); +/*! \page Def_CallerPres Caller ID Presentation + + Caller ID presentation values are used to set properties to a + caller ID in PSTN networks, and as RPID value in SIP transactions. + + The following values are available to use: + \arg \b Defined value, text string in config file, explanation + . + + \arg \b AST_PRES_ALLOWED_USER_NUMBER_NOT_SCREENED, "allowed_not_screened", Presentation Allowed, Not Screened, + \arg \b AST_PRES_ALLOWED_USER_NUMBER_PASSED_SCREEN, "allowed_passed_screen", Presentation Allowed, Passed Screen, + \arg \b AST_PRES_ALLOWED_USER_NUMBER_FAILED_SCREEN, "allowed_failed_screen", Presentation Allowed, Failed Screen, + \arg \b AST_PRES_ALLOWED_NETWORK_NUMBER, "allowed", Presentation Allowed, Network Number, + \arg \b AST_PRES_PROHIB_USER_NUMBER_NOT_SCREENED, "prohib_not_screened", Presentation Prohibited, Not Screened, + \arg \b AST_PRES_PROHIB_USER_NUMBER_PASSED_SCREEN, "prohib_passed_screen", Presentation Prohibited, Passed Screen, + \arg \b AST_PRES_PROHIB_USER_NUMBER_FAILED_SCREEN, "prohib_failed_screen", Presentation Prohibited, Failed Screen, + \arg \b AST_PRES_PROHIB_NETWORK_NUMBER, "prohib", Presentation Prohibited, Network Number, + + \par References + \arg \ref callerid.h Definitions + \arg \ref callerid.c Functions +*/ + + #endif /* _ASTERISK_CALLERID_H */ |