Version 0.1.10 from FTP

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@385 f38db490-d61c-443f-a65b-d21fe96a405b

3 files changed, 347 insertions, 57 deletions

diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index b456e5ce0..f246357f8 100755
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -23,10 +23,10 @@ extern "C" {
 #define AST_PBX_KEEP    0
 #define AST_PBX_REPLACE 1
 
-/* Max length of an application */
+//! Max length of an application
 #define AST_MAX_APP	32
 
-/* Special return values from applications to the PBX */
+//! Special return values from applications to the PBX
 #define AST_PBX_KEEPALIVE	10		/* Destroy the thread, but don't hang up the channel */
 
 struct ast_context;
@@ -35,122 +35,343 @@ struct ast_include;
 struct ast_ignorepat;
 struct ast_sw;
 
+//! Data structure associated with an asterisk switch
 struct ast_switch {
-	struct ast_switch *next;	/* NULL */
-	char *name;				/* Name of the switch */
-	char *description;		/* Description of the switch */
+	/*! NULL */
+	struct ast_switch *next;	
+	/*! Name of the switch */
+	char *name;				
+	/*! Description of the switch */
+	char *description;		
+	
 	int (*exists)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
+	
 	int (*canmatch)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
+	
 	int (*exec)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, int newstack, char *data);
 };
 
-/* Register an alternative switch */
+//! Register an alternative switch
+/*!
+ * \param sw switch to register
+ * This function registers a populated ast_switch structure with the
+ * asterisk switching architecture.
+ * It returns 0 on success, and other than 0 on failure
+ */
 extern int ast_register_switch(struct ast_switch *sw);
 
-/* Unregister an alternative switch */
+//! Unregister an alternative switch
+/*!
+ * \param sw switch to unregister
+ * Unregisters a switch from asterisk.
+ * Returns nothing
+ */
 extern void ast_unregister_switch(struct ast_switch *sw);
 
-/* Look up an application */
+//! Look up an application
+/*!
+ * \param app name of the app
+ * This function searches for the ast_app structure within
+ * the apps that are registered for the one with the name
+ * you passed in.
+ * Returns the ast_app structure that matches on success, or NULL on failure
+ */
 extern struct ast_app *pbx_findapp(char *app);
 
+//! executes an application
+/*!
+ * \param c channel to execute on
+ * \param app which app to execute
+ * \param data the data passed into the app
+ * \param newstack stack pointer
+ * This application executes an application on a given channel.  It
+ * saves the stack and executes the given appliation passing in
+ * the given data.
+ * It returns 0 on success, and -1 on failure
+ */
 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack);
 
-/* Register a new context */
+//! Register a new context
+/*!
+ * \param name name of the new context
+ * \param registrar registrar of the context
+ * This will first search for a context with your name.  If it exists already, it will not
+ * create a new one.  If it does not exist, it will create a new one with the given name
+ * and registrar.
+ * It returns NULL on failure, and an ast_context structure on success
+ */
 struct ast_context *ast_context_create(char *name, char *registrar);
 
-/* Destroy a context (matches the specified context (or ANY context if
-   NULL) */
-void ast_context_destroy(struct ast_context *, char *registrar);
+//! Destroy a context (matches the specified context (or ANY context if NULL)
+/*!
+ * \param con context to destroy
+ * \param registrar who registered it
+ * You can optionally leave out either parameter.  It will find it
+ * based on either the ast_context or the registrar name.
+ * Returns nothing
+ */
+void ast_context_destroy(struct ast_context *con, char *registrar);
 
-/* Find a context */
+//! Find a context
+/*!
+ * \param name name of the context to find
+ * Will search for the context with the given name.
+ * Returns the ast_context on success, NULL on failure.
+ */
 struct ast_context *ast_context_find(char *name);
 
-/* Create a new thread and start the PBX (or whatever) */
+//! Create a new thread and start the PBX (or whatever)
+/*!
+ * \param c channel to start the pbx on
+ * Starts a pbx thread on a given channel
+ * It returns -1 on failure, and 0 on success
+ */
 int ast_pbx_start(struct ast_channel *c);
 
