Version 0.1.10 from FTP

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

5 files changed, 312 insertions, 40 deletions

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index ecb1ab101..bf9c5b0b4 100755
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -18,6 +18,19 @@
 #if defined(__cplusplus) || defined(c_plusplus)
 extern "C" {
 #endif
+//! 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
+ * \param maxlen Max Length of the data
+ * \param timeout Timeout length waiting for data(in milliseconds).  Set to 0 for standard timeout(six seconds), or -1 for no time out.
+ *
+ *  This function was designed for application programmers for situations where they need 
+ *  to play a message and then get some DTMF data in response to the message.  If a digit 
+ *  is pressed during playback, it will immediately break out of the message and continue
+ *  execution of your code.
+ */
 extern int ast_app_getdata(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout);
 
 #if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/cdr.h b/include/asterisk/cdr.h
new file mode 100755
index 000000000..b2e0d1641
--- /dev/null
+++ b/include/asterisk/cdr.h
@@ -0,0 +1,196 @@
+/*
+ * Asterisk -- A telephony toolkit for Linux.
+ *
+ * Call Detail Record API 
+ * 
+ * Copyright (C) 1999, Mark Spencer
+ *
+ * Mark Spencer <markster@linux-support.net>
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License.
+ *
+ * Includes code and algorithms from the Zapata library.
+ *
+ */
+
+#ifndef _CDR_H
+#define _CDR_H
+
+#include <asterisk/channel.h>
+#include <sys/time.h>
+
+#define AST_CDR_NOANSWER			(1 << 0)
+#define AST_CDR_BUSY				(1 << 1)
+#define AST_CDR_ANSWERED			(1 << 2)
+
+//! AMA Flags
+#define AST_CDR_OMIT				(1)
+#define AST_CDR_BILLING				(2)
+#define AST_CDR_DOCUMENTATION		(3)
+
+struct ast_channel;
+
+//! Responsible for call detail data
+struct ast_cdr {
+	/*! Caller*ID with text */
+	char clid[AST_MAX_EXTENSION];		
+	/*! Caller*ID number */
+	char src[AST_MAX_EXTENSION];		
+	/*! Destination extension */
+	char dst[AST_MAX_EXTENSION];		
+	/*! Destination context */
+	char dcontext[AST_MAX_EXTENSION];	
+	
+	char channel[AST_MAX_EXTENSION];
+	/*! Destination channel if appropriate */
+	char dstchannel[AST_MAX_EXTENSION];	
+	/*! Last application if appropriate */
+	char lastapp[AST_MAX_EXTENSION];	
+	/*! Last application data */
+	char lastdata[AST_MAX_EXTENSION];	
+	
+	struct timeval start;
+	
+	struct timeval answer;
+	
+	struct timeval end;
+	/*! Total time in system, in seconds */
+	int duration;				
+	/*! Total time call is up, in seconds */
+	int billsec;				
+	/*! What happened to the call */
+	int disposition;			
+	/*! What flags to use */
+	int amaflags;				
+	/*! What account number to use */
+	char accountcode[20];			
+	/*! Whether or not the record has been posted */
+	int posted;				
+};
+
+typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
+
+//! Allocate a record
+/*! 
+ * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
+ */
+extern struct ast_cdr *ast_cdr_alloc(void);
+
+//! Free a record
+/* \param cdr ast_cdr structure to free
+ * Returns nothing important
+ */
+extern void ast_cdr_free(struct ast_cdr *cdr);
+
+//! Initialize based on a channel
+/*! 
+ * \param cdr Call Detail Record to use for channel
+ * \param chan Channel to bind CDR with
+ * Initializes a CDR and associates it with a particular channel
+ * Return is negligible.  (returns 0 by default)
+ */
+extern int ast_cdr_init(struct ast_cdr *cdr, struct ast_channel *chan);
+
+//! Register a CDR handling engine
+/*!
+ * \param name name associated with the particular CDR handler
+ * \param desc description of the CDR handler
+ * \param be function pointer to a CDR handler
+ * Used to register a Call Detail Record handler.
+ * Returns -1 on error, 0 on success.
+ */
+extern int ast_cdr_register(char *name, char *desc, ast_cdrbe be);
+
+//! Unregister a CDR handling engine
+/*!
+ * \param name name of CDR handler to unregister
+ * Unregisters a CDR by it's name
+ */
+extern void ast_cdr_unregister(char *name);
+
+//! Start a call
+/*!
+ * \param cdr the cdr you wish to associate with the call
+ * Starts all CDR stuff necessary for monitoring a call
+ * Returns nothing important
+ */
+extern void ast_cdr_start(struct ast_cdr *cdr);
+
+//! Answer a call
+/*!
+ * \param cdr the cdr you wish to associate with the call
+ * Starts all CDR stuff necessary for doing CDR when answering a call
+ */
+extern void ast_cdr_answer(struct ast_cdr *cdr);
+
+//! Busy a call
+/*!
+ * \param cdr the cdr you wish to associate with the call
+ * Returns nothing important
+ */
+extern void ast_cdr_busy(struct ast_cdr *cdr);
+
+//! End a call
+/*!
+ * \param cdr the cdr you have associated the call with
+ * Registers the end of call time in the cdr structure.
+ * Returns nothing important
+ */
+extern void ast_cdr_end(struct ast_cdr *cdr);
+
+//! Post the detail record
+/*! 
+ * \param cdr Which cdr to post
+ * Actually outputs the CDR record to the CDR plugins installed
+ * Returns nothing
+ */
+extern void ast_cdr_post(struct ast_cdr *cdr);
+
+//! Set the destination channel, if there was one
+/*!
+ * \param cdr Which cdr it's applied to
+ * Sets the destination channel the CDR is applied to
+ * Returns nothing
+ */
+extern void ast_cdr_setdestchan(struct ast_cdr *cdr, char *chan);
+
+//! Set the last executed application
+/*!
+ * \param cdr which cdr to act upon
+ * \param app the name of the app you wish to change it to
+ * \param data the data you want in the data field of app you set it to
+ * Changes the value of the last executed app
+ * Returns nothing
+ */
+extern void ast_cdr_setapp(struct ast_cdr *cdr, char *app, char *data);
+
+//! Convert a string to a detail record AMA flag
+/*!
+ * \param flag string form of flag
+ * Converts the string form of the flag to the binary form.
+ * Returns the binary form of the flag
+ */
+extern int ast_cdr_amaflags2int(char *flag);
+
+//! Disposition to a string
+/*!
+ * \param flag input binary form
+ * Converts the binary form of a disposition to string form.
+ * Returns a pointer to the string form
+ */
+extern char *ast_cdr_disp2str(int disposition);
+
+//! Flags to a string
+/*!
+ * \param flags binary flag
+ * Converts binary flags to string flags
+ * Returns string with flag name
+ */
+extern char *ast_cdr_flags2str(int flags);
+
+extern int ast_default_amaflags;
+
+extern char ast_default_accountcode[20];
+
+#endif /* _CDR_H */
diff --git a/include/asterisk/channel_pvt.h b/include/asterisk/channel_pvt.h
index 643115954..0085762fd 100755
--- a/include/asterisk/channel_pvt.h
+++ b/include/asterisk/channel_pvt.h
@@ -22,51 +22,54 @@ extern "C" {
 
 
 struct ast_channel_pvt {
-	/* Private data used by channel backend */
+	/*! Private data used by channel backend */
 	void *pvt;
-	/* Write translation path */
+	/*! Write translation path */
 	struct ast_trans_pvt *writetrans;
-	/* Read translation path */
+	/*! Read translation path */
 	struct ast_trans_pvt *readtrans;
-	/* Raw read format */
+	/*! Raw read format */
 	int rawreadformat;
-	/* Raw write format */
+	/*! Raw write format */
 	int rawwriteformat;
-	/* Send a literal DTMF digit */
+	/*! Send a literal DTMF digit */
 	int (*send_digit)(struct ast_channel *chan, char digit);
-	/* Call a given phone number (address, etc), but don't
+	/*! Call a given phone number (address, etc), but don't
 	   take longer than timeout seconds to do so.  */
 	int (*call)(struct ast_channel *chan, char *addr, int timeout);
-	/* Hangup (and possibly destroy) the channel */
+	/*! Hangup (and possibly destroy) the channel */
 	int (*hangup)(struct ast_channel *chan);
-	/* Answer the line */
+	/*! Answer the line */
 	int (*answer)(struct ast_channel *chan);
-	/* Read a frame, in standard format */
+	/*! Read a frame, in standard format */
 	struct ast_frame * (*read)(struct ast_channel *chan);
-	/* Write a frame, in standard format */
+	/*! Write a frame, in standard format */
 	int (*write)(struct ast_channel *chan, struct ast_frame *frame);
-	/* Display or transmit text */
+	/*! Display or transmit text */
 	int (*send_text)(struct ast_channel *chan, char *text);
-	/* Display or send an image */
+	/*! Display or send an image */
 	int (*send_image)(struct ast_channel *chan, struct ast_frame *frame);
-	/* Send HTML data */
+	/*! Send HTML data */
 	int (*send_html)(struct ast_channel *chan, int subclass, char *data, int len);
-	/* Handle an exception, reading a frame */
+	/*! Handle an exception, reading a frame */
 	struct ast_frame * (*exception)(struct ast_channel *chan);
-	/* Bridge two channels of the same type together */
+	/*! Bridge two channels of the same type together */
 	int (*bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
-	/* Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
+	/*! Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
 	int (*indicate)(struct ast_channel *c, int condition);
-	/* Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
+	/*! Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
 	int (*fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
-	/* Set a given option */
+	/*! Set a given option */
 	int (*setoption)(struct ast_channel *chan, int option, void *data, int datalen);
-	/* Query a given option */
+	/*! Query a given option */
 	int (*queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
 };
 
-/* Create a channel structure */
+//! Create a channel structure
+/*! Returns NULL on failure to allocate */
 struct ast_channel *ast_channel_alloc(void);
+
+//! Free a channel structure
 void  ast_channel_free(struct ast_channel *);
 
 #if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/cli.h b/include/asterisk/cli.h
index 3720e4567..bfbf2c5c5 100755
--- a/include/asterisk/cli.h
+++ b/include/asterisk/cli.h
@@ -28,35 +28,51 @@ extern void ast_cli(int fd, char *fmt, ...);
 
 #define AST_MAX_CMD_LEN 	16
 
-/* A command line entry */
 #define AST_MAX_ARGS 64
 
+//! A command line entry */
 struct ast_cli_entry {
-	/* Null terminated list of the words of the command */
+	/*! Null terminated list of the words of the command */
 	char *cmda[AST_MAX_CMD_LEN];
-	/* Handler for the command (fd for output, # of arguments, argument list). 
-	    Returns RESULT_SHOWUSAGE for improper arguments */
+	/*! Handler for the command (fd for output, # of arguments, argument list).  Returns RESULT_SHOWUSAGE for improper arguments */
 	int (*handler)(int fd, int argc, char *argv[]);
-	/* Summary of the command (< 60 characters) */
+	/*! Summary of the command (< 60 characters) */
 	char *summary;
-	/* Detailed usage information */
+	/*! Detailed usage information */
 	char *usage;
-	/* Generate a list of possible completions for a given word */
+	/*! Generate a list of possible completions for a given word */
 	char *(*generator)(char *line, char *word, int pos, int state);
-	/* For linking */
+	/*! For linking */
 	struct ast_cli_entry *next;
 };
 
-/* Interpret a command s, sending output to fd */
+//! Interprets a command
+/*! Interpret a command s, sending output to fd
+ * Returns 0 on succes, -1 on failure 
+ */
 extern int ast_cli_command(int fd, char *s);
 
-/* Register your own command */
+//! Registers a command
+/*! 
+ * \param fd File descriptor that I/O is done to
+ * \param s string given at prompt
+ * Register your own command
+ * Returns 0 on success, -1 on failure
+ */
 extern int ast_cli_register(struct ast_cli_entry *e);
 
-/* Unregister your own command */
+//! Unregisters a command
+/*!
+ * \param e which cli entry to unregister
+ * Unregister your own command.  You must pass a completed ast_cli_entry structur
+ * Returns 0 on success, -1 on failure
+ */
 extern int ast_cli_unregister(struct ast_cli_entry *e);
 
-/* Useful for readline, that's about it */
+//! Readline madness
+/* Useful for readline, that's about it
+ * Returns 0 on success, -1 on failure
+ */
 extern char *ast_cli_generator(char *, char *, int);
 
 #if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/config.h b/include/asterisk/config.h
index d4eccc073..cb7d7e44e 100755
--- a/include/asterisk/config.h
+++ b/include/asterisk/config.h
@@ -27,19 +27,63 @@ struct ast_variable {
 	struct ast_variable *next;
 };
 
-/* Create a config structure from a given configuration file */
+//! Load a config file
+/*! 
+ * \param configfile path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
+ * Create a config structure from a given configuration file.
+ * Returns NULL on error, or an ast_config data structure on success
+ */
 struct ast_config *ast_load(char *configfile);
-/* Free memory associated with a given config */
+
+//! Removes a config
+/*!
+ * \param config config data structure associated with the config.
+ * Free memory associated with a given config
+ * Returns nothing
+ */
 void ast_destroy(struct ast_config *config);
-/* List categories of config file */
+
+//! Goes through categories
+/*!
+ * \param config Which config file you wish to "browse"
+ * \param prev A pointer to a previous category.
+ * This funtion is kind of non-intuitive in it's use.  To begin, one passes NULL as the second arguement.  It will return a pointer to the string of the first category in the file.  From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.  Note:  If you manually strcpy a string into a character array and pass it thinking it will return your category, it will not; the comparisons are not done doing strcmp, they are done by checking whether the value of the string POINTER is the same.
+ * Returns a category on success, or NULL on failure/no-more-categories
+ */
 char *ast_category_browse(struct ast_config *config, char *prev);
-/* List variables of config file */
+
+//! Goes through variables
+/*!
+ * Somewhat similar in intent as the ast_category_browse.  The category MUST be an actual pointer to an actual category (such as one obtained by using ast_category_browse()).
+ * List variables of config file
+ * Returns ast_variable list on success, or NULL on failure
+ */
 struct ast_variable *ast_variable_browse(struct ast_config *config, char *category);
-/* Retrieve a specific variable */
+
+//! Gets a variable
+/*!
+ * \param config which (opened) config to use
+ * \param category category under which the variable lies (must be a pointer to the category, such as one given by ast_category_browse)
+ * \param value which variable you wish to get the data for
+ * Goes through a given config file in the given category and searches for the given variable
+ * Returns the variable value on success, or NULL if unable to find it.
+ * Retrieve a specific variable */
 char *ast_variable_retrieve(struct ast_config *config, char *category, char *value);
-/* Determine affermativeness of a boolean value */
+
+//! Make sure something is true
+/*!
+ * Determine affermativeness of a boolean value.
+ * This function checks to see whether a string passed to it is an indication of an affirmitave value.  It checks to see if the string is "yes", "true", "y", "t", and "1".  
+ * Returns 0 if the value of s is a NULL pointer, 0 on "truth", and -1 on falsehood.
+ */
 int ast_true(char *val);
-/* Browse config structure and check for category duplicity Return non-zero if found */
+
+//! Check for category duplicates
+/*!
+ * \param config which config to use
+ * \param category_name name of the category you're looking for
+ * This will search through the categories within a given config file and search for a match.  The passed category_name can be a regular string (as opposed to a pointer of an existent string, lol)
+ * Browse config structure and check for category duplicity Return non-zero if found */
 int ast_category_exist(struct ast_config *config, char *category_name);
 
 #if defined(__cplusplus) || defined(c_plusplus)