res_phoneprov: Refactor phoneprov to allow pluggable config providers

This patch makes res_phoneprov more modular so other modules (like pjsip)
can provide configuration information instead of res_phoneprov relying solely
on users.conf and sip.conf.  To accomplish this a new ast_phoneprov public API
is now exposed which allows config providers to register themselves, set
defaults (server profile, etc) and add user extensions.

* ast_phoneprov_provider_register registers the provider and provides callbacks
  for loading default settings and loading users.
* ast_phoneprov_provider_unregister clears the defaults and users.
* ast_phoneprov_add_extension should be called once for each user/extension
  by the provider's load_users callback to add them.
* ast_phoneprov_delete_extension deletes one extension.
* ast_phoneprov_delete_extensions deletes all extensions for the provider.

Tested-by: George Joseph
Review: https://reviewboard.asterisk.org/r/3970/
........

Merged revisions 424963 from http://svn.asterisk.org/svn/asterisk/branches/12


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

configs/samples/phoneprov.conf.sample

@@ -1,4 +1,7 @@
 [general]
+; This section applies only to the default sip.conf/users.conf config provider
+; embedded in res_phoneprov.  Other providers may provide their own default settings.
+
 ; The default behavior of res_phoneprov will be to set the SERVER template variable to
 ; the IP address that the phone uses to contact the provisioning server and the
 ; SERVER_PORT variable to the bindport setting in sip.conf.  Unless you have a very
@@ -15,7 +18,8 @@ default_profile=polycom ; The default profile to use if none specified in users.
 ; with the provisioning server.  You can define either static files, or dynamically
 ; generated files that can have dynamic names and point to templates that variables
 ; can be substituted into.  You can also set arbitrary variables for the profiles
-; templates to have access to.  Example:
+; templates to have access to.  Profiles are shared across all config providers.
+; Example:
 
 ;[example]
 ;mime_type => application/octet-stream
@@ -25,7 +29,9 @@ default_profile=polycom ; The default profile to use if none specified in users.
 ;setvar => DB_CIDNAME=${ODBC_CID_NAME_LOOKUP(${USERNAME})}
 
 ; Dynamically generated files have a filename registered with variable substitution
-; with variables obtained while reading users.conf.
+; with variables obtained from various config providers.  The default provider
+; embedded in res_phoneprov reads users.conf.  Other providers will have their own
+; sources for the variables and may provide additional variables not listed here.
 
 ; Built in variables and the options in users.conf that they come from
 ;   MAC (macaddress)

include/asterisk/chanvars.h