-/* Execute the PBX in the current thread */
+//! Execute the PBX in the current thread
+/*!
+ * \param c channel to run the pbx on
+ * This executes the PBX on a given channel.  It allocates a new
+ * PBX structure for the channel, and provides all PBX functionality.
+ */
 int ast_pbx_run(struct ast_channel *c);
 
-/* Add and extension to an extension context.  Callerid is a pattern to match CallerID, or NULL to match any
-   callerid */
+/*! 
+ * \param context context to add the extension to
+ * \param replace
+ * \param extension extension to add
+ * \param priority priority level of extension addition
+ * \param callerid callerid of extension
+ * \param application application to run on the extension with that priority level
+ * \param data data to pass to the application
+ * \param datad
+ * \param registrar who registered the extension
+ * Add and extension to an extension context.  
+ * Callerid is a pattern to match CallerID, or NULL to match any callerid
+ * Returns 0 on success, -1 on failure
+ */
 int ast_add_extension(char *context, int replace, char *extension, int priority, char *callerid,
 	char *application, void *data, void (*datad)(void *), char *registrar);
 
-/* Add an extension to an extension context, this time with an ast_context *.  CallerID is a pattern to match
-   on callerid, or NULL to not care about callerid */
+//! Add an extension to an extension context, this time with an ast_context *.  CallerID is a pattern to match on callerid, or NULL to not care about callerid
+/*! 
+ * For details about the arguements, check ast_add_extension()
+ */
 int ast_add_extension2(struct ast_context *con,
 				      int replace, char *extension, int priority, char *callerid, 
 					  char *application, void *data, void (*datad)(void *),
 					  char *registrar);
 
-/* Add an application.  The function 'execute' should return non-zero if the line needs to be hung up. 
+//! Add an application.  The function 'execute' should return non-zero if the line needs to be hung up. 
+/*!
+  \param app Short name of the application
+  \param execute a function callback to execute the application
+  \param synopsis a short description of the application
+  \param description long description of the application
    Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline
    description with more detail, including under what conditions the application
-   will return 0 or -1.  */
+   will return 0 or -1.
+   This registers an application with asterisks internal application list.  Please note:
+   The individual applications themselves are responsible for registering and unregistering
+   CLI commands.
+   It returns 0 on success, -1 on failure.
+*/
 int ast_register_application(char *app, int (*execute)(struct ast_channel *, void *),
 			     char *synopsis, char *description);
 
-/* Remove an application */
+//! Remove an application
+/*!
+ * \param app name of the application (does not have to be the same string as the one that was registered)
+ * This unregisters an application from asterisk's internal registration mechanisms.
+ * It returns 0 on success, and -1 on failure.
+ */
 int ast_unregister_application(char *app);
 
-/* If an extension exists, return non-zero */
+//! If an extension exists, return non-zero
+// work
+/*!
+ * \param c this is not important
+ * \param context which context to look in
+ * \param exten which extension to search for
+ * \param priority priority of the action within the extension
+ * \param callerid callerid to search for
+ * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
+ * Otherwise, 0 is returned.
+ */
 int ast_exists_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
 
-/* If "exten" *could be* a valid extension in this context with or without
+//! Looks for a valid matching extension
+/*!
+  \param c not really important
+  \param context context to serach within
+  \param exten extension to check
+  \param priority priority of extension path
+  \param callerid callerid of extension being searched for
+   If "exten" *could be* a valid extension in this context with or without
    some more digits, return non-zero.  Basically, when this returns 0, no matter
-   what you add to exten, it's not going to be a valid extension anymore */
+   what you add to exten, it's not going to be a valid extension anymore
+*/
 int ast_canmatch_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
 
