diff --git a/channels/DialTone.h b/channels/DialTone.h index 098ed44d7..e71ba0c7d 100644 --- a/channels/DialTone.h +++ b/channels/DialTone.h @@ -9,6 +9,11 @@ * */ +/*! \file + * \brief + * 8-bit raw data + */ + static unsigned char DialTone[] = { 0xff, 0xab, 0x9d, 0x96, 0x91, 0x90, 0x91, 0x96, 0x9c, 0xaa, 0xd9, 0x2f, 0x1f, 0x19, 0x15, 0x14, 0x15, 0x19, 0x1f, 0x2c, diff --git a/channels/gentone.c b/channels/gentone.c index 29bd88e91..fc97e389e 100644 --- a/channels/gentone.c +++ b/channels/gentone.c @@ -1,6 +1,11 @@ /* Generate a header file for a particular single or double frequency */ +/*! \file + * \brief + * Generate a header file for a particular single or double frequency + */ + #include #include #include diff --git a/channels/iax2.h b/channels/iax2.h index 99748814d..b3947fffa 100644 --- a/channels/iax2.h +++ b/channels/iax2.h @@ -10,6 +10,15 @@ * This program is free software, distributed under the terms of * the GNU General Public License */ + +/*! \file + * \brief + * + * Implementation of Inter-Asterisk eXchange, version 2 + * \ref iax2-parser.c + * \ref iax2-parser.h + * \ref chan_iax2.c + */ #ifndef _IAX2_H #define _IAX2_H diff --git a/channels/misdn/chan_misdn_config.h b/channels/misdn/chan_misdn_config.h index f9475bd03..8c27f4f24 100644 --- a/channels/misdn/chan_misdn_config.h +++ b/channels/misdn/chan_misdn_config.h @@ -11,6 +11,12 @@ * the GNU General Public License */ +/*! \file \brief + * Interface to mISDN - Config + * \author Christian Richter + */ + + #ifndef CHAN_MISDN_CONFIG_H diff --git a/channels/misdn/ie.c b/channels/misdn/ie.c index 9c783cd10..817e3d8cb 100644 --- a/channels/misdn/ie.c +++ b/channels/misdn/ie.c @@ -15,6 +15,11 @@ * the GNU General Public License */ +/*! \file \brief + * Interface to mISDN + * \author Christian Richter + */ + /* the pointer of enc_ie_* always points to the IE itself if qi is not NULL (TE-mode), offset is set diff --git a/channels/misdn/isdn_lib.c b/channels/misdn/isdn_lib.c index 888887d6e..67ecb47fa 100644 --- a/channels/misdn/isdn_lib.c +++ b/channels/misdn/isdn_lib.c @@ -11,6 +11,12 @@ * the GNU General Public License */ +/*! \file \brief + * Interface to mISDN + * \author Christian Richter + */ + + #include #include diff --git a/channels/misdn/isdn_lib.h b/channels/misdn/isdn_lib.h index 5dc374c4f..731d497b3 100644 --- a/channels/misdn/isdn_lib.h +++ b/channels/misdn/isdn_lib.h @@ -11,6 +11,13 @@ * the GNU General Public License */ +/*! \file \brief + * + * Interface to mISDN + * + * \author Christian Richter + */ + #ifndef TE_LIB #define TE_LIB diff --git a/channels/misdn/isdn_msg_parser.c b/channels/misdn/isdn_msg_parser.c index 720f43d0d..ebaf6a92f 100644 --- a/channels/misdn/isdn_msg_parser.c +++ b/channels/misdn/isdn_msg_parser.c @@ -11,6 +11,12 @@ * the GNU General Public License */ +/*! \file \brief + * Interface to mISDN - message parser + * \author Christian Richter + */ + + #include "isdn_lib_intern.h" diff --git a/channels/misdn/portinfo.c b/channels/misdn/portinfo.c index bcb9f0313..8223164e5 100644 --- a/channels/misdn/portinfo.c +++ b/channels/misdn/portinfo.c @@ -1,3 +1,7 @@ +/*! \file \brief + * Interface to mISDN - ??? + * \author Christian Richter + */ #include "isdn_lib.h" diff --git a/channels/ringtone.h b/channels/ringtone.h index 559c42a7b..f4eac96fc 100644 --- a/channels/ringtone.h +++ b/channels/ringtone.h @@ -1,5 +1,9 @@ /* ringtone.h: Generated from frequencies 440 and 480 by gentone. 200 samples */ +/*! \file + \brief + Generated from frequencies 440 and 480 by gentone. 200 samples +*/ static short ringtone[200] = { 0, 11581, 21659, 28927, 32445, 31764, 26981, 18727, 8084, -3559, -14693, -23875, -29927, -32083, -30088, -24228, diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 6e4b0e99b..6fbe462ec 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -16,7 +16,8 @@ * at the top of the source tree. */ -/*! \file doxyref.h This file generates Doxygen pages from files in the /doc +/*! \file + * \brief This file generates Doxygen pages from files in the /doc directory of the Asterisk source code tree */ diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h index a57e890fd..8e63acfee 100644 --- a/include/asterisk/manager.h +++ b/include/asterisk/manager.h @@ -45,14 +45,18 @@ \endverbatim - ** Please try to re-use existing headers to simplify manager message parsing in clients. + \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients. Don't re-use an existing header with a new meaning, please. You can find a reference of standard headers in doc/manager.txt + +- \ref manager.c Main manager code file */ #define AMI_VERSION "1.1" #define DEFAULT_MANAGER_PORT 5038 /* Default port for Asterisk management via TCP */ +/*! \name Manager event classes */ +/*@{ */ #define EVENT_FLAG_SYSTEM (1 << 0) /* System events such as module load/unload */ #define EVENT_FLAG_CALL (1 << 1) /* Call event, such as state change, etc */ #define EVENT_FLAG_LOG (1 << 2) /* Log events */ @@ -64,11 +68,12 @@ #define EVENT_FLAG_DTMF (1 << 8) /* Ability to read DTMF events */ #define EVENT_FLAG_REPORTING (1 << 9) /* Reporting events such as rtcp sent */ #define EVENT_FLAG_CDR (1 << 10) /* CDR events */ +/*@} */ -/* Export manager structures */ +/*! \brief Export manager structures */ #define AST_MAX_MANHEADERS 128 -/* Manager Helper Function */ +/*! \brief Manager Helper Function */ typedef int (*manager_hook_t)(int, const char *, char *); @@ -87,13 +92,13 @@ int check_manager_enabled(void); /*! \brief Check if AMI/HTTP is enabled */ int check_webmanager_enabled(void); -/*! Add a custom hook to be called when an event is fired */ -/*! \param hook struct manager_custom_hook object to add +/*! Add a custom hook to be called when an event is fired + \param hook struct manager_custom_hook object to add */ void ast_manager_register_hook(struct manager_custom_hook *hook); -/*! Delete a custom hook to be called when an event is fired */ -/*! \param hook struct manager_custom_hook object to delete +/*! Delete a custom hook to be called when an event is fired + \param hook struct manager_custom_hook object to delete */ void ast_manager_unregister_hook(struct manager_custom_hook *hook); @@ -119,13 +124,13 @@ struct manager_action { AST_RWLIST_ENTRY(manager_action) list; }; -/* External routines may register/unregister manager callbacks this way */ +/*! \brief External routines may register/unregister manager callbacks this way + * \note Use ast_manager_register2() to register with help text for new manager commands */ #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL) -/* Use ast_manager_register2 to register with help text for new manager commands */ -/*! Register a manager command with the manager interface */ -/*! \param action Name of the requested Action: +/*! \brief Register a manager command with the manager interface + \param action Name of the requested Action: \param authority Required authority for this command \param func Function to call for this command \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands @@ -138,8 +143,8 @@ int ast_manager_register2( const char *synopsis, const char *description); -/*! Unregister a registred manager command */ -/*! \param action Name of registred Action: +/*! \brief Unregister a registred manager command + \param action Name of registred Action: */ int ast_manager_unregister( char *action ); @@ -161,8 +166,8 @@ int astman_verify_session_readpermissions(unsigned long ident, int perm); */ int astman_verify_session_writepermissions(unsigned long ident, int perm); -/*! External routines may send asterisk manager events this way */ -/*! \param category Event category, matches manager authorization +/*! \brief External routines may send asterisk manager events this way + * \param category Event category, matches manager authorization \param event Event name \param contents Contents of event */ @@ -176,22 +181,30 @@ int __attribute__ ((format(printf, 6, 7))) __manager_event(int category, const c const char *file, int line, const char *func, const char *contents, ...); -/*! Get header from mananger transaction */ +/*! \brief Get header from mananger transaction */ const char *astman_get_header(const struct message *m, char *var); -/*! Get a linked list of the Variable: headers */ +/*! \brief Get a linked list of the Variable: headers */ struct ast_variable *astman_get_variables(const struct message *m); -/*! Send error in manager transaction */ +/*! \brief Send error in manager transaction */ void astman_send_error(struct mansession *s, const struct message *m, char *error); + +/*! \brief Send response in manager transaction */ void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg); + +/*! \brief Send ack in manager transaction */ void astman_send_ack(struct mansession *s, const struct message *m, char *msg); + +/*! \brief Send ack in manager list transaction */ void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag); void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...); -/*! Called by Asterisk initialization */ +/*! \brief Called by Asterisk initialization */ int init_manager(void); + +/*! \brief Called by Asterisk module functions and the CLI command */ int reload_manager(void); #endif /* _ASTERISK_MANAGER_H */ diff --git a/include/asterisk/term.h b/include/asterisk/term.h index 3b454ce2c..3277f0042 100644 --- a/include/asterisk/term.h +++ b/include/asterisk/term.h @@ -28,6 +28,10 @@ extern "C" { #endif #define ESC 0x1b + +/*! \name Terminal Attributes +*/ +/*@{ */ #define ATTR_RESET 0 #define ATTR_BRIGHT 1 #define ATTR_DIM 2 @@ -35,7 +39,11 @@ extern "C" { #define ATTR_BLINK 5 #define ATTR_REVER 7 #define ATTR_HIDDEN 8 +/*@} */ +/*! \name Terminal Colors +*/ +/*@{ */ #define COLOR_BLACK 30 #define COLOR_GRAY (30 | 128) #define COLOR_RED 31 @@ -52,6 +60,7 @@ extern "C" { #define COLOR_BRCYAN (36 | 128) #define COLOR_WHITE 37 #define COLOR_BRWHITE (37 | 128) +/*@} */ char *term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout); diff --git a/include/asterisk/transcap.h b/include/asterisk/transcap.h index 5da8329dc..1eca28d6d 100644 --- a/include/asterisk/transcap.h +++ b/include/asterisk/transcap.h @@ -28,6 +28,9 @@ * that utilize these fields. */ +/*! \name AstTranscode General Asterisk channel transcoding definitions. +*/ +/*@{ */ #define AST_TRANS_CAP_SPEECH 0x0 #define AST_TRANS_CAP_DIGITAL 0x08 #define AST_TRANS_CAP_RESTRICTED_DIGITAL 0x09 @@ -35,6 +38,7 @@ #define AST_TRANS_CAP_7K_AUDIO 0x11 /* Depriciated ITU Q.931 (05/1998)*/ #define AST_TRANS_CAP_DIGITAL_W_TONES 0x11 #define AST_TRANS_CAP_VIDEO 0x18 +/*@} */ #define IS_DIGITAL(cap)\ (cap) & AST_TRANS_CAP_DIGITAL ? 1 : 0 diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h index 75023f0ad..2db3019c1 100644 --- a/include/asterisk/translate.h +++ b/include/asterisk/translate.h @@ -18,6 +18,7 @@ /*! \file * \brief Support for translation of data formats. + * \ref translate.c */ #ifndef _ASTERISK_TRANSLATE_H @@ -40,7 +41,9 @@ extern "C" { struct ast_trans_pvt; /* declared below */ /*! \brief - * Descriptor of a translator. Name, callbacks, and various options + * Descriptor of a translator. + * + * Name, callbacks, and various options * related to run-time operation (size of buffers, auxiliary * descriptors, etc). * @@ -116,7 +119,7 @@ struct ast_translator { /*! \brief * Default structure for translators, with the basic fields and buffers, * all allocated as part of the same chunk of memory. The buffer is - * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion. + * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion. * 'buf' points right after this space. * * *_framein() routines operate in two ways: @@ -158,6 +161,8 @@ struct ast_trans_pvt; * \return 0 on success, -1 on failure */ int __ast_register_translator(struct ast_translator *t, struct ast_module *module); + +/*! \brief See \ref __ast_register_translator() */ #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self) /*! diff --git a/include/asterisk/udptl.h b/include/asterisk/udptl.h index 090cc5b07..74fcf357d 100644 --- a/include/asterisk/udptl.h +++ b/include/asterisk/udptl.h @@ -15,6 +15,14 @@ * this code. */ +/*! \file + * \brief UDPTL support for T.38 + * \author Steve Underwood + * \ref udptl.c + * \todo add doxygen documentation to this file! + */ + + #ifndef _ASTERISK_UDPTL_H #define _ASTERISK_UDPTL_H @@ -24,8 +32,8 @@ #include "asterisk/sched.h" #include "asterisk/channel.h" -enum -{ + +enum { UDPTL_ERROR_CORRECTION_NONE, UDPTL_ERROR_CORRECTION_FEC, UDPTL_ERROR_CORRECTION_REDUNDANCY @@ -36,9 +44,9 @@ extern "C" { #endif struct ast_udptl_protocol { - /* Get UDPTL struct, or NULL if unwilling to transfer */ + /*! \brief Get UDPTL struct, or NULL if unwilling to transfer */ struct ast_udptl *(*get_udptl_info)(struct ast_channel *chan); - /* Set UDPTL peer */ + /*! \brief Set UDPTL peer */ int (* const set_udptl_peer)(struct ast_channel *chan, struct ast_udptl *peer); const char * const type; AST_RWLIST_ENTRY(ast_udptl_protocol) list; diff --git a/include/asterisk/ulaw.h b/include/asterisk/ulaw.h index 1ac079d54..0f3eae58b 100644 --- a/include/asterisk/ulaw.h +++ b/include/asterisk/ulaw.h @@ -24,7 +24,6 @@ #define _ASTERISK_ULAW_H -/*! Init the ulaw conversion stuff */ /*! * To init the ulaw to slinear conversion stuff, this needs to be run. */ @@ -35,9 +34,7 @@ void ast_ulaw_init(void); #define AST_ULAW_TAB_SIZE (32768 / AST_ULAW_STEP + 1) #define AST_ULAW_SIGN_BIT 0x80 -/*! converts signed linear to mulaw */ -/*! - */ +/*! \brief converts signed linear to mulaw */ #ifndef G711_NEW_ALGORITHM extern unsigned char __ast_lin2mu[16384]; #else @@ -57,7 +54,7 @@ extern short __ast_mulaw[256]; __ast_lin2mu[((mag) + AST_ULAW_STEP / 2) >> AST_ULAW_BIT_LOSS] -/*! convert signed linear sample to sign-magnitude pair for u-Law */ +/*! \brief convert signed linear sample to sign-magnitude pair for u-Law */ static inline void ast_ulaw_get_sign_mag(short sample, unsigned *sign, unsigned *mag) { /* It may look illogical to retrive the sign this way in both cases, diff --git a/include/asterisk/zapata.h b/include/asterisk/zapata.h index 8d7eff74f..50df73a58 100644 --- a/include/asterisk/zapata.h +++ b/include/asterisk/zapata.h @@ -19,10 +19,7 @@ /*! \file * \brief Stub to find zaptel headers - */ - - -/* +* * Stub to find the zaptel headers. The configure script will * define HAVE_ZAPTEL_VERSION according to what it has found. * Applications should include "zapata.h" and not (directly) diff --git a/include/jitterbuf.h b/include/jitterbuf.h index d2e5b5ac0..2a6045f05 100644 --- a/include/jitterbuf.h +++ b/include/jitterbuf.h @@ -13,6 +13,13 @@ * Copyright on this file is disclaimed to Digium for inclusion in Asterisk */ +/*! \file + * \brief + * jitterbuf: an application-independent jitterbuffer + * \ref jitterbuf.c + */ + + #ifndef _JITTERBUF_H_ #define _JITTERBUF_H_ @@ -20,7 +27,8 @@ extern "C" { #endif -/* configuration constants */ +/*! \name configuration constants */ +/*@{ */ /*! Number of historical timestamps to use in calculating jitter and drift */ #define JB_HISTORY_SZ 500 /*! what percentage of timestamps should we drop from the history when we examine it; @@ -34,6 +42,7 @@ extern "C" { #define JB_TARGET_EXTRA 40 /*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */ #define JB_ADJUST_DELAY 40 +/*@} */ enum jb_return_code { /* return codes */ @@ -47,10 +56,10 @@ enum jb_return_code { enum jb_frame_type { /* frame types */ - JB_TYPE_CONTROL, /* 0 */ - JB_TYPE_VOICE, /* 1 */ - JB_TYPE_VIDEO, /* 2 - reserved */ - JB_TYPE_SILENCE /* 3 */ + JB_TYPE_CONTROL, /*!< 0 */ + JB_TYPE_VOICE, /*!< 1 */ + JB_TYPE_VIDEO, /*!< 2 - reserved */ + JB_TYPE_SILENCE /*!< 3 */ }; typedef struct jb_conf { @@ -111,18 +120,20 @@ typedef struct jitterbuf { } jitterbuf; -/* new jitterbuf */ +/*! \brief new jitterbuf */ jitterbuf * jb_new(void); -/* destroy jitterbuf */ +/*! \brief destroy jitterbuf */ void jb_destroy(jitterbuf *jb); -/* reset jitterbuf */ -/* NOTE: The jitterbuffer should be empty before you call this, otherwise +/*! \brief reset jitterbuf + * \note The jitterbuffer should be empty before you call this, otherwise * you will leak queued frames, and some internal structures */ void jb_reset(jitterbuf *jb); -/* queue a frame data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) +/*!\brief queue a frame + * + * data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) * now=now (in receiver's time) return value is one of * JB_OK: Frame added. Last call to jb_next() still valid * JB_DROP: Drop this frame immediately @@ -130,7 +141,7 @@ void jb_reset(jitterbuf *jb); */ enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts, long now); -/* get a frame for time now (receiver's time) return value is one of +/*! \brief get a frame for time now (receiver's time) return value is one of * JB_OK: You've got frame! * JB_DROP: Here's an audio frame you should just drop. Ask me again for this time.. * JB_NOFRAME: There's no frame scheduled for this time. @@ -139,21 +150,21 @@ enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type t */ enum jb_return_code jb_get(jitterbuf *jb, jb_frame *frame, long now, long interpl); -/* unconditionally get frames from jitterbuf until empty */ +/*! \brief unconditionally get frames from jitterbuf until empty */ enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout); -/* when is the next frame due out, in receiver's time (0=EMPTY) +/*! \brief when is the next frame due out, in receiver's time (0=EMPTY) * This value may change as frames are added (esp non-audio frames) */ -long jb_next(jitterbuf *jb); +long jb_next(jitterbuf *jb); -/*! get jitterbuf info: only "statistics" may be valid */ +/*! \brief get jitterbuf info: only "statistics" may be valid */ enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats); -/*! set jitterbuf conf */ +/*! \brief set jitterbuf conf */ enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf); -typedef void (*jb_output_function_t)(const char *fmt, ...); -void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg); +typedef void (*jb_output_function_t)(const char *fmt, ...); +void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg); #ifdef __cplusplus } diff --git a/main/cygload.c b/main/cygload.c index 5945af4e4..fd8f3d5b6 100644 --- a/main/cygload.c +++ b/main/cygload.c @@ -1,7 +1,25 @@ /* - * Loader for asterisk under windows. + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 1999 - 2005, Digium, Inc. + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief + * Loader for Asterisk under Cygwin/windows. * Open the dll, locate main, run. */ + #include #include #include @@ -16,6 +34,6 @@ int main(int argc, char *argv[]) ast_main = (main_f)dlsym(handle, "main"); if (ast_main) return ast_main(argc, argv); - fprintf(stderr, "could not load asterisk, %s\n", dlerror()); + fprintf(stderr, "could not load Asterisk, %s\n", dlerror()); return 1; /* there was an error */ }