Const-ify the world (or at least a good part of it)

This patch adds 'const' tags to a number of Asterisk APIs where they are appropriate (where the API already demanded that the function argument not be modified, but the compiler was not informed of that fact). The list includes:

- CLI command handlers
- CLI command handler arguments
- AGI command handlers
- AGI command handler arguments
- Dialplan application handler arguments
- Speech engine API function arguments

In addition, various file-scope and function-scope constant arrays got 'const' and/or 'static' qualifiers where they were missing.

Review: https://reviewboard.asterisk.org/r/251/



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@196072 65c4cc65-6c06-0410-ace0-fbb531ad65f3

13 files changed, 59 insertions, 57 deletions

diff --git a/include/asterisk/abstract_jb.h b/include/asterisk/abstract_jb.h
index d884ce3d5..1e9508b71 100644
--- a/include/asterisk/abstract_jb.h
+++ b/include/asterisk/abstract_jb.h
@@ -84,7 +84,7 @@ struct ast_jb
 	/*! \brief Jitterbuffer configuration. */
 	struct ast_jb_conf conf;
 	/*! \brief Jitterbuffer implementation to be used. */
-	struct ast_jb_impl *impl;
+	const struct ast_jb_impl *impl;
 	/*! \brief Jitterbuffer object, passed to the implementation. */
 	void *jbobj;
 	/*! \brief The time the jitterbuffer was created. */