@@ -33,6 +33,8 @@ struct ast_var_t {
 
 AST_LIST_HEAD_NOLOCK(varshead, ast_var_t);
 
+struct varshead *ast_var_list_create(void);
+void ast_var_list_destroy(struct varshead *head);
 #ifdef MALLOC_DEBUG
 struct ast_var_t *_ast_var_assign(const char *name, const char *value, const char *file, int lineno, const char *function);
 #define ast_var_assign(a,b)	_ast_var_assign(a,b,__FILE__,__LINE__,__PRETTY_FUNCTION__)
@@ -43,5 +45,21 @@ void ast_var_delete(struct ast_var_t *var);
 const char *ast_var_name(const struct ast_var_t *var);
 const char *ast_var_full_name(const struct ast_var_t *var);
 const char *ast_var_value(const struct ast_var_t *var);
+char *ast_var_find(const struct varshead *head, const char *name);
+struct varshead *ast_var_list_clone(struct varshead *head);
+
+#define AST_VAR_LIST_TRAVERSE(head, var) AST_LIST_TRAVERSE(head, var, entries)
+
+static inline void AST_VAR_LIST_INSERT_TAIL(struct varshead *head, struct ast_var_t *var) {
+	if (var) {
+		AST_LIST_INSERT_TAIL(head, var, entries);
+	}
+}
+
+static inline void AST_VAR_LIST_INSERT_HEAD(struct varshead *head, struct ast_var_t *var) {
+	if (var) {
+		AST_LIST_INSERT_HEAD(head, var, entries);
+	}
+}
 
 #endif /* _ASTERISK_CHANVARS_H */

include/asterisk/phoneprov.h

@@ -0,0 +1,119 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2014 - Fairview 5 Engineering, LLC
+ *
+ * George Joseph <george.joseph@fairview5.com>
+ *
+ * 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.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef _ASTERISK_PHONEPROV_H
+#define _ASTERISK_PHONEPROV_H
+
+#include "asterisk.h"
+#include "asterisk/inline_api.h"
+
+enum ast_phoneprov_std_variables {
+	AST_PHONEPROV_STD_MAC = 0,
+	AST_PHONEPROV_STD_PROFILE,
+	AST_PHONEPROV_STD_USERNAME,
+	AST_PHONEPROV_STD_DISPLAY_NAME,
+	AST_PHONEPROV_STD_SECRET,
+	AST_PHONEPROV_STD_LABEL,
+	AST_PHONEPROV_STD_CALLERID,
+	AST_PHONEPROV_STD_TIMEZONE,
+	AST_PHONEPROV_STD_LINENUMBER,
+	AST_PHONEPROV_STD_LINEKEYS,
+	AST_PHONEPROV_STD_SERVER,
+	AST_PHONEPROV_STD_SERVER_PORT,
+	AST_PHONEPROV_STD_SERVER_IFACE,
+	AST_PHONEPROV_STD_VOICEMAIL_EXTEN,
+	AST_PHONEPROV_STD_EXTENSION_LENGTH,
+	AST_PHONEPROV_STD_TZOFFSET,
+	AST_PHONEPROV_STD_DST_ENABLE,
+	AST_PHONEPROV_STD_DST_START_MONTH,
+	AST_PHONEPROV_STD_DST_START_MDAY,
+	AST_PHONEPROV_STD_DST_START_HOUR,
+	AST_PHONEPROV_STD_DST_END_MONTH,
+	AST_PHONEPROV_STD_DST_END_MDAY,
+	AST_PHONEPROV_STD_DST_END_HOUR,
+	AST_PHONEPROV_STD_VAR_LIST_LENGTH,	/* This entry must always be the last in the list */
+};
+
+/*! \brief Lookup table for the standard phoneprov variable names */
+extern const char *ast_phoneprov_std_variable_lookup[];
+
+/*!
+ * \brief Causes the provider to load its users.
+ *
+ * This function is called by phoneprov in response to a
+ * ast_phoneprov_provider_register call by the provider.
+ * It may also be called by phoneprov to request a reload in
+ * response to the res_phoneprov module being reloaded.
+ *
+ * \retval 0 if successful
+ * \retval non-zero if failure
+ */
+typedef int(*ast_phoneprov_load_users_cb)(void);
+
+/*!
+ * \brief Registers a config provider to phoneprov.
+ * \param provider_name The name of the provider
+ * \param load_users Callback that gathers user variables then loads them by
+ * calling ast_phoneprov_add_extension once for each extension.
+ *
+ * \retval 0 if successful
+ * \retval non-zero if failure
+ */
+int ast_phoneprov_provider_register(char *provider_name,
+	ast_phoneprov_load_users_cb load_users);
+
+/*!
+ * \brief Unegisters a config provider from phoneprov and frees its resources.
+ * \param provider_name The name of the provider
+ */
+void ast_phoneprov_provider_unregister(char *provider_name);
+
+/*!
+ * \brief Adds an extension
+ * \param provider_name The name of the provider
+ * \param defaults An ast_vat_t linked list of the extension's variables.
+ * The list is automatically cloned and it must contain at least MACADDRESS
+ * and USERNAME entries.
+ *
+ * \retval 0 if successful
+ * \retval non-zero if failure
+ */
+int ast_phoneprov_add_extension(char *provider_name, struct varshead *vars);
+
+/*!
+ * \brief Deletes an extension
+ * \param provider_name The name of the provider
+ * \param macaddress The mac address of the extension
+ */
+void ast_phoneprov_delete_extension(char *provider_name, char *macaddress);
+
+/*!
+ * \brief Deletes all extensions for this provider
+ * \param provider_name The name of the provider
+ */
+void ast_phoneprov_delete_extensions(char *provider_name);
+
+#endif /* _ASTERISK_PHONEPROV_H */
+
+#ifdef __cplusplus
+}
+#endif

main/chanvars.c

@@ -90,4 +90,67 @@ const char *ast_var_value(const struct ast_var_t *var)
 	return (var ? var->value : NULL);
 }
 
+char *ast_var_find(const struct varshead *head, const char *name)
+{
+	struct ast_var_t *var;
 
+	AST_LIST_TRAVERSE(head, var, entries) {
+		if (!strcmp(name, var->name)) {
+			return var->value;
+		}
+	}
+	return NULL;
+}
+
+struct varshead *ast_var_list_create(void)
+{
+	struct varshead *head;
+
+	head = ast_calloc(1, sizeof(*head));
+	if (!head) {
+		return NULL;
+	}
+	AST_LIST_HEAD_INIT_NOLOCK(head);
+	return head;
+}
+
+void ast_var_list_destroy(struct varshead *head)
+{
+	struct ast_var_t *var;
+
+	if (!head) {
+		return;
+	}
+
+	while ((var = AST_LIST_REMOVE_HEAD(head, entries))) {
+		ast_var_delete(var);
+	}
+
+	ast_free(head);
+}
+
+struct varshead *ast_var_list_clone(struct varshead *head)
+{
+	struct varshead *clone;
+	struct ast_var_t *var, *newvar;
+
+	if (!head) {
+		return NULL;
+	}
+
+	clone = ast_var_list_create();
+	if (!clone) {
+		return NULL;
+	}
+
+	AST_VAR_LIST_TRAVERSE(head, var) {
+		newvar = ast_var_assign(var->name, var->value);
+		if (!newvar) {
+			ast_var_list_destroy(clone);
+			return NULL;
+		}
+		AST_VAR_LIST_INSERT_TAIL(clone, newvar);
+	}
+
+	return clone;
+}

res/res_phoneprov.exports.in

@@ -0,0 +1,6 @@
+{
+	global:
+		LINKER_SYMBOL_PREFIXast_phoneprov_*;
+	local:
+		*;
+};