-/* Determine if a given extension matches a given pattern (in NXX format) */
+//! Determine if a given extension matches a given pattern (in NXX format)
+/*!
+ * \param pattern pattern to match
+ * \param extension extension to check against the pattern.
+ * Checks whether or not the given extension matches the given pattern.
+ * Returns 1 on match, 0 on failure
+ */
 int ast_extension_match(char *pattern, char *extension);
 
-/* Launch a new extension (i.e. new stack) */
+//! Launch a new extension (i.e. new stack)
+/*!
+ * \param c not important
+ * \param context which context to generate the extension within
+ * \param exten new extension to add
+ * \param priority priority of new extension
+ * \param callerid callerid of extension
+ * This adds a new extension to the asterisk extension list.
+ * It returns 0 on success, -1 on failure.
+ */
 int ast_spawn_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
 
-/* Execute an extension.  If it's not available, do whatever you should do for
+//! Execute an extension.
+/*!
+  \param c channel to execute upon
+  \param context which context extension is in
+  \param exten extension to execute
+  \param priority priority to execute within the given extension
+   If it's not available, do whatever you should do for
    default extensions and halt the thread if necessary.  This function does not
-   return, except on error. */
+   return, except on error.
+*/
 int ast_exec_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
 
-/* Add an include */
+//! Add an include
+/*!
+  \param context context to add include to
+  \param include new include to add
+  \param registrar who's registering it
+   Adds an include taking a char * string as the context parameter
+   Returns 0 on success, -1 on error
+*/
 int ast_context_add_include(char *context, char *include, char *registrar);
+
+//! Add an include
+/*!
+  \param con context to add the include to
+  \param include include to add
+  \param registrar who registered the context
+   Adds an include taking a struct ast_context as the first parameter
+   Returns 0 on success, -1 on failure
+*/
 int ast_context_add_include2(struct ast_context *con, char *include, char *registrar);
 
-/* Remove an include */
+//! Removes an include
+/*!
+ * See add_include
+ */
 int ast_context_remove_include(char *context, char *include, char *registrar);
+//! Removes an include by an ast_context structure
+/*!
+ * See add_include2
+ */
 int ast_context_remove_include2(struct ast_context *con, char *include, char *registrar);
 
-/* Add a switch */
+//! Add a switch
+/*!
+ * \param context context to which to add the switch
+ * \param sw switch to add
+ * \param data data to pass to switch
+ * \param registrar whoever registered the switch
+ * This function registers a switch with the asterisk switch architecture
+ * It returns 0 on success, -1 on failure
+ */
 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar);
+//! Adds a switch (first param is a ast_context)
+/*!
+ * See ast_context_add_switch()
+ */
 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
 
-/* Remove a switch */
+//! Remove a switch
+/*!
+ * Removes a switch with the given parameters
+ * Returns 0 on success, -1 on failure
+ */
 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar);
 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
 
-/* Simply remove extension from context */
+//! Simply remove extension from context
+/*!
+ * \param context context to remove extension from
+ * \param extension which extension to remove
+ * \param priority priority of extension to remove
+ * \param registrar registrar of the extension
+ * This function removes an extension from a given context.
+ * Returns 0 on success, -1 on failure
+ */
 int ast_context_remove_extension(char *context, char *extension, int priority,
 	char *registrar);
 int ast_context_remove_extension2(struct ast_context *con, char *extension,
 	int priority, char *registrar);
 
-/* Add an ignorepat */
+//! Add an ignorepat
+/*!
+ * \param context which context to add the ignorpattern to
+ * \param ignorpat ignorepattern to set up for the extension
+ * \param registrar registrar of the ignore pattern
+ * Adds an ignore pattern to a particular context.
+ * Returns 0 on success, -1 on failure
+ */
 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar);
 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
 
 /* Remove an ignorepat */
+/*!
+ * \param context context from which to remove the pattern
+ * \param ignorepat the pattern to remove
+ * \param registrar the registrar of the ignore pattern
+ * This removes the given ignorepattern
+ * Returns 0 on success, -1 on failure
+ */
 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar);
 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
 