diff --git a/include/asterisk/agi.h b/include/asterisk/agi.h
index 9c7759576..9df9afe4d 100644
--- a/include/asterisk/agi.h
+++ b/include/asterisk/agi.h
@@ -39,22 +39,22 @@ typedef struct agi_state {
 } AGI;
 
 typedef struct agi_command {
-	char *cmda[AST_MAX_CMD_LEN];		/*!< Null terminated list of the words of the command */
+	const char * const cmda[AST_MAX_CMD_LEN];		/*!< Null terminated list of the words of the command */
 	/*! Handler for the command (channel, AGI state, # of arguments, argument list). 
 	    Returns RESULT_SHOWUSAGE for improper arguments */
-	int (*handler)(struct ast_channel *chan, AGI *agi, int argc, char *argv[]);
+	int (* const handler)(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[]);
 	/*! Summary of the command (< 60 characters) */
-	char *summary;
+	const char * const summary;
 	/*! Detailed usage information */
-	char *usage;
+	const char * const usage;
 	/*! Does this application run dead */
-	int dead;
+	const int dead;
 	/*! AGI command syntax description */
-	char *syntax;
+	const char * const syntax;
 	/*! See also content */
-	char *seealso;
+	const char * const seealso;
 	/*! Where the documentation come from. */
-	enum ast_doc_src docsrc;
+	const enum ast_doc_src docsrc;
 	/*! Pointer to module that registered the agi command */
 	struct ast_module *mod;
 	/*! Linked list pointer */
diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 8e0d86952..d442e5292 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -106,7 +106,7 @@ int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbd
 int ast_app_getdata(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout);
 
 /*! \brief Full version with audiofd and controlfd.  NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
-int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
+int ast_app_getdata_full(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
 
 /*!
  * \brief Set voicemail function callbacks
diff --git a/include/asterisk/cli.h b/include/asterisk/cli.h
index a02764dfa..f03a39ffe 100644
--- a/include/asterisk/cli.h
+++ b/include/asterisk/cli.h
@@ -97,7 +97,7 @@ void ast_cli(int fd, const char *fmt, ...)
 \code
 static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 {
-	static char *choices = { "one", "two", "three", NULL };
+	static const char * const choices = { "one", "two", "three", NULL };
 
         switch (cmd) {
         case CLI_INIT:
@@ -128,7 +128,7 @@ static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args
 /*! \brief calling arguments for new-style handlers. 
 * \arg \ref CLI_command_API
 */
-enum ast_cli_fn {
+enum ast_cli_command {
 	CLI_INIT = -2,		/* return the usage string */
 	CLI_GENERATE = -3,	/* behave as 'generator', remap argv to struct ast_cli_args */
 	CLI_HANDLER = -4,	/* run the normal handler */
@@ -136,27 +136,25 @@ enum ast_cli_fn {
 
 /* argument for new-style CLI handler */
 struct ast_cli_args {
-	int fd;
-	int argc;
-	char **argv;
+	const int fd;
+	const int argc;
+	const char * const *argv;
 	const char *line;	/* the current input line */
 	const char *word;	/* the word we want to complete */
-	int pos;		/* position of the word to complete */
-	int n;			/* the iteration count (n-th entry we generate) */
+	const int pos;		/* position of the word to complete */
+	const int n;		/* the iteration count (n-th entry we generate) */
 };
 
-struct ast_cli_entry;
-typedef char *(*cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
-
 /*! \brief descriptor for a cli entry. 
  * \arg \ref CLI_command_API
  */
 struct ast_cli_entry {
-	char * const cmda[AST_MAX_CMD_LEN];	/*!< words making up the command.
-						* set the first entry to NULL for a new-style entry. */
+	const char * const cmda[AST_MAX_CMD_LEN];	/*!< words making up the command.
+							 * set the first entry to NULL for a new-style entry.
+							 */
 
-	const char *summary; 			/*!< Summary of the command (< 60 characters) */
-	const char *usage; 			/*!< Detailed usage information */
+	const char * const summary; 			/*!< Summary of the command (< 60 characters) */
+	const char * usage; 				/*!< Detailed usage information */
 
 	int inuse; 				/*!< For keeping track of usage */
 	struct module *module;			/*!< module this belongs to */
@@ -166,7 +164,7 @@ struct ast_cli_entry {
 	 */
 	int args;				/*!< number of non-null entries in cmda */
 	char *command;				/*!< command, non-null for new-style entries */
-	cli_fn handler;
+	char *(*handler)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
 	/*! For linking */
 	AST_LIST_ENTRY(ast_cli_entry) list;
 };
@@ -183,7 +181,7 @@ struct ast_cli_entry {
   \code
     char *my_generate(const char *line, const char *word, int pos, int n)
     {
-        static char *choices = { "one", "two", "three", NULL };
+        static const char * const choices = { "one", "two", "three", NULL };
 	if (pos == 2)
         	return ast_cli_complete(word, choices, n);
 	else
@@ -191,7 +189,7 @@ struct ast_cli_entry {
     }
   \endcode
  */
-char *ast_cli_complete(const char *word, char *const choices[], int pos);
+char *ast_cli_complete(const char *word, const char * const choices[], int pos);
 
 /*! 
  * \brief Interprets a command
diff --git a/include/asterisk/extconf.h b/include/asterisk/extconf.h
index eeccc7b33..3aa15785b 100644
--- a/include/asterisk/extconf.h
+++ b/include/asterisk/extconf.h
@@ -185,7 +185,7 @@ int localized_pbx_load_module(void);
  * \version 1.6.1 renamed function from localized_context_create to localized_context_find_or_create
  */
 struct ast_context *localized_context_find_or_create(struct ast_context **extcontexts, void *tab, const char *name, const char *registrar);
-int localized_pbx_builtin_setvar(struct ast_channel *chan, void *data);
+int localized_pbx_builtin_setvar(struct ast_channel *chan, const void *data);
 int localized_context_add_ignorepat2(struct ast_context *con, const char *value, const char *registrar);
 int localized_context_add_switch2(struct ast_context *con, const char *value,
 								 const char *data, int eval, const char *registrar);
diff --git a/include/asterisk/features.h b/include/asterisk/features.h
index 9a666c743..a660b9e8a 100644
--- a/include/asterisk/features.h
+++ b/include/asterisk/features.h
@@ -49,7 +49,7 @@
 #define FEATURE_SENSE_CHAN	(1 << 0)
 #define FEATURE_SENSE_PEER	(1 << 1)
 
-typedef int (*ast_feature_operation)(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense, void *data);
+typedef int (*ast_feature_operation)(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, const char *code, int sense, void *data);
 
 /*! \brief main call feature structure */
 
@@ -136,7 +136,7 @@ void ast_unregister_feature(struct ast_call_feature *feature);
     \param char ptr of input code
     \retval ast_call_feature ptr to be set if found 
     \return result, was feature found or not */
-int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, char *code, struct ast_call_feature *feature);
+int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature);
 
 /*! \brief look for a call feature entry by its sname
 	\param name a string ptr, should match "automon", "blindxfer", "atxfer", etc. */
diff --git a/include/asterisk/image.h b/include/asterisk/image.h
index cfe511904..a3e2e015e 100644
--- a/include/asterisk/image.h
+++ b/include/asterisk/image.h
@@ -51,7 +51,7 @@ int ast_supports_images(struct ast_channel *chan);
  * \retval 0 on success
  * \retval -1 on error
  */
-int ast_send_image(struct ast_channel *chan, char *filename);
+int ast_send_image(struct ast_channel *chan, const char *filename);
 
 /*! 
  * \brief Make an image 
@@ -62,7 +62,7 @@ int ast_send_image(struct ast_channel *chan, char *filename);
  * \retval an ast_frame on success
  * \retval NULL on failure
  */
-struct ast_frame *ast_read_image(char *filename, const char *preflang, int format);
+struct ast_frame *ast_read_image(const char *filename, const char *preflang, int format);
 
 /*! 
  * \brief Register image format
diff --git a/include/asterisk/module.h b/include/asterisk/module.h
index c952db448..3ffe0b7d8 100644
--- a/include/asterisk/module.h
+++ b/include/asterisk/module.h
@@ -415,7 +415,7 @@ static void __restore_globals(void)
  * \retval 0 success
  * \retval -1 failure.
  */
-int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, void *),
+int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, const char *),
 				     const char *synopsis, const char *description, void *mod);
 
 /*! 
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 95a23f8cc..c2f999eb6 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -210,7 +210,7 @@ struct ast_app *pbx_findapp(const char *app);
  * \retval 0 success
  * \retval -1 failure
  */
-int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
+int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
 
 /*!
  * \brief Register a new context or find an existing one
@@ -976,14 +976,14 @@ void pbx_builtin_clear_globals(void);
 /*!\brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
  * \note Will lock the channel.
  */
-int pbx_builtin_setvar(struct ast_channel *chan, void *data);
+int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
 
 /*!\brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
  * \note Will lock the channel.
  */
-int pbx_builtin_setvar_multiple(struct ast_channel *chan, void *data);
+int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
 
-int pbx_builtin_raise_exception(struct ast_channel *chan, void *data);
+int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
 
 /*! @name Substitution routines, using static string buffers
  * @{ */
diff --git a/include/asterisk/speech.h b/include/asterisk/speech.h
index 54e9c69ac..cb167d5b5 100644
--- a/include/asterisk/speech.h
+++ b/include/asterisk/speech.h
@@ -78,13 +78,13 @@ struct ast_speech_engine {
 	/*! Destroy any data set on the speech structure by the engine */
 	int (*destroy)(struct ast_speech *speech);
 	/*! Load a local grammar on the speech structure */
-	int (*load)(struct ast_speech *speech, char *grammar_name, char *grammar);
+	int (*load)(struct ast_speech *speech, const char *grammar_name, const char *grammar);
 	/*! Unload a local grammar */
-	int (*unload)(struct ast_speech *speech, char *grammar_name);
+	int (*unload)(struct ast_speech *speech, const char *grammar_name);
 	/*! Activate a loaded grammar */
-	int (*activate)(struct ast_speech *speech, char *grammar_name);
+	int (*activate)(struct ast_speech *speech, const char *grammar_name);
 	/*! Deactivate a loaded grammar */
-	int (*deactivate)(struct ast_speech *speech, char *grammar_name);
+	int (*deactivate)(struct ast_speech *speech, const char *grammar_name);
 	/*! Write audio to the speech engine */
 	int (*write)(struct ast_speech *speech, void *data, int len);
 	/*! Signal DTMF was received */
@@ -92,7 +92,7 @@ struct ast_speech_engine {
 	/*! Prepare engine to accept audio */
 	int (*start)(struct ast_speech *speech);
 	/*! Change an engine specific setting */
-	int (*change)(struct ast_speech *speech, char *name, const char *value);
+	int (*change)(struct ast_speech *speech, const char *name, const char *value);
 	/*! Change the type of results we want back */
 	int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
 	/*! Try to get results */
@@ -117,13 +117,13 @@ struct ast_speech_result {
 };
 
 /*! \brief Activate a grammar on a speech structure */
-int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name);
+int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name);
 /*! \brief Deactivate a grammar on a speech structure */
-int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name);
+int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name);
 /*! \brief Load a grammar on a speech structure (not globally) */
-int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar);
+int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar);
 /*! \brief Unload a grammar */
