[Asterisk-cvs] asterisk/include/asterisk app.h, 1.43,
1.44 callerid.h, 1.15, 1.16 channel.h, 1.113, 1.114 doxyref.h,
1.3, 1.4 frame.h, 1.62, 1.63 fskmodem.h, 1.3, 1.4
russell
russell
Sun Nov 6 10:18:32 CST 2005
Update of /usr/cvsroot/asterisk/include/asterisk
In directory mongoose.digium.com:/tmp/cvs-serv2786/include/asterisk
Modified Files:
app.h callerid.h channel.h doxyref.h frame.h fskmodem.h
Log Message:
issue #5605
Index: app.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/app.h,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -d -r1.43 -r1.44
--- app.h 6 Nov 2005 04:39:52 -0000 1.43
+++ app.h 6 Nov 2005 15:09:47 -0000 1.44
@@ -29,46 +29,46 @@
/* IVR stuff */
-/* Callback function for IVR, returns 0 on completion, -1 on hangup or digit if
- interrupted */
+/*! \brief Callback function for IVR
+ \return returns 0 on completion, -1 on hangup or digit if interrupted
+ */
typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);
typedef enum {
- AST_ACTION_UPONE, /* adata is unused */
- AST_ACTION_EXIT, /* adata is the return value for ast_ivr_menu_run if channel was not hungup */
- AST_ACTION_CALLBACK, /* adata is an ast_ivr_callback */
- AST_ACTION_PLAYBACK, /* adata is file to play */
- AST_ACTION_BACKGROUND, /* adata is file to play */
- AST_ACTION_PLAYLIST, /* adata is list of files, separated by ; to play */
- AST_ACTION_MENU, /* adata is a pointer to an ast_ivr_menu */
- AST_ACTION_REPEAT, /* adata is max # of repeats, cast to a pointer */
- AST_ACTION_RESTART, /* adata is like repeat, but resets repeats to 0 */
- AST_ACTION_TRANSFER, /* adata is a string with exten[@context] */
- AST_ACTION_WAITOPTION, /* adata is a timeout, or 0 for defaults */
- AST_ACTION_NOOP, /* adata is unused */
- AST_ACTION_BACKLIST, /* adata is list of files separated by ; allows interruption */
+ AST_ACTION_UPONE, /*!< adata is unused */
+ AST_ACTION_EXIT, /*!< adata is the return value for ast_ivr_menu_run if channel was not hungup */
+ AST_ACTION_CALLBACK, /*!< adata is an ast_ivr_callback */
+ AST_ACTION_PLAYBACK, /*!< adata is file to play */
+ AST_ACTION_BACKGROUND, /*!< adata is file to play */
+ AST_ACTION_PLAYLIST, /*!< adata is list of files, separated by ; to play */
+ AST_ACTION_MENU, /*!< adata is a pointer to an ast_ivr_menu */
+ AST_ACTION_REPEAT, /*!< adata is max # of repeats, cast to a pointer */
+ AST_ACTION_RESTART, /*!< adata is like repeat, but resets repeats to 0 */
+ AST_ACTION_TRANSFER, /*!< adata is a string with exten[@context] */
+ AST_ACTION_WAITOPTION, /*!< adata is a timeout, or 0 for defaults */
+ AST_ACTION_NOOP, /*!< adata is unused */
+ AST_ACTION_BACKLIST, /*!< adata is list of files separated by ; allows interruption */
} ast_ivr_action;
+/*!
+ Special "options" are:
+ \arg "s" - "start here (one time greeting)"
+ \arg "g" - "greeting/instructions"
+ \arg "t" - "timeout"
+ \arg "h" - "hangup"
+ \arg "i" - "invalid selection"
+
+*/
struct ast_ivr_option {
char *option;
ast_ivr_action action;
void *adata;
};
-/*
- Special "options" are:
- "s" - "start here (one time greeting)"
- "g" - "greeting/instructions"
- "t" - "timeout"
- "h" - "hangup"
- "i" - "invalid selection"
-
-*/
-
struct ast_ivr_menu {
- char *title; /* Title of menu */
- unsigned int flags; /* Flags */
- struct ast_ivr_option *options; /* All options */
+ char *title; /*!< Title of menu */
+ unsigned int flags; /*!< Flags */
+ struct ast_ivr_option *options; /*!< All options */
};
#define AST_IVR_FLAG_AUTORESTART (1 << 0)
@@ -78,11 +78,11 @@
static struct ast_ivr_menu holder = { title, flags, __options_##holder }
-/*! Runs an IVR menu, returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
+/*! \brief Runs an IVR menu
+ \return returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
extern int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);
-/*! Plays a stream and gets DTMF data from a channel */
-/*!
+/*! \brief Plays a stream and gets DTMF data from a channel
* \param c Which channel one is interacting with
* \param prompt File to pass to ast_streamfile (the one that you wish to play)
* \param s The location where the DTMF data will be stored
@@ -96,7 +96,7 @@
*/
extern int ast_app_getdata(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout);
-/* Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
+/*! \brief Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
extern int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
/*! Record voice (after playing prompt if specified), waiting for silence (in ms) up to a given timeout (in s) or '#' */
@@ -113,7 +113,9 @@
/*! Determine number of new/old messages in a mailbox */
int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs);
-/*! Safely spawn an external program while closingn file descriptors */
+/*! Safely spawn an external program while closing file descriptors
+ \note This replaces the \b system call in all Asterisk modules
+*/
extern int ast_safe_system(const char *s);
/*! Send DTMF to chan (optionally entertain peer) */
@@ -128,13 +130,18 @@
/*! Play a stream and wait for a digit, returning the digit that was pressed */
int ast_play_and_wait(struct ast_channel *chan, const char *fn);
-/*! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum */
-/* permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
+/*! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum
+ \n
+ permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
calls ast_unlock_path() on 'path' if passed */
int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
-/*! Record a message and prepend the message to the given record file after playing the optional playfile (or a beep), storing the duration in 'duration' and with a maximum */
-/* permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. */
+/*! Record a message and prepend the message to the given record file after
+ playing the optional playfile (or a beep), storing the duration in
+ 'duration' and with a maximum
+\n
+ permitted silence time in milliseconds of 'maxsilence' under
+ 'silencethreshold' or use '-1' for either or both parameters for defaults. */
int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
enum AST_LOCK_RESULT {
@@ -144,17 +151,17 @@
AST_LOCK_FAILURE = -3,
};
-/*
+/*!
* \brief Lock a filesystem path.
* \param path the path to be locked
- * \return one of AST_LOCK_RESULT values
+ * \return one of \ref AST_LOCK_RESULT values
*/
enum AST_LOCK_RESULT ast_lock_path(const char *path);
-/* Unlock a path */
+/*! Unlock a path */
int ast_unlock_path(const char *path);
-/*Read a file into asterisk*/
+/*! Read a file into asterisk*/
char *ast_read_textfile(const char *file);
#define GROUP_CATEGORY_PREFIX "GROUP"
@@ -188,7 +195,7 @@
argc argument counter. The arguments must be declared using AST_APP_ARG,
and they will all be character pointers (strings).
- Note: The structure is <b>not</b> initialized, as the call to
+ \note The structure is <b>not</b> initialized, as the call to
ast_separate_app_args() will perform that function before parsing
the arguments.
*/
@@ -329,7 +336,9 @@
*/
int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr);
-/*! Present a dialtone and collect a certain length extension. Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension. Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
+/*! \brief Present a dialtone and collect a certain length extension.
+ \return Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension.
+\note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
/*! Allow to record message and have a review option */
Index: callerid.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/callerid.h,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- callerid.h 26 Oct 2005 23:11:36 -0000 1.15
+++ callerid.h 6 Nov 2005 15:09:47 -0000 1.16
@@ -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 @@
* 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_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 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 @@
* \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 @@
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 */
Index: channel.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/channel.h,v
retrieving revision 1.113
retrieving revision 1.114
diff -u -d -r1.113 -r1.114
--- channel.h 2 Nov 2005 18:08:33 -0000 1.113
+++ channel.h 6 Nov 2005 15:09:47 -0000 1.114
@@ -18,8 +18,71 @@
/*! \file
* \brief General Asterisk PBX channel definitions.
+ * \par See also:
+ * \arg \ref Def_Channel
+ * \arg \ref channel_drivers
*/
+/*! \page Def_Channel Asterisk Channels
+ \par What is a Channel?
+ A phone call through Asterisk consists of an incoming
+ connection and an outbound connection. Each call comes
+ in through a channel driver that supports one technology,
+ like SIP, ZAP, IAX2 etc.
+ \par
+ Each channel driver, technology, has it's own private
+ channel or dialog structure, that is technology-dependent.
+ Each private structure is "owned" by a generic Asterisk
+ channel structure, defined in channel.h and handled by
+ channel.c .
+ \par Call scenario
+ This happens when an incoming call arrives to Asterisk
+ -# Call arrives on a channel driver interface
+ -# Channel driver creates a PBX channel and starts a
+ pbx thread on the channel
+ -# The dial plan is executed
+ -# At this point at least two things can happen:
+ -# The call is answered by Asterisk and
+ Asterisk plays a media stream or reads media
+ -# The dial plan forces Asterisk to create an outbound
+ call somewhere with the dial (see \ref app_dial.c)
+ application
+
+ .
+ \par Bridging channels
+ If Asterisk dials out this happens:
+ -# Dial creates an outbound PBX channel and asks one of the
+ channel drivers to create a call
+ -# When the call is answered, Asterisk bridges the media streams
+ so the caller on the first channel can speak with the callee
+ on the second, outbound channel
+ -# In some cases where we have the same technology on both
+ channels and compatible codecs, a native bridge is used.
+ In a native bridge, the channel driver handles forwarding
+ of incoming audio to the outbound stream internally, without
+ sending audio frames through the PBX.
+ -# In SIP, theres an "external native bridge" where Asterisk
+ redirects the endpoint, so audio flows directly between the
+ caller's phone and the callee's phone. Signalling stays in
+ Asterisk in order to be able to provide a proper CDR record
+ for the call.
+
+
+ \par Masquerading channels
+ In some cases, a channel can masquerade itself into another
+ channel. This happens frequently in call transfers, where
+ a new channel takes over a channel that is already involved
+ in a call. The new channel sneaks in and takes over the bridge
+ and the old channel, now a zombie, is hung up.
+
+ \par Reference
+ \arg channel.c - generic functions
+ \arg channel.h - declarations of functions, flags and structures
+ \arg \ref channel_drivers - Implemented channel drivers
+ \arg \ref Def_Frame Asterisk Multimedia Frames
+
+*/
+
#ifndef _ASTERISK_CHANNEL_H
#define _ASTERISK_CHANNEL_H
@@ -74,6 +137,7 @@
int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
};
+/*! Structure for all kinds of caller ID identifications */
struct ast_callerid {
/*! Malloc'd Dialed Number Identifier */
char *cid_dnid;
@@ -95,7 +159,18 @@
int cid_tns;
};
-/*! Structure to describe a channel "technology" */
+/*! Structure to describe a channel "technology", ie a channel driver
+ See
+ \arg chan_iax2.c - The Inter-Asterisk exchange protocol
+ \arg chan_sip.c - The SIP channel driver
+ \arg chan_zap.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
+
+ If you develop your own channel driver, this is where you
+ tell the PBX at registration of your driver what properties
+ this driver supports and where different callbacks are
+ implemented.
+*/
+
struct ast_channel_tech {
const char * const type;
@@ -107,8 +182,10 @@
/*! Technology Properties */
int properties;
+ /*! Requester - to set up call data structures (pvt's) */
struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
+ /*! Devicestate call back */
int (* const devicestate)(void *data);
/*! Send a literal DTMF digit */
@@ -121,13 +198,13 @@
/*! Hangup (and possibly destroy) the channel */
int (* const hangup)(struct ast_channel *chan);
- /*! Answer the line */
+ /*! Answer the channel */
int (* const answer)(struct ast_channel *chan);
- /*! Read a frame, in standard format */
+ /*! Read a frame, in standard format (see frame.h) */
struct ast_frame * (* const read)(struct ast_channel *chan);
- /*! Write a frame, in standard format */
+ /*! Write a frame, in standard format (see frame.h) */
int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
/*! Display or transmit text */
@@ -158,7 +235,7 @@
/*! Query a given option */
int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
- /*! Blind transfer other side */
+ /*! Blind transfer other side (see app_transfer.c and ast_transfer() */
int (* const transfer)(struct ast_channel *chan, const char *newdest);
/*! Write a frame, in standard format */
@@ -212,20 +289,20 @@
struct ast_channel_spy_list;
-/*! Main Channel structure associated with a channel. */
-/*!
+/*! Main Channel structure associated with a channel.
* This is the side of it mostly used by the pbx and call management.
*/
struct ast_channel {
- /*! ASCII Description of channel name */
+ /*! ASCII unique channel name */
char name[AST_CHANNEL_NAME];
- /*! Technology */
+ /*! Technology (point to channel driver) */
const struct ast_channel_tech *tech;
+
/*! Private data used by the technology driver */
void *tech_pvt;
- /*! Language requested */
+ /*! Language requested for voice prompts */
char language[MAX_LANGUAGE];
/*! Type of channel */
const char *type;
@@ -252,7 +329,7 @@
int cdrflags;
/*! Whether or not we have been hung up... Do not set this value
directly, use ast_softhangup */
- int _softhangup;
+ int _softhangup;
/*! Non-zero, set to actual time when channel is to be hung up */
time_t whentohangup;
/*! If anyone is blocking, this is them */
@@ -275,9 +352,9 @@
int streamid;
/*! Stream itself. */
struct ast_filestream *stream;
- /*! For streaming playback, the schedule ID */
+ /*! For streaming video playback, the schedule ID */
int vstreamid;
- /*! Stream itself. */
+ /*! Video Stream itself. */
struct ast_filestream *vstream;
/*! Original writer format */
int oldwriteformat;
@@ -321,17 +398,17 @@
/*! PBX private structure */
struct ast_pbx *pbx;
/*! Set BEFORE PBX is started to determine AMA flags */
- int amaflags;
+ int amaflags;
/*! Account code for billing */
- char accountcode[AST_MAX_ACCOUNT_CODE];
+ char accountcode[AST_MAX_ACCOUNT_CODE];
/*! Call Detail Record */
struct ast_cdr *cdr;
/*! Whether or not ADSI is detected on CPE */
- int adsicpe;
+ int adsicpe;
/*! Where to forward to if asked to dial on this interface */
char call_forward[AST_MAX_EXTENSION];
- /*! Tone zone */
+ /*! Tone zone as set in indications.conf */
struct tone_zone *zone;
/* Channel monitoring */
@@ -360,7 +437,7 @@
/*! channel flags of AST_FLAG_ type */
unsigned int flags;
- /* ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
+ /*! ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
unsigned short transfercapability;
struct ast_frame *readq;
@@ -381,24 +458,26 @@
struct ast_channel *next;
};
-/* Channel tech properties: */
-/* Channels have this property if they can accept input with jitter; i.e. most VoIP channels */
+/* \defgroup chanprop Channel tech properties:
+ \brief Channels have this property if they can accept input with jitter; i.e. most VoIP channels */
+/* @{ */
#define AST_CHAN_TP_WANTSJITTER (1 << 0)
/* This flag has been deprecated by the transfercapbilty data member in struct ast_channel */
/* #define AST_FLAG_DIGITAL (1 << 0) */ /* if the call is a digital ISDN call */
-#define AST_FLAG_DEFER_DTMF (1 << 1) /* if dtmf should be deferred */
-#define AST_FLAG_WRITE_INT (1 << 2) /* if write should be interrupt generator */
-#define AST_FLAG_BLOCKING (1 << 3) /* if we are blocking */
-#define AST_FLAG_ZOMBIE (1 << 4) /* if we are a zombie */
-#define AST_FLAG_EXCEPTION (1 << 5) /* if there is a pending exception */
-#define AST_FLAG_MOH (1 << 6) /* XXX anthm promises me this will disappear XXX listening to moh */
-#define AST_FLAG_SPYING (1 << 7) /* XXX might also go away XXX is spying on someone */
-#define AST_FLAG_NBRIDGE (1 << 8) /* is it in a native bridge */
-#define AST_FLAG_IN_AUTOLOOP (1 << 9) /* the channel is in an auto-incrementing dialplan processor,
+#define AST_FLAG_DEFER_DTMF (1 << 1) /*!< if dtmf should be deferred */
+#define AST_FLAG_WRITE_INT (1 << 2) /*!< if write should be interrupt generator */
+#define AST_FLAG_BLOCKING (1 << 3) /*!< if we are blocking */
+#define AST_FLAG_ZOMBIE (1 << 4) /*!< if we are a zombie */
+#define AST_FLAG_EXCEPTION (1 << 5) /*!< if there is a pending exception */
+#define AST_FLAG_MOH (1 << 6) /*!< XXX anthm promises me this will disappear XXX listening to moh */
+#define AST_FLAG_SPYING (1 << 7) /*!< XXX might also go away XXX is spying on someone */
+#define AST_FLAG_NBRIDGE (1 << 8) /*!< is it in a native bridge */
+#define AST_FLAG_IN_AUTOLOOP (1 << 9) /*!< the channel is in an auto-incrementing dialplan processor,
so when ->priority is set, it will get incremented before
finding the next priority to run
*/
+/* @} */
#define AST_FEATURE_PLAY_WARNING (1 << 0)
#define AST_FEATURE_REDIRECT (1 << 1)
@@ -457,15 +536,18 @@
#define AST_ADSI_UNAVAILABLE (2)
#define AST_ADSI_OFFHOOKONLY (3)
-#define AST_SOFTHANGUP_DEV (1 << 0) /* Soft hangup by device */
-#define AST_SOFTHANGUP_ASYNCGOTO (1 << 1) /* Soft hangup for async goto */
+#define AST_SOFTHANGUP_DEV (1 << 0) /*!< Soft hangup by device */
+#define AST_SOFTHANGUP_ASYNCGOTO (1 << 1) /*!< Soft hangup for async goto */
#define AST_SOFTHANGUP_SHUTDOWN (1 << 2)
#define AST_SOFTHANGUP_TIMEOUT (1 << 3)
#define AST_SOFTHANGUP_APPUNLOAD (1 << 4)
#define AST_SOFTHANGUP_EXPLICIT (1 << 5)
#define AST_SOFTHANGUP_UNBRIDGE (1 << 6)
-/* Bits 0-15 of state are reserved for the state (up/down) of the line */
+
+/*! \defgroup ChanState Channel states
+\brief Bits 0-15 of state are reserved for the state (up/down) of the line */
+/*! @{ */
/*! Channel is down and available */
#define AST_STATE_DOWN 0
/*! Channel is down, but reserved */
@@ -487,47 +569,52 @@
/*! Channel has detected an incoming call and is waiting for ring */
#define AST_STATE_PRERING 9
-/* Bits 16-32 of state are reserved for flags */
+/* Bits 16-32 of state are reserved for flags (See \ref ChanState ) */
/*! Do not transmit voice data */
#define AST_STATE_MUTE (1 << 16)
+/*! @} */
-/*! Create a channel structure */
-/*! Returns NULL on failure to allocate. New channels are
+/*! \brief Change the state of a channel */
+int ast_setstate(struct ast_channel *chan, int state);
+
+/*! \brief Create a channel structure
+ \return Returns NULL on failure to allocate.
+ \note New channels are
by default set to the "default" context and
extension "s"
*/
struct ast_channel *ast_channel_alloc(int needalertpipe);
-/*! Queue an outgoing frame */
+/*! \brief Queue an outgoing frame */
int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
-/*! Queue a hangup frame */
+/*! \brief Queue a hangup frame */
int ast_queue_hangup(struct ast_channel *chan);
-/*! Queue a control frame */
+/*! \brief Queue a control frame */
int ast_queue_control(struct ast_channel *chan, int control);
-/*! Change the state of a channel */
-int ast_setstate(struct ast_channel *chan, int state);
+/*! \brief Change channel name */
void ast_change_name(struct ast_channel *chan, char *newname);
-/*! Free a channel structure */
+/*! \brief Free a channel structure */
void ast_channel_free(struct ast_channel *);
-/*! Requests a channel */
-/*!
+/*! \brief Requests a channel
* \param type type of channel to request
* \param format requested channel format
* \param data data to pass to the channel requester
* \param status status
* Request a channel of a given type, with data as optional information used
* by the low level module
- * Returns an ast_channel on success, NULL on failure.
+ * \return Returns an ast_channel on success, NULL on failure.
*/
struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
/*!
+ * \brief Request a channel of a given type, with data as optional information used
+ * by the low level module and attempt to place a call on it
* \param type type of channel to request
* \param format requested channel format
* \param data data to pass to the channel requester
@@ -535,71 +622,63 @@
* \param reason why unsuccessful (if unsuceessful)
* \param cidnum Caller-ID Number
* \param cidname Caller-ID Name
- * Request a channel of a given type, with data as optional information used
- * by the low level module and attempt to place a call on it
- * Returns an ast_channel on success or no answer, NULL on failure. Check the value of chan->_state
+ * \return Returns an ast_channel on success or no answer, NULL on failure. Check the value of chan->_state
* to know if the call was answered or not.
*/
struct ast_channel *ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname);
struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname, struct outgoing_helper *oh);
-/*! Register a channel technology */
-/*!
- * \param tech Structure defining channel technology or "type"
+/*!\brief Register a channel technology (a new channel driver)
* Called by a channel module to register the kind of channels it supports.
- * Returns 0 on success, -1 on failure.
+ * \param tech Structure defining channel technology or "type"
+ * \return Returns 0 on success, -1 on failure.
*/
int ast_channel_register(const struct ast_channel_tech *tech);
-/*! Unregister a channel technology */
-/*
+/*! \brief Unregister a channel technology
* \param tech Structure defining channel technology or "type" that was previously registered
- * No return value.
+ * \return No return value.
*/
void ast_channel_unregister(const struct ast_channel_tech *tech);
-/*! Get a channel technology structure by name
+/*! \brief Get a channel technology structure by name
* \param name name of technology to find
* \return a pointer to the structure, or NULL if no matching technology found
*/
const struct ast_channel_tech *ast_get_channel_tech(const char *name);
-/*! Hang up a channel */
-/*!
- * \param chan channel to hang up
- * This function performs a hard hangup on a channel. Unlike the soft-hangup, this function
+/*! \brief Hang up a channel
+ * \note This function performs a hard hangup on a channel. Unlike the soft-hangup, this function
* performs all stream stopping, etc, on the channel that needs to end.
* chan is no longer valid after this call.
- * Returns 0 on success, -1 on failure.
+ * \param chan channel to hang up
+ * \return Returns 0 on success, -1 on failure.
*/
int ast_hangup(struct ast_channel *chan);
-/*! Softly hangup up a channel */
-/*!
+/*! \brief Softly hangup up a channel
* \param chan channel to be soft-hung-up
* Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
* safely hangup a channel managed by another thread.
* \param cause Ast hangupcause for hangup
- * Returns 0 regardless
+ * \return Returns 0 regardless
*/
int ast_softhangup(struct ast_channel *chan, int cause);
-/*! Softly hangup up a channel (no channel lock)
+/*! \brief Softly hangup up a channel (no channel lock)
* \param chan channel to be soft-hung-up
- * \param cause Ast hangupcause for hangup */
+ * \param cause Ast hangupcause for hangup (see cause.h) */
int ast_softhangup_nolock(struct ast_channel *chan, int cause);
-/*! Check to see if a channel is needing hang up */
-/*!
+/*! \brief Check to see if a channel is needing hang up
* \param chan channel on which to check for hang up
* This function determines if the channel is being requested to be hung up.
- * Returns 0 if not, or 1 if hang up is requested (including time-out).
+ * \return Returns 0 if not, or 1 if hang up is requested (including time-out).
*/
int ast_check_hangup(struct ast_channel *chan);
-/*! Compare a offset with the settings of when to hang a channel up */
-/*!
+/*! \brief Compare a offset with the settings of when to hang a channel up
* \param chan channel on which to check for hang up
* \param offset offset in seconds from current time
* \return 1, 0, or -1
@@ -610,77 +689,69 @@
*/
int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset);
-/*! Set when to hang a channel up */
-/*!
+/*! \brief Set when to hang a channel up
* \param chan channel on which to check for hang up
* \param offset offset in seconds from current time of when to hang up
* This function sets the absolute time out on a channel (when to hang up).
*/
void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
-/*! Answer a ringing call */
-/*!
+/*! \brief Answer a ringing call
* \param chan channel to answer
* This function answers a channel and handles all necessary call
* setup functions.
- * Returns 0 on success, -1 on failure
+ * \return Returns 0 on success, -1 on failure
*/
int ast_answer(struct ast_channel *chan);
-/*! Make a call */
-/*!
+/*! \brief Make a call
* \param chan which channel to make the call on
* \param addr destination of the call
* \param timeout time to wait on for connect
- * Place a call, take no longer than timeout ms. Returns -1 on failure,
- 0 on not enough time (does not auto matically stop ringing), and
+ * Place a call, take no longer than timeout ms.
+ \return Returns -1 on failure, 0 on not enough time
+ (does not automatically stop ringing), and
the number of seconds the connect took otherwise.
- Returns 0 on success, -1 on failure
*/
int ast_call(struct ast_channel *chan, char *addr, int timeout);
-/*! Indicates condition of channel */
-/*!
+/*! \brief Indicates condition of channel
+ * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
* \param chan channel to change the indication
* \param condition which condition to indicate on the channel
- * Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
- * Returns 0 on success, -1 on failure
+ * \return Returns 0 on success, -1 on failure
*/
int ast_indicate(struct ast_channel *chan, int condition);
-/* Misc stuff */
+/* Misc stuff ------------------------------------------------ */
-/*! Wait for input on a channel */
-/*!
+/*! \brief Wait for input on a channel
* \param chan channel to wait on
* \param ms length of time to wait on the channel
* Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
- Returns < 0 on failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
+ \return Returns < 0 on failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
int ast_waitfor(struct ast_channel *chan, int ms);
-/*! Wait for a specied amount of time, looking for hangups */
-/*!
+/*! \brief Wait for a specied amount of time, looking for hangups
* \param chan channel to wait for
* \param ms length of time in milliseconds to sleep
* Waits for a specified amount of time, servicing the channel as required.
- * returns -1 on hangup, otherwise 0.
+ * \return returns -1 on hangup, otherwise 0.
*/
int ast_safe_sleep(struct ast_channel *chan, int ms);
-/*! Wait for a specied amount of time, looking for hangups and a condition argument */
-/*!
+/*! \brief Wait for a specied amount of time, looking for hangups and a condition argument
* \param chan channel to wait for
* \param ms length of time in milliseconds to sleep
* \param cond a function pointer for testing continue condition
* \param data argument to be passed to the condition test function
+ * \return returns -1 on hangup, otherwise 0.
* Waits for a specified amount of time, servicing the channel as required. If cond
* returns 0, this function returns.
- * returns -1 on hangup, otherwise 0.
*/
int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
-/*! Waits for activity on a group of channels */
-/*!
+/*! \brief Waits for activity on a group of channels
* \param chan an array of pointers to channels
* \param n number of channels that are to be waited upon
* \param fds an array of fds to wait upon
@@ -689,7 +760,8 @@
* \param outfd fd that had activity on it
* \param ms how long the wait was
* Big momma function here. Wait for activity on any of the n channels, or any of the nfds
- file descriptors. Returns the channel with activity, or NULL on error or if an FD
+ file descriptors.
+ \return Returns the channel with activity, or NULL on error or if an FD
came first. If the FD came first, it will be returned in outfd, otherwise, outfd
will be -1 */
struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
@@ -1163,8 +1235,7 @@
}
#endif
-/*! Waits for activity on a group of channels */
-/*!
+/*! \brief Waits for activity on a group of channels
* \param nfds the maximum number of file descriptors in the sets
* \param rfds file descriptors to check for read availability
* \param wfds file descriptors to check for write availability
Index: doxyref.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/doxyref.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- doxyref.h 26 Oct 2005 23:11:36 -0000 1.3
+++ doxyref.h 6 Nov 2005 15:09:47 -0000 1.4
@@ -25,26 +25,30 @@
* system.
*/
/*! \page DevDoc Asterisk Developer's Documentation - appendices
- * \arg \ref CodeGuide
+ * \arg \ref CodeGuide : The must-read document for all developer's
* \arg \ref AstAPI
- * \arg \ref AstDebug
- * \arg \ref AstAMI
- * \arg \ref AstARA
- * \arg \ref AstDUNDi
+ * \arg \ref Def_Channel : What's a channel, anyway?
+ * \arg \ref channel_drivers : Existing channel drivers
+ * \arg \ref AstDebug : Hints on debugging
+ * \arg \ref AstAMI : The Call management socket API
+ * \arg \ref AstARA : A generic data storage and retrieval API for Asterisk
+ * \arg \ref AstDUNDi : A way to find phone services dynamically by using the DUNDi protocol
* \arg \ref AstCDR
* \arg \ref AstREADME
- * \arg \ref AstCREDITS
* \arg \ref AstVar
- * \arg \ref AstENUM
+ * \arg \ref AstENUM : The IETF way to redirect from phone numbers to VoIP calls
* \arg \ref ConfigFiles
- * \arg \ref SoundFiles
- * \section wwwsites Web sites
- * \arg Main: Asterisk Developer's website http://www.asterisk.org/developers/
- * \arg Bugs: The Issue tracker http://bugs.digium.com
- * \arg Lists: List server http://lists.digium.com
- * \arg Wiki: The Asterisk Wiki http://www.voip-info.org
- * \arg Docs: The Asterisk Documentation Project http://www.asteriskdocs.org
- * \arg Digium: The Asterisk company http://www.digium.com
+ * \arg \ref SoundFiles included in the Asterisk distribution
+ * \arg \ref AstCREDITS : A Thank You to contributors
+ \n\n
+ * \section weblinks Web sites
+ * \arg \b Main: Asterisk Developer's website http://www.asterisk.org/developers/
+ * \arg \b Bugs: The Issue tracker http://bugs.digium.com
+ * \arg \b Lists: List server http://lists.digium.com
+ * \arg \b Wiki: The Asterisk Wiki http://www.voip-info.org
+ * \arg \b Docs: The Asterisk Documentation Project http://www.asteriskdocs.org
+ * \arg \b Digium: The Asterisk company http://www.digium.com
+ *
*/
/*! \page CodeGuide Coding Guidelines
@@ -56,10 +60,11 @@
/*! \page AstAPI Asterisk API
* \section Asteriskapi Asterisk API
- * This programmer's documentation covers the generic API.
- * \subsection generic Generic Model
+ * Some generic documents on the Asterisk architecture
+ * \subsection model_txt Generic Model
* \verbinclude model.txt
- * \subsection channel Channels
+ * \subsection channel_txt Channels
+ * \arg See \link Def_Channel
* \verbinclude channel.txt
*/
@@ -88,6 +93,7 @@
DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it publishes routes which are in turn accessed via industry standard protocols such as IAX, SIP and H.323.
+ \par References
\arg DUNDi is documented at http://www.dundi.com
\arg Implemented in \ref pbx_dundi.c and \ref dundi-parser.c
\arg Configuration in \link Config_dun dundi.conf \endlink
@@ -95,9 +101,12 @@
/*! \page AstCDR CDR - Call Data Records and billing
* \section cdr Call Data Records
- * \verbinclude README.cdr
+ * \par See also
* \arg \ref cdr.c
+ * \arg \ref cdr_drivers
* \arg \ref Config_cdr CDR configuration files
+ *
+ * \verbinclude README.cdr
*/
/*! \page AstREADME README - the general administrator introduction
@@ -137,6 +146,8 @@
* \arg \link Config_oss OSS (sound card) configuration \endlink
* \arg \link Config_alsa ALSA (sound card) configuration \endlink
* \arg \link Config_agent Agent (proxy channel) configuration \endlink
+ * \arg \link Config_misdn MISDN Experimental ISDN BRI channel configuration \endlink
+ * \arg \link Config_h323 H.323 configuration \endlink
* \section appconf Application configuration files
* \arg \link Config_mm Meetme (conference bridge) configuration \endlink
* \arg \link Config_qu Queue system configuration \endlink
@@ -164,10 +175,17 @@
* \verbinclude README.asterisk.conf
*/
/*! \page Config_mod Modules configuration
+ * All res_ resource modules are loaded with globals on, which means
+ * that non-static functions are callable from other modules.
+ *
+ * If you want your non res_* module to export functions to other modules
+ * you have to include it in the [global] section.
* \verbinclude modules.conf.sample
*/
/*! \page Config_fea Call features configuration
+ * \par See also
+ * \arg \ref res_features.c : Call feature implementation
* \section featconf features.conf
* \verbinclude features.conf.sample
*/
@@ -189,58 +207,75 @@
*/
/*! \page Config_iax IAX configuration
- * \ref chan_iax2.c
+ * \arg Implemented in \ref chan_iax2.c
* \section iaxconf iax.conf
* \verbinclude iax.conf.sample
*/
/*! \page Config_sip SIP configuration
* Also see \ref Config_rtp RTP configuration
- * \ref chan_sip.c
+ * \arg Implemented in \ref chan_sip.c
* \section sipconf sip.conf
* \verbinclude sip.conf.sample
+ *
+ * \arg \b Back \ref chanconf
*/
/*! \page Config_mgcp MGCP configuration
* Also see \ref Config_rtp RTP configuration
- * \ref chan_mgcp.c
+ * \arg Implemented in \ref chan_mgcp.c
* \section mgcpconf mgcp.conf
* \verbinclude mgcp.conf.sample
*/
+/*! \page Config_misdn MISDN configuration
+ * \arg Implemented in \ref chan_misdn.c
+ * \section misdnconf misdn.conf
+ * \verbinclude misdn.conf.sample
+ */
+
/*! \page Config_vm VoiceMail configuration
* \section vmconf voicemail.conf
- * \ref app_voicemail.c
+ * \arg Implemented in \ref app_voicemail.c
* \verbinclude voicemail.conf.sample
*/
/*! \page Config_zap Zaptel configuration
* \section zapconf zapata.conf
- * \ref chan_zap.c
+ * \arg Implemented in \ref chan_zap.c
* \verbinclude zapata.conf.sample
*/
+/*! \page Config_h323 H.323 channel driver information
+ * This is the configuration of the H.323 channel driver within the Asterisk
+ * distribution. There's another one, called OH323, in asterisk-addons
+ * \arg Implemented in \ref chan_h323.c
+ * \section h323conf h323.conf
+ * \ref chan_h323.c
+ * \verbinclude README.h323
+ */
+
/*! \page Config_oss OSS configuration
* \section ossconf oss.conf
- * \ref chan_oss.c
+ * \arg Implemented in \ref chan_oss.c
* \verbinclude oss.conf.sample
*/
/*! \page Config_alsa ALSA configuration
* \section alsaconf alsa.conf
- * \ref chan_alsa.c
+ * \arg Implemented in \ref chan_alsa.c
* \verbinclude alsa.conf.sample
*/
/*! \page Config_agent Agent configuration
* \section agentconf agents.conf
* The agent channel is a proxy channel for queues
- * \ref chan_agent.c
+ * \arg Implemented in \ref chan_agent.c
* \verbinclude agents.conf.sample
*/
/*! \page Config_rtp RTP configuration
- * \ref rtp.c
+ * \arg Implemented in \ref rtp.c
* Used in \ref chan_sip.c and \ref chan_mgcp.c (and various H.323 channels)
* \section rtpconf rtp.conf
* \verbinclude rtp.conf.sample
@@ -255,19 +290,20 @@
/*! \page Config_enum ENUM Configuration
* \section enumconf enum.conf
* \arg See also \ref enumreadme
- * \arg \ref app_enumlookup.c
+ * \arg Implemented in \ref app_enumlookup.c and \ref enum.c
* \verbinclude enum.conf.sample
*/
/*! \page cdr_custom Custom CDR Configuration
- * \arg See also \ref cdrconf
+ * \par See also
+ * \arg \ref cdrconf
* \arg \ref cdr_custom.c
* \verbinclude cdr_custom.conf.sample
*/
/*! \page cdr_ami Manager CDR driver configuration
- * \arg See also \ref cdrconf
- * See also:
+ * \par See also
+ * \arg \ref cdrconf
* \arg \ref AstAMI
* \arg \ref cdr_manager.c
* \verbinclude cdr_manager.conf.sample
@@ -304,7 +340,8 @@
*/
/*! \page Config_cdr CDR configuration
- * \verbinclude cdr.conf.sample
+ * \par See also
+ * \arg \ref cdr_drivers
* \arg \link Config_cdr CDR configuration \endlink
* \arg \link cdr_custom Custom CDR driver configuration \endlink
* \arg \link cdr_ami Manager CDR driver configuration \endlink
@@ -312,6 +349,7 @@
* \arg \link cdr_pgsql PostgreSQL CDR driver configuration \endlink
* \arg \link cdr_sqlite SQLite CDR driver configuration \endlink
* \arg \link cdr_tds FreeTDS CDR driver configuration (Microsoft SQL Server) \endlink
+ * \verbinclude cdr.conf.sample
*/
/*! \page Config_moh Music on Hold Configuration
@@ -343,11 +381,13 @@
*/
/*! \page Config_qu ACD - Queue system configuration
+ * \arg Implemented in \ref app_queue.c
* \section quconf queues.conf
* \verbinclude queues.conf.sample
*/
/*! \page Config_mm Meetme - The conference bridge configuration
+ * \arg Implemented in \ref app_meetme.c
* \section mmconf meetme.conf
* \verbinclude meetme.conf.sample
*/
@@ -363,3 +403,47 @@
* \section SoundList List of included sound files
* \verbinclude sounds.txt
*/
+
+/*! \addtogroup cdr_drivers Module: CDR Drivers
+ * \section CDR_generic Asterisk CDR Drivers
+ * \brief CDR drivers are loaded dynamically (see \ref Config_mod "Modules Configuration"). Each loaded CDR driver produce a billing record for each call.
+ * \arg \ref Config_cdr "CDR Configuration"
+ */
+
+
+/*! \addtogroup channel_drivers Module: Asterisk Channel Drivers
+ * \section channel_generic Asterisk Channel Drivers
+ * \brief Channel drivers are loaded dynamically (see \ref Config_mod "Modules Configuration").
+ */
+
+/*! \addtogroup applications Module: Dial plan applications
+ * \section app_generic Asterisk Dial Plan Applications
+ * \brief Applications support the dialplan. They register dynamically with \ref ast_register_application() and unregister with ast_unregister_application()
+ * \par See also
+ * \arg \ref functions
+ *
+ */
+
+/*! \addtogroup functions Module: Dial plan functions
+ * \section func_generic Asterisk Dial Plan Functions
+ * \brief Functions support the dialplan. They do not change any property of a channel
+ * or touch a channel in any way.
+ * \par See also
+ * \arg \ref applications
+ *
+ */
+
+/*! \addtogroup codecs Module: Codecs
+ * \section codec_generic Asterisk Codec Modules
+ * Codecs are referenced in configuration files by name
+ * \par See also
+ * \arg \ref formats
+ *
+ */
+
+/*! \addtogroup formats Module: Media File Formats
+ * \section codec_generic Asterisk Format drivers
+ * Formats are modules that read or write media files to disk.
+ * \par See also
+ * \arg \ref codecs
+ */
Index: frame.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/frame.h,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -d -r1.62 -r1.63
--- frame.h 28 Oct 2005 21:49:27 -0000 1.62
+++ frame.h 6 Nov 2005 15:09:47 -0000 1.63
@@ -18,6 +18,8 @@
/*! \file
* \brief Asterisk internal frame definitions.
+ * \arg For an explanation of frames, see \ref Def_Frame
+ * \arg Frames are send of Asterisk channels, see \ref Def_Channel
*/
#ifndef _ASTERISK_FRAME_H
@@ -35,9 +37,55 @@
char order[32];
};
-/*! Data structure associated with a single frame of data */
-/* A frame of data read used to communicate between
- between channels and applications */
+/*! \page Def_Frame AST Multimedia and signalling frames
+ \section Def_AstFrame What is an ast_frame ?
+ A frame of data read used to communicate between
+ between channels and applications.
+ Frames are divided into frame types and subclasses.
+
+ \par Frame types
+ \arg \b VOICE: Voice data, subclass is codec (AST_FORMAT_*)
+ \arg \b VIDEO: Video data, subclass is codec (AST_FORMAT_*)
+ \arg \b DTMF: A DTMF digit, subclass is the digit
+ \arg \b IMAGE: Image transport, mostly used in IAX
+ \arg \b TEXT: Text messages
+ \arg \b HTML: URL's and web pages
+ \arg \b T38: T38 Fax transport frames
+ \arg \b IAX: Private frame type for the IAX protocol
+ \arg \b CNG: Comfort noice frames
+ \arg \b CONTROL: A control frame, subclass defined as AST_CONTROL_
+ \arg \b NULL: Empty, useless frame
+
+ \par Files
+ \arg frame.h Definitions
+ \arg frame.c Function library
+ \arg \ref Def_Channel Asterisk channels
+ \section Def_ControlFrame Control Frames
+ Control frames send signalling information between channels
+ and devices. They are prefixed with AST_CONTROL_, like AST_CONTROL_FRAME_HANGUP
+ \arg \b HANGUP The other end has hungup
+ \arg \b RING Local ring
+ \arg \b RINGING The other end is ringing
+ \arg \b ANSWER The other end has answered
+ \arg \b BUSY Remote end is busy
+ \arg \b TAKEOFFHOOK Make it go off hook (what's "it" ? )
+ \arg \b OFFHOOK Line is off hook
+ \arg \b CONGESTION Congestion (circuit is busy, not available)
+ \arg \b FLASH Other end sends flash hook
+ \arg \b WINK Other end sends wink
+ \arg \b OPTION Send low-level option
+ \arg \b RADIO_KEY Key radio (see app_rpt.c)
+ \arg \b RADIO_UNKEY Un-key radio (see app_rpt.c)
+ \arg \b PROGRESS Other end indicates call progress
+ \arg \b PROCEEDING Indicates proceeding
+ \arg \b HOLD Call is placed on hold
+ \arg \b UNHOLD Call is back from hold
+ \arg \b VIDUPDATE Video update requested
+
+*/
+
+/*! \brief Data structure associated with a single frame of data
+ */
struct ast_frame {
/*! Kind of frame */
int frametype;
@@ -63,10 +111,10 @@
struct ast_frame *next;
};
-#define AST_FRIENDLY_OFFSET 64 /*! It's polite for a a new frame to
- have this number of bytes for additional
- headers. */
-#define AST_MIN_OFFSET 32 /*! Make sure we keep at least this much handy */
+#define AST_FRIENDLY_OFFSET 64 /*! It's polite for a a new frame to
+ have this number of bytes for additional
+ headers. */
+#define AST_MIN_OFFSET 32 /*! Make sure we keep at least this much handy */
/*! Need the header be free'd? */
#define AST_MALLOCD_HDR (1 << 0)
@@ -206,29 +254,29 @@
#define AST_OPTION_FLAG_ANSWER 5
#define AST_OPTION_FLAG_WTF 6
-/* Verify touchtones by muting audio transmission
+/*! Verify touchtones by muting audio transmission
(and reception) and verify the tone is still present */
#define AST_OPTION_TONE_VERIFY 1
-/* Put a compatible channel into TDD (TTY for the hearing-impared) mode */
+/*! Put a compatible channel into TDD (TTY for the hearing-impared) mode */
#define AST_OPTION_TDD 2
-/* Relax the parameters for DTMF reception (mainly for radio use) */
+/*! Relax the parameters for DTMF reception (mainly for radio use) */
#define AST_OPTION_RELAXDTMF 3
-/* Set (or clear) Audio (Not-Clear) Mode */
+/*! Set (or clear) Audio (Not-Clear) Mode */
#define AST_OPTION_AUDIO_MODE 4
-/* Set channel transmit gain */
-/* Option data is a single signed char
+/*! Set channel transmit gain
+ * Option data is a single signed char
representing number of decibels (dB)
to set gain to (on top of any gain
specified in channel driver)
*/
#define AST_OPTION_TXGAIN 5
-/* Set channel receive gain */
-/* Option data is a single signed char
+/*! Set channel receive gain
+ * Option data is a single signed char
representing number of decibels (dB)
to set gain to (on top of any gain
specified in channel driver)
@@ -251,8 +299,8 @@
u_int8_t data[0];
};
-/* Requests a frame to be allocated */
-/*
+/*! \brief Requests a frame to be allocated
+ *
* \param source
* Request a frame be allocated. source is an optional source of the frame,
* len is the requested length, or "0" if the caller will supply the buffer
@@ -261,55 +309,49 @@
struct ast_frame *ast_fralloc(char *source, int len);
#endif
-/*! Frees a frame */
-/*!
+/*! \brief Frees a frame
* \param fr Frame to free
* Free a frame, and the memory it used if applicable
- * no return.
+ * \return no return.
*/
void ast_frfree(struct ast_frame *fr);
-/*! Copies a frame */
-/*!
+/*! \brief Copies a frame
* \param fr frame to act upon
* Take a frame, and if it's not been malloc'd, make a malloc'd copy
* and if the data hasn't been malloced then make the
* data malloc'd. If you need to store frames, say for queueing, then
* you should call this function.
- * Returns a frame on success, NULL on error
+ * \return Returns a frame on success, NULL on error
*/
struct ast_frame *ast_frisolate(struct ast_frame *fr);
-/*! Copies a frame */
-/*!
+/*! \brief Copies a frame
* \param fr frame to copy
* Dupliates a frame -- should only rarely be used, typically frisolate is good enough
- * Returns a frame on success, NULL on error
+ * \return Returns a frame on success, NULL on error
*/
struct ast_frame *ast_frdup(struct ast_frame *fr);
-/*! Reads a frame from an fd */
-/*!
- * \param fd an opened fd to read from
+/*! \brief Reads a frame from an fd
* Read a frame from a stream or packet fd, as written by fd_write
- * returns a frame on success, NULL on error
+ * \param fd an opened fd to read from
+ * \return returns a frame on success, NULL on error
*/
struct ast_frame *ast_fr_fdread(int fd);
-/*! Writes a frame to an fd */
-/*!
+/*! Writes a frame to an fd
+ * Write a frame to an fd
* \param fd Which fd to write to
* \param frame frame to write to the fd
- * Write a frame to an fd
- * Returns 0 on success, -1 on failure
+ * \return Returns 0 on success, -1 on failure
*/
int ast_fr_fdwrite(int fd, struct ast_frame *frame);
-/*! Sends a hangup to an fd */
-/*!
- * \param fd fd to write to
+/*! \brief Sends a hangup to an fd
* Send a hangup (NULL equivalent) on an fd
- * Returns 0 on success, -1 on failure
+ * \param fd fd to write to
+ * \return Returns 0 on success, -1 on failure
*/
int ast_fr_fdhangup(int fd);
@@ -326,15 +368,13 @@
#endif
-/*! Get the name of a format */
-/*!
+/*! \brief Get the name of a format
* \param format id of format
* \return A static string containing the name of the format or "UNKN" if unknown.
*/
extern char* ast_getformatname(int format);
-/*! Get the names of a set of formats */
-/*!
+/*! \brief Get the names of a set of formats
* \param buf a buffer for the output string
* \param size size of buf (bytes)
* \param format the format (combined IDs of codecs)
@@ -345,17 +385,16 @@
extern char* ast_getformatname_multiple(char *buf, size_t size, int format);
/*!
+ * \brief Gets a format from a name.
* \param name string of format
- * Gets a format from a name.
- * This returns the form of the format in binary on success, 0 on error.
+ * \return This returns the form of the format in binary on success, 0 on error.
*/
extern int ast_getformatbyname(char *name);
-/*! Get a name from a format */
-/*!
- * \param codec codec number (1,2,4,8,16,etc.)
+/*! \brief Get a name from a format
* Gets a name from a format
- * This returns a static string identifying the format on success, 0 on error.
+ * \param codec codec number (1,2,4,8,16,etc.)
+ * \return This returns a static string identifying the format on success, 0 on error.
*/
extern char *ast_codec2str(int codec);
@@ -381,39 +420,39 @@
extern void ast_frame_dump(char *name, struct ast_frame *f, char *prefix);
-/* Initialize a codec preference to "no preference" */
+/*! \brief Initialize a codec preference to "no preference" */
extern void ast_codec_pref_init(struct ast_codec_pref *pref);
-/* Codec located at a particular place in the preference index */
+/*! \brief Codec located at a particular place in the preference index */
extern int ast_codec_pref_index(struct ast_codec_pref *pref, int index);
-/* Remove a codec from a preference list */
+/*! \brief Remove a codec from a preference list */
extern void ast_codec_pref_remove(struct ast_codec_pref *pref, int format);
-/* Append a codec to a preference list, removing it first if it was already there */
+/*! \brief Append a codec to a preference list, removing it first if it was already there */
extern int ast_codec_pref_append(struct ast_codec_pref *pref, int format);
-/* Select the best format according to preference list from supplied options.
+/*! \brief Select the best format according to preference list from supplied options.
If "find_best" is non-zero then if nothing is found, the "Best" format of
the format list is selected, otherwise 0 is returned. */
extern int ast_codec_choose(struct ast_codec_pref *pref, int formats, int find_best);
-/* Parse an "allow" or "deny" line and update the mask and pref if provided */
+/*! \brief Parse an "allow" or "deny" line and update the mask and pref if provided */
extern void ast_parse_allow_disallow(struct ast_codec_pref *pref, int *mask, const char *list, int allowing);
-/* Dump codec preference list into a string */
+/*! \brief Dump codec preference list into a string */
extern int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
-/* Shift a codec preference list up or down 65 bytes so that it becomes an ASCII string */
+/*! \brief Shift a codec preference list up or down 65 bytes so that it becomes an ASCII string */
extern void ast_codec_pref_convert(struct ast_codec_pref *pref, char *buf, size_t size, int right);
-/* Returns the number of samples contained in the frame */
+/*! \brief Returns the number of samples contained in the frame */
extern int ast_codec_get_samples(struct ast_frame *f);
-/* Returns the number of bytes for the number of samples of the given format */
+/*! \brief Returns the number of bytes for the number of samples of the given format */
extern int ast_codec_get_len(int format, int samples);
-/* Gets duration in ms of interpolation frame for a format */
+/*! \brief Gets duration in ms of interpolation frame for a format */
static inline int ast_codec_interp_len(int format)
{
return (format == AST_FORMAT_ILBC) ? 30 : 20;
Index: fskmodem.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/fskmodem.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- fskmodem.h 24 Oct 2005 20:12:06 -0000 1.3
+++ fskmodem.h 6 Nov 2005 15:09:47 -0000 1.4
@@ -19,6 +19,7 @@
/*! \file
* \brief FSK Modem Support
* \note Includes code and algorithms from the Zapata library.
+ * \todo Translate Emiliano Zapata's spanish comments to english, please.
*/
#ifndef _ASTERISK_FSKMODEM_H
@@ -32,39 +33,39 @@
#define NCOLA 0x4000
typedef struct {
- float spb; /* Samples / Bit */
- int nbit; /* Number of Data Bits (5,7,8) */
- float nstop; /* Number of Stop Bits 1,1.5,2 */
- int paridad; /* Parity 0=none 1=even 2=odd */
- int hdlc; /* Modo Packet */
+ float spb; /*!< Samples / Bit */
+ int nbit; /*!< Number of Data Bits (5,7,8) */
+ float nstop; /*!< Number of Stop Bits 1,1.5,2 */
+ int paridad; /*!< Parity 0=none 1=even 2=odd */
+ int hdlc; /*!< Modo Packet */
float x0;
float x1;
float x2;
float cont;
- int bw; /* Ancho de Banda */
- double fmxv[8],fmyv[8]; /* filter stuff for M filter */
- int fmp; /* pointer for M filter */
- double fsxv[8],fsyv[8]; /* filter stuff for S filter */
- int fsp; /* pointer for S filter */
- double flxv[8],flyv[8]; /* filter stuff for L filter */
- int flp; /* pointer for L filter */
- int f_mark_idx; /* Indice de frecuencia de marca (f_M-500)/5 */
- int f_space_idx;/* Indice de frecuencia de espacio (f_S-500)/5 */
+ int bw; /*!< Ancho de Banda */
+ double fmxv[8],fmyv[8]; /*!< filter stuff for M filter */
+ int fmp; /*!< pointer for M filter */
+ double fsxv[8],fsyv[8]; /*!< filter stuff for S filter */
+ int fsp; /*!< pointer for S filter */
+ double flxv[8],flyv[8]; /*!< filter stuff for L filter */
+ int flp; /*!< pointer for L filter */
+ int f_mark_idx; /*!< Indice de frecuencia de marca (f_M-500)/5 */
+ int f_space_idx; /*!< Indice de frecuencia de espacio (f_S-500)/5 */
int state;
- int pcola; /* Puntero de las colas de datos */
- float cola_in[NCOLA]; /* Cola de muestras de entrada */
- float cola_filtro[NCOLA]; /* Cola de muestras tras filtros */
- float cola_demod[NCOLA]; /* Cola de muestras demoduladas */
+ int pcola; /*!< Puntero de las colas de datos */
+ float cola_in[NCOLA]; /*!< Cola de muestras de entrada */
+ float cola_filtro[NCOLA]; /*!< Cola de muestras tras filtros */
+ float cola_demod[NCOLA]; /*!< Cola de muestras demoduladas */
} fsk_data;
/* \brief Retrieve a serial byte into outbyte.
Buffer is a pointer into a series of
shorts and len records the number of bytes in the buffer. len will be
- overwritten with the number of bytes left that were not consumed, and the
- return value is as follows:
- 0: Still looking for something...
- 1: An output byte was received and stored in outbyte
- -1: An error occured in the transmission
+ overwritten with the number of bytes left that were not consumed.
+ \return return value is as follows:
+ \arg 0: Still looking for something...
+ \arg 1: An output byte was received and stored in outbyte
+ \arg -1: An error occured in the transmission
He must be called with at least 80 bytes of buffer. */
extern int fsk_serie(fsk_data *fskd, short *buffer, int *len, int *outbyte);
More information about the svn-commits
mailing list