-/* Check if a number should be ignored with respect to dialtone cancellation.  Returns 0 if
-   the pattern should not be ignored, or non-zero if the pattern should be ignored */
+//! Checks to see if a number should be ignored
+/*!
+ * \param context context to search within
+ * \param extension to check whether it should be ignored or not
+ * Check if a number should be ignored with respect to dialtone cancellation.  
+ * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
+ */
 int ast_ignore_pattern(char *context, char *pattern);
 
 /* Locking functions for outer modules, especially for completion functions */
+//! Locks the contexts
+/*! Locks the context list
+ * Returns 0 on success, -1 on error
+ */
 int ast_lock_contexts(void);
+
+//! Unlocks contexts
+/*!
+ * Returns 0 on success, -1 on failure
+ */
 int ast_unlock_contexts(void);
 
+//! Locks a given context
+/*!
+ * \param con context to lock
+ * Locks the context.
+ * Returns 0 on success, -1 on failure
+ */
 int ast_lock_context(struct ast_context *con);
+//! Unlocks the given context
+/*!
+ * \param con context to unlock
+ * Unlocks the given context
+ * Returns 0 on success, -1 on failure
+ */
 int ast_unlock_context(struct ast_context *con);
 
 /* Functions for returning values from structures */
diff --git a/include/asterisk/sched.h b/include/asterisk/sched.h
index 9ccdda195..fc8c797b1 100755
--- a/include/asterisk/sched.h
+++ b/include/asterisk/sched.h
@@ -18,23 +18,34 @@
 extern "C" {
 #endif
 
-/*
+//! Max num of schedule structs
+/*!
  * The max number of schedule structs to keep around
  * for use.  Undefine to disable schedule structure
  * caching. (Only disable this on very low memory 
  * machines)
  */
- 
 #define SCHED_MAX_CACHE 128
 
 struct sched_context;
 
-/* Create a scheduling context */
+//! New schedule context
+/* !
+ * Create a scheduling context
+ * Returns a malloc'd sched_context structure, NULL on failure
+ */
 extern struct sched_context *sched_context_create(void);
 
-void sched_context_destroy(struct sched_context *);
+//! destroys a schedule context
+/*!
+ * \param c Context to free
+ * Destroys (free's) the given sched_context structure
+ * Returns 0 on success, -1 on failure
+ */
+void sched_context_destroy(struct sched_context *c);
 
-/* 
+//! callback for a cheops scheduler
+/*! 
  * A cheops scheduler callback takes a pointer with callback data and
  * returns a 0 if it should not be run again, or non-zero if it should be
  * rescheduled to run again
@@ -42,20 +53,32 @@ void sched_context_destroy(struct sched_context *);
 typedef int (*ast_sched_cb)(void *data);
 #define AST_SCHED_CB(a) ((ast_sched_cb)(a))
 
-/* 
+//!Adds a scheduled event
+/*! 
+ * \param con Schduler context to add
+ * \param when how many milliseconds to wait for event to occur
+ * \param callback function to call when the amount of time expires
+ * \param data data to pass to the callback
  * Schedule an event to take place at some point in the future.  callback 
  * will be called with data as the argument, when milliseconds into the
  * future (approximately)
+ * Returns 0 on success, -1 on failure
  */
 extern int ast_sched_add(struct sched_context *con, int when, ast_sched_cb callback, void *data);
 
-/*
+//! Deletes a scheduled event
+/*!
+ * \param con scheduling context to delete item from
+ * \param id ID of the scheduled item to delete
  * Remove this event from being run.  A procedure should not remove its
  * own event, but return 0 instead.
+ * Returns 0 on success, -1 on failure
  */
 extern int ast_sched_del(struct sched_context *con, int id);
 
-/*
+//! Determines number of seconds until the next outstanding event to take place
+/*!
+ * \param con context to act upon
  * Determine the number of seconds until the next outstanding event
  * should take place, and return the number of milliseconds until
  * it needs to be run.  This value is perfect for passing to the poll
@@ -64,13 +87,17 @@ extern int ast_sched_del(struct sched_context *con, int id);
  */
 extern int ast_sched_wait(struct sched_context *con);
 
-/*
+//! Runs the queue
+/*!
+ * \param con Scheduling context to run
  * Run the queue, executing all callbacks which need to be performed
  * at this time.  Returns the number of events processed.
  */
 extern int ast_sched_runq(struct sched_context *con);
 
-/*
+//!Dumps the scheduler contents
+/*!
+ * \param con Context to dump
  * Debugging: Dump the contents of the scheduler to stderr
  */
 extern void ast_sched_dump(struct sched_context *con);
diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h
index 640c5794d..a1cfd913b 100755
--- a/include/asterisk/translate.h
+++ b/include/asterisk/translate.h
@@ -25,40 +25,82 @@ extern "C" {
 /* Declared by individual translators */
 struct ast_translator_pvt;
 
+//! data structure associated with a translator
 struct ast_translator {
+	/*! Name of translator */
 	char name[80];
+	/*! Source format */
 	int srcfmt;
+	/*! Destination format */
 	int dstfmt;
+	/*! Private data associated with the translator */
 	struct ast_translator_pvt *(*new)(void);
+	/*! Input frame callback */
 	int (*framein)(struct ast_translator_pvt *pvt, struct ast_frame *in);
+	/*! Output frame callback */
 	struct ast_frame * (*frameout)(struct ast_translator_pvt *pvt);
+	/*! Destroy translator callback */
 	void (*destroy)(struct ast_translator_pvt *pvt);
 	/* For performance measurements */
-	/* Generate an example frame */
+	/*! Generate an example frame */
 	struct ast_frame * (*sample)(void);
-	/* Cost in milliseconds for encoding/decoding 1 second of sound */
+	/*! Cost in milliseconds for encoding/decoding 1 second of sound */
 	int cost;
-	/* For linking, not to be modified by the translator */
+	/*! For linking, not to be modified by the translator */
 	struct ast_translator *next;
 };
 
 struct ast_trans_pvt;
 
-/* Register a Codec translator */
+//! Register a translator
+/*! 
+ * \param t populated ast_translator structure
+ * This registers a codec translator with asterisk
+ * Returns 0 on success, -1 on failure
+ */
 extern int ast_register_translator(struct ast_translator *t);
-/* Unregister same */
+
+//! Unregister a translator
+/*!
+ * \param t translator to unregister
+ * Unregisters the given tranlator
+ * Returns 0 on success, -1 on failure
+ */
 extern int ast_unregister_translator(struct ast_translator *t);
-/* Given a list of sources, and a designed destination format, which should
+
+//! Chooses the best translation path
+/*! 
+ * Given a list of sources, and a designed destination format, which should
    I choose? Returns 0 on success, -1 if no path could be found.  Modifies
-   dests and srcs in place */
+   dests and srcs in place 
+   */
 extern int ast_translator_best_choice(int *dsts, int *srcs);
 
-/* Build a path (possibly NULL) from source to dest */
+//!Builds a translator path
+/*! 
+ * \param dest destination format
+ * \param source source format
+ * Build a path (possibly NULL) from source to dest 
+ * Returns ast_trans_pvt on success, NULL on failure
+ * */
 extern struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
+
+//! Frees a translator path
+/*!
+ * \param tr translator path to get rid of
+ * Frees the given translator path structure
+ */
 extern void ast_translator_free_path(struct ast_trans_pvt *tr);
 
-/* Apply an input frame into the translator and receive zero or one output frames.  Consume
-   determines whether the original frame should be freed */
+//! translates one or more frames
+/*! 
+ * \param tr translator structure to use for translation
+ * \param f frame to translate
+ * \param consume Whether or not to free the original frame
+ * Apply an input frame into the translator and receive zero or one output frames.  Consume
+ * determines whether the original frame should be freed
+ * Returns an ast_frame of the new translation format on success, NULL on failure
+ */
 extern struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);