-int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name);
+int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name);
 /*! \brief Get speech recognition results */
 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
 /*! \brief Free a set of results */
@@ -131,7 +131,7 @@ int ast_speech_results_free(struct ast_speech_result *result);
 /*! \brief Indicate to the speech engine that audio is now going to start being written */
 void ast_speech_start(struct ast_speech *speech);
 /*! \brief Create a new speech structure */
-struct ast_speech *ast_speech_new(char *engine_name, int formats);
+struct ast_speech *ast_speech_new(const char *engine_name, int formats);
 /*! \brief Destroy a speech structure */
 int ast_speech_destroy(struct ast_speech *speech);
 /*! \brief Write audio to the speech engine */
@@ -139,7 +139,7 @@ int ast_speech_write(struct ast_speech *speech, void *data, int len);
 /*! \brief Signal to the engine that DTMF was received */
 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf);
 /*! \brief Change an engine specific attribute */
-int ast_speech_change(struct ast_speech *speech, char *name, const char *value);
+int ast_speech_change(struct ast_speech *speech, const char *name, const char *value);
 /*! \brief Change the type of results we want */
 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
 /*! \brief Change state of a speech structure */
@@ -147,7 +147,7 @@ int ast_speech_change_state(struct ast_speech *speech, int state);
 /*! \brief Register a speech recognition engine */
 int ast_speech_register(struct ast_speech_engine *engine);
 /*! \brief Unregister a speech recognition engine */
-int ast_speech_unregister(char *engine_name);
+int ast_speech_unregister(const char *engine_name);
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 43ba361f4..ae58af3ef 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -281,7 +281,7 @@ int attribute_pure ast_false(const char *val);
  * string.  It will also place a space in the result buffer in between each
  * string from 'w'.
 */
-void ast_join(char *s, size_t len, char * const w[]);
+void ast_join(char *s, size_t len, const char * const w[]);
 
 /*
   \brief Parse a time (integer) string.
@@ -454,7 +454,7 @@ void ast_str_trim_blanks(struct ast_str *buf),
  * \param buf A pointer to the ast_str structure.
  */
 AST_INLINE_API(
-size_t attribute_pure ast_str_strlen(struct ast_str *buf),
+size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
 {
 	return buf->__AST_STR_USED;
 }
@@ -465,7 +465,7 @@ size_t attribute_pure ast_str_strlen(struct ast_str *buf),
  * \retval Current maximum length of the buffer.
  */
 AST_INLINE_API(
-size_t attribute_pure ast_str_size(struct ast_str *buf),
+size_t attribute_pure ast_str_size(const struct ast_str *buf),
 {
 	return buf->__AST_STR_LEN;
 }
@@ -476,9 +476,13 @@ size_t attribute_pure ast_str_size(struct ast_str *buf),
  * \retval A pointer to the enclosed string.
  */
 AST_INLINE_API(
-char * attribute_pure ast_str_buffer(struct ast_str *buf),
+char * attribute_pure ast_str_buffer(const struct ast_str *buf),
 {
-	return buf->__AST_STR_STR;
+	/* for now, cast away the const qualifier on the pointer
+	 * being returned; eventually, it should become truly const
+	 * and only be modified via accessor functions
+	 */
+	return (char *) buf->__AST_STR_STR;
 }
 )
 
diff --git a/include/asterisk/taskprocessor.h b/include/asterisk/taskprocessor.h
index 6929b8fb4..aa37477dd 100644
--- a/include/asterisk/taskprocessor.h
+++ b/include/asterisk/taskprocessor.h
@@ -73,7 +73,7 @@ enum ast_tps_options {
  * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist
  * \since 1.6.1
  */
-struct ast_taskprocessor *ast_taskprocessor_get(char *name, enum ast_tps_options create);
+struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create);
 
 /*! \brief Unreference the specified taskprocessor and its reference count will decrement.
  *
diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index aac5a4651..cd1c7fa6b 100644
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -215,9 +215,9 @@ struct ast_hostent {
 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
 
 /*!  \brief Produces MD5 hash based on input string */
-void ast_md5_hash(char *output, char *input);
+void ast_md5_hash(char *output, const char *input);
 /*! \brief Produces SHA1 hash based on input string */
-void ast_sha1_hash(char *output, char *input);
+void ast_sha1_hash(char *output, const char *input);
 
 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);