[asterisk-commits] file: trunk r380069 - in /trunk: configs/ include/asterisk/ main/ res/ tests/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Fri Jan 25 08:01:09 CST 2013
Author: file
Date: Fri Jan 25 08:01:04 2013
New Revision: 380069
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=380069
Log:
Merge the sorcery data access layer API.
Sorcery is a unifying data access layer which provides a pluggable mechanism to allow
object creation, retrieval, updating, and deletion using different backends (or wizards).
This is a fancy way of saying "one interface to rule them all" where them is configuration,
realtime, and anything else that comes along.
Review: https://reviewboard.asterisk.org/r/2259/
Added:
trunk/configs/sorcery.conf.sample (with props)
trunk/configs/test_sorcery.conf.sample (with props)
trunk/include/asterisk/sorcery.h (with props)
trunk/main/sorcery.c (with props)
trunk/res/res_sorcery_config.c (with props)
trunk/res/res_sorcery_memory.c (with props)
trunk/tests/test_sorcery.c (with props)
Modified:
trunk/main/asterisk.c
Added: trunk/configs/sorcery.conf.sample
URL: http://svnview.digium.com/svn/asterisk/trunk/configs/sorcery.conf.sample?view=auto&rev=380069
==============================================================================
--- trunk/configs/sorcery.conf.sample (added)
+++ trunk/configs/sorcery.conf.sample Fri Jan 25 08:01:04 2013
@@ -1,0 +1,50 @@
+; Sample configuration file for Sorcery Data Access Layer
+
+;
+; Wizards
+;
+; Wizards are the persistence mechanism for objects. They are loaded as Asterisk modules and register
+; themselves with the sorcery core. All implementation specific details of how objects are persisted is isolated
+; within wizards.
+;
+
+;
+; Caching
+;
+; A wizard can optionally be marked as an object cache by adding "/cache" to the object type within the mapping.
+; If an object is returned from a non-object cache it is immediately given to the cache to be created. Multiple
+; object caches can be configured for a single object type.
+;
+
+;
+; Object Type Mappings
+;
+; To allow configuration of where and how an object is persisted object mappings can be defined within this file
+; on a per-module basis. The mapping consists of the object type, options, wizard name, and wizard configuration
+; data. This has the following format:
+;
+; object type [/options] = wizard name, wizard configuration data
+;
+; For example to configure an in-memory wizard for the 'bob' object type:
+;
+; bob = memory
+;
+; Or to configure the object type 'joe' from a configuration file:
+;
+; joe = config,joe.conf
+;
+; Note that an object type can have multiple mappings defined. Each mapping will be consulted in the order in which
+; it appears within the configuration file. This means that if you are configuring a wizard as a cache it should
+; appear as the first mapping so the cache is consulted before all other mappings.
+;
+
+;
+; The following object mappings are used by the unit test to test certain functionality of sorcery.
+;
+[test_sorcery]
+test=memory
+
+[test_sorcery_cache]
+test/cache=test
+test=memory
+
Propchange: trunk/configs/sorcery.conf.sample
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: trunk/configs/sorcery.conf.sample
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: trunk/configs/sorcery.conf.sample
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: trunk/configs/test_sorcery.conf.sample
URL: http://svnview.digium.com/svn/asterisk/trunk/configs/test_sorcery.conf.sample?view=auto&rev=380069
==============================================================================
--- trunk/configs/test_sorcery.conf.sample (added)
+++ trunk/configs/test_sorcery.conf.sample Fri Jan 25 08:01:04 2013
@@ -1,0 +1,14 @@
+; This is a res_sorcery_config compatible file for the sorcery unit tests
+
+[hey]
+bob=98
+joe=41
+
+[hey2]
+type=zombies
+bob=97
+joe=40
+
+[hey3]
+bob=96
+joe=39
Propchange: trunk/configs/test_sorcery.conf.sample
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: trunk/configs/test_sorcery.conf.sample
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: trunk/configs/test_sorcery.conf.sample
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: trunk/include/asterisk/sorcery.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/sorcery.h?view=auto&rev=380069
==============================================================================
--- trunk/include/asterisk/sorcery.h (added)
+++ trunk/include/asterisk/sorcery.h Fri Jan 25 08:01:04 2013
@@ -1,0 +1,537 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012 - 2013, Digium, Inc.
+ *
+ * Joshua Colp <jcolp at digium.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.
+ */
+
+/*! \file
+ * \brief Sorcery Data Access Layer API
+ * \author Joshua Colp <jcolp at digium.com>
+ * \ref AstSorcery
+ */
+
+/*!
+ * \page AstSorcery Data Access Layer API
+ *
+ * Sorcery is a unifying data access layer which utilizes the configuration framework,
+ * realtime, and astdb to allow object creation, retrieval, updating, and deletion.
+ *
+ * \par Initialization
+ *
+ * Usage of sorcery is accomplished by first opening a sorcery structure. This structure holds
+ * all information about the object types, object fields, and object mappings. All API functions
+ * require the sorcery structure to operate. When sorcery is no longer needed the structure can
+ * be unreferenced using \ref ast_sorcery_unref
+ *
+ * Once opened the sorcery structure must have object mappings applied to it. This maps the
+ * object types to their respective wizards (object storage modules). If the developer would like
+ * to allow the user to configure this using the sorcery.conf configuration file the
+ * \ref ast_sorcery_apply_config API call can be used to read in the configuration file and apply the
+ * mappings. If the storage of the object types are such that a default wizard can be used this can
+ * be applied using the \ref ast_sorcery_apply_default API call. Note that the default mappings will not
+ * override configured mappings. They are only used in the case where no configured mapping exists.
+ *
+ * Configuring object mappings implicitly creates a basic version of an object type. The object type
+ * must be fully registered, however, using the \ref ast_sorcery_object_type_register API call before any
+ * objects of the type can be allocated, created, or retrieved.
+ *
+ * Once the object type itself has been fully registered the individual fields within the object must
+ * be registered using the \ref ast_sorcery_object_field_register API call. Note that not all fields *need*
+ * be registered. Only fields that should be accessible using the sorcery API have to be registered.
+ *
+ * \par Creating Objects
+ *
+ * Before an object can be created within the sorcery API it must first be allocated using the
+ * \ref ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific
+ * details, and applies default values to the object. A unique identifier can optionally be specified
+ * when allocating an object. If it is not provided one will be automatically generated. Allocating
+ * an object does not create it within any object storage mechanisms that are configured for the
+ * object type. Creation must explicitly be done using the \ref ast_sorcery_create API call. This API call
+ * passes the object to each configured object storage mechanism for the object type until one
+ * successfully persists the object.
+ *
+ * \par Retrieving Objects
+ *
+ * To retrieve a single object using its unique identifier the \ref ast_sorcery_retrieve_by_id API call
+ * can be used.
+ *
+ * To retrieve potentially multiple objects using specific fields the \ref ast_sorcery_retrieve_by_fields
+ * API call can be used. The behavior of this API call is controlled using different flags. If the
+ * AST_RETRIEVE_FLAG_MULTIPLE flag is used a container will be returned which contains all matching objects.
+ * To retrieve all objects the AST_RETRIEVE_FLAG_ALL flag can be specified. Note that when specifying this flag
+ * you do not need to pass any fields.
+ *
+ * Both API calls return shared objects. Modification of the object can not occur until it has been copied.
+ *
+ * \par Updating Objects
+ *
+ * As retrieved objects may be shared the first step to updating the object with new details is creating a
+ * copy using the \ref ast_sorcery_copy API call. This will return a new object which is specific to the caller.
+ * Any field within the object may be modified as needed. Once changes are done the changes can be committed
+ * using the \ref ast_sorcery_update API call. Note that as the copied object is specific to the caller it must
+ * be unreferenced after use.
+ *
+ * \par Deleting Objects
+ *
+ * To delete an object simply call the \ref ast_sorcery_delete API call with an object retrieved using the
+ * ast_sorcery_retrieve_by_* API calls or a copy returned from \ref ast_sorcery_copy.
+ */
+
+#ifndef _ASTERISK_SORCERY_H
+#define _ASTERISK_SORCERY_H
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+#include "asterisk/config_options.h"
+#include "asterisk/uuid.h"
+
+/*! \brief Maximum size of an object type */
+#define MAX_OBJECT_TYPE 64
+
+/*!
+ * \brief Retrieval flags
+ */
+enum ast_sorcery_retrieve_flags {
+ /*! \brief Default retrieval flags */
+ AST_RETRIEVE_FLAG_DEFAULT = 0,
+
+ /*! \brief Return all matching objects */
+ AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
+
+ /*! \brief Perform no matching, return all objects */
+ AST_RETRIEVE_FLAG_ALL = (1 << 1),
+};
+
+/*! \brief Forward declaration for the sorcery main structure */
+struct ast_sorcery;
+
+/*!
+ * \brief A callback function for translating a value into a string
+ *
+ * \param obj Object to get value from
+ * \param args Where the field is
+ * \param buf Pointer to the buffer that the handler has created which contains the field value
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
+
+/*!
+ * \brief A callback function for performing a transformation on an object set
+ *
+ * \param set The existing object set
+ *
+ * \retval non-NULL new object set if changed
+ * \retval NULL if no changes present
+ *
+ * \note The returned ast_variable list must be *new*. You can not return the input set.
+ */
+typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
+
+/*!
+ * \brief A callback function for when an object set is successfully applied to an object
+ *
+ * \param sorcery Sorcery structure in use
+ * \param obj The object itself
+ */
+typedef void (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
+
+/*! \brief Interface for a sorcery wizard */
+struct ast_sorcery_wizard {
+ /*! \brief Name of the wizard */
+ const char *name;
+
+ /*! \brief Pointer to the Asterisk module this wizard is implemented by */
+ struct ast_module *module;
+
+ /*! \brief Callback for opening a wizard */
+ void *(*open)(const char *data);
+
+ /*! \brief Optional callback for loading persistent objects */
+ void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
+
+ /*! \brief Optional callback for reloading persistent objects */
+ void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
+
+ /*! \brief Callback for creating an object */
+ int (*create)(void *data, void *object);
+
+ /*! \brief Callback for retrieving an object using an id */
+ void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
+
+ /*! \brief Optional callback for retrieving an object using fields */
+ void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
+
+ /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
+ void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
+
+ /*! \brief Callback for updating an object */
+ int (*update)(void *data, void *object);
+
+ /*! \brief Callback for deleting an object */
+ int (*delete)(void *data, void *object);
+
+ /*! \brief Callback for closing a wizard */
+ void (*close)(void *data);
+};
+
+/*! \brief Structure which contains details about a sorcery object */
+struct ast_sorcery_object_details {
+ /*! \brief Unique identifier of this object */
+ char id[AST_UUID_STR_LEN];
+
+ /*! \brief Type of object */
+ char type[MAX_OBJECT_TYPE];
+};
+
+/*! \brief Macro which must be used at the beginning of each sorcery capable object */
+#define SORCERY_OBJECT(details) \
+struct { \
+ struct ast_sorcery_object_details details; \
+} \
+
+/*!
+ * \brief Initialize the sorcery API
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_init(void);
+
+/*!
+ * \brief Register a sorcery wizard
+ *
+ * \param interface Pointer to a wizard interface
+ * \param module Pointer to the module implementing the interface
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
+
+/*!
+ * \brief See \ref __ast_sorcery_wizard_register()
+ */
+#define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, ast_module_info ? ast_module_info->self : NULL)
+
+/*!
+ * \brief Unregister a sorcery wizard
+ *
+ * \param interface Pointer to the wizard interface
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
+
+/*!
+ * \brief Open a new sorcery structure
+ *
+ * \retval non-NULL success
+ * \retval NULL if allocation failed
+ */
+struct ast_sorcery *ast_sorcery_open(void);
+
+/*!
+ * \brief Apply configured wizard mappings
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param name Name of the category to use within the configuration file, normally the module name
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name);
+
+/*!
+ * \brief Apply default object wizard mappings
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object to apply to
+ * \param name Name of the wizard to use
+ * \param data Data to be passed to wizard
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note This should be called *after* applying configuration sourced mappings
+ *
+ * \note Only a single default can exist per object type
+ */
+int ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *name, const char *data);
+
+/*!
+ * \brief Register an object type
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param alloc Required object allocation callback
+ * \param transform Optional transformation callback
+ * \param apply Optional object set apply callback
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply);
+
+/*!
+ * \brief Register a field within an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param name Name of the field
+ * \param default_val Default value of the field
+ * \param opt_type Option type
+ * \param flags Option type specific flags
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type, const char *name, const char *default_val, enum aco_option_type opt_type,
+ aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, size_t argc, ...);
+
+/*!
+ * \brief Register a field within an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param name Name of the field
+ * \param default_val Default value of the field
+ * \param opt_type Option type
+ * \param flags Option type specific flags
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+#define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
+ __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
+
+/*!
+ * \brief Register a field within an object with custom handlers
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param name Name of the field
+ * \param default_val Default value of the field
+ * \param config_handler Custom configuration handler
+ * \param sorcery_handler Custom sorcery handler
+ * \param flags Option type specific flags
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+#define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, flags, ...) \
+ __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
+
+/*!
+ * \brief Inform any wizards to load persistent objects
+ *
+ * \param sorcery Pointer to a sorcery structure
+ */
+void ast_sorcery_load(const struct ast_sorcery *sorcery);
+
+/*!
+ * \brief Inform any wizards to reload persistent objects
+ *
+ * \param sorcery Pointer to a sorcery structure
+ */
+void ast_sorcery_reload(const struct ast_sorcery *sorcery);
+
+/*!
+ * \brief Increase the reference count of a sorcery structure
+ *
+ * \param sorcery Pointer to a sorcery structure
+ */
+void ast_sorcery_ref(struct ast_sorcery *sorcery);
+
+/*!
+ * \brief Create an object set (KVP list) for an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param object Pointer to a sorcery object
+ *
+ * \retval non-NULL success
+ * \retval NULL if error occurred
+ *
+ * \note The returned ast_variable list must be destroyed using ast_variables_destroy
+ */
+struct ast_variable *ast_sorcery_objectset_create(const struct ast_sorcery *sorcery, const void *object);
+
+/*!
+ * \brief Apply an object set (KVP list) to an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param object Pointer to a sorcery object
+ * \param objectset Object set itself
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
+ * applied object set.
+ */
+int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
+
+/*!
+ * \brief Create a changeset given two object sets
+ *
+ * \param original Original object set
+ * \param modified Modified object set
+ * \param changes Pointer to hold any changes between the object sets
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note The returned ast_variable list must be destroyed using ast_variables_destroy
+ */
+int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
+
+/*!
+ * \brief Allocate an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object to allocate
+ * \param id Optional unique identifier, if none is provided one will be generated
+ *
+ * \retval non-NULL success
+ * \retval NULL failure
+ */
+void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
+
+/*!
+ * \brief Create a copy of an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param object Existing object
+ *
+ * \retval non-NULL success
+ * \retval NULL failure
+ */
+void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
+
+/*!
+ * \brief Create a changeset of two objects
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param original Original object
+ * \param modified Modified object
+ * \param changes Pointer which will be populated with changes if any exist
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note The returned ast_variable list must be destroyed using ast_variables_destroy
+ *
+ * \note While the objects must be of the same type they do not have to be the same object
+ */
+int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
+
+/*!
+ * \brief Create and potentially persist an object using an available wizard
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param object Pointer to a sorcery object
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
+
+/*!
+ * \brief Retrieve an object using its unique identifier
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object to retrieve
+ * \param id Unique object identifier
+ *
+ * \retval non-NULL if found
+ * \retval NULL if not found
+ */
+void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
+
+/*!
+ * \brief Retrieve an object or multiple objects using specific fields
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object to retrieve
+ * \param flags Flags to control behavior
+ * \param fields Optional jbject fields and values to match against
+ *
+ * \retval non-NULL if found
+ * \retval NULL if not found
+ *
+ * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
+ * ao2_container that must be unreferenced after use.
+ *
+ * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
+ * of the given type.
+ */
+void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
+
+/*!
+ * \brief Update an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param object Pointer to a sorcery object
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
+
+/*!
+ * \brief Delete an object
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param object Pointer to a sorcery object
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
+
+/*!
+ * \brief Decrease the reference count of a sorcery structure
+ *
+ * \param sorcery Pointer to a sorcery structure
+ */
+void ast_sorcery_unref(struct ast_sorcery *sorcery);
+
+/*!
+ * \brief Get the unique identifier of a sorcery object
+ *
+ * \param object Pointer to a sorcery object
+ *
+ * \retval unique identifier
+ */
+const char *ast_sorcery_object_get_id(const void *object);
+
+/*!
+ * \brief Get the type of a sorcery object
+ *
+ * \param object Pointer to a sorcery object
+ *
+ * \retval type of object
+ */
+const char *ast_sorcery_object_get_type(const void *object);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* _ASTERISK_SORCERY_H */
Propchange: trunk/include/asterisk/sorcery.h
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: trunk/include/asterisk/sorcery.h
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: trunk/include/asterisk/sorcery.h
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: trunk/main/asterisk.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/asterisk.c?view=diff&rev=380069&r1=380068&r2=380069
==============================================================================
--- trunk/main/asterisk.c (original)
+++ trunk/main/asterisk.c Fri Jan 25 08:01:04 2013
@@ -239,6 +239,7 @@
#include "asterisk/format.h"
#include "asterisk/aoc.h"
#include "asterisk/uuid.h"
+#include "asterisk/sorcery.h"
#include "../defaults.h"
@@ -4116,6 +4117,11 @@
ast_aoc_cli_init();
ast_uuid_init();
+ if (ast_sorcery_init()) {
+ printf("%s", term_quit());
+ exit(1);
+ }
+
ast_makesocket();
sigemptyset(&sigs);
sigaddset(&sigs, SIGHUP);
Added: trunk/main/sorcery.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/sorcery.c?view=auto&rev=380069
==============================================================================
--- trunk/main/sorcery.c (added)
+++ trunk/main/sorcery.c Fri Jan 25 08:01:04 2013
@@ -1,0 +1,965 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012 - 2013, Digium, Inc.
+ *
+ * Joshua Colp <jcolp at digium.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.
+ */
+
+/*! \file
+ *
+ * \brief Sorcery Data Access Layer API
+ *
+ * \author Joshua Colp <jcolp at digium.com>
+ */
+
+/*** MODULEINFO
+ <support_level>core</support_level>
+ ***/
+
+#include "asterisk.h"
+
+ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
+
+#include "asterisk/logger.h"
+#include "asterisk/sorcery.h"
+#include "asterisk/astobj2.h"
+#include "asterisk/strings.h"
+#include "asterisk/config_options.h"
+#include "asterisk/netsock2.h"
+#include "asterisk/module.h"
+
+/*! \brief Number of buckets for wizards (should be prime for performance reasons) */
+#define WIZARD_BUCKETS 7
+
+/*! \brief Number of buckets for types (should be prime for performance reasons) */
+#define TYPE_BUCKETS 53
+
+/*! \brief Maximum length of an object field name */
+#define MAX_OBJECT_FIELD 128
+
+/*! \brief Structure for registered object type */
+struct ast_sorcery_object_type {
+ /*! \brief Unique name of the object type */
+ char name[MAX_OBJECT_TYPE];
+
+ /*! \brief Optional transformation callback */
+ sorcery_transform_handler transform;
+
+ /*! \brief Optional object set apply callback */
+ sorcery_apply_handler apply;
+
+ /*! \brief Wizard instances */
+ struct ao2_container *wizards;
+
+ /*! \brief Object fields */
+ struct ao2_container *fields;
+
+ /*! \brief Configuration framework general information */
+ struct aco_info *info;
+
+ /*! \brief Configuration framework file information */
+ struct aco_file *file;
+
+ /*! \brief Type details */
+ struct aco_type type;
+};
+
+/*! \brief Structure for registered object field */
+struct ast_sorcery_object_field {
+ /*! \brief Name of the field */
+ char name[MAX_OBJECT_FIELD];
+
+ /*! \brief Callback function for translation */
+ sorcery_field_handler handler;
+
+ /*! \brief Position of the field */
+ intptr_t args[];
+};
+
+/*! \brief Structure for a wizard instance which operates on objects */
+struct ast_sorcery_object_wizard {
+ /*! \brief Wizard interface itself */
+ struct ast_sorcery_wizard *wizard;
+
+ /*! \brief Unique data for the wizard */
+ void *data;
+
+ /*! \brief Wizard is acting as an object cache */
+ unsigned int caching:1;
+};
+
+/*! \brief Full structure for sorcery */
+struct ast_sorcery {
+ /*! \brief Container for known object types */
+ struct ao2_container *types;
+};
+
+/*! \brief Structure for passing load/reload details */
+struct sorcery_load_details {
+ /*! \brief Sorcery structure in use */
+ const struct ast_sorcery *sorcery;
+
+ /*! \brief Type of object being loaded */
+ const char *type;
+
+ /*! \brief Whether this is a reload or not */
+ unsigned int reload:1;
+};
+
+/*! \brief Registered sorcery wizards */
+struct ao2_container *wizards;
+
+static int int_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ int *field = (int *)(obj + args[0]);
+ return (ast_asprintf(buf, "%d", *field) < 0) ? -1 : 0;
+}
+
+static int uint_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ unsigned int *field = (unsigned int *)(obj + args[0]);
+ return (ast_asprintf(buf, "%u", *field) < 0) ? -1 : 0;
+}
+
+static int double_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ double *field = (double *)(obj + args[0]);
+ return (ast_asprintf(buf, "%f", *field) < 0) ? -1 : 0;
+}
+
+static int stringfield_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ ast_string_field *field = (const char **)(obj + args[0]);
+ return !(*buf = ast_strdup(*field)) ? -1 : 0;
+}
+
+static int bool_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ unsigned int *field = (unsigned int *)(obj + args[0]);
+ return !(*buf = ast_strdup(*field ? "true" : "false")) ? -1 : 0;
+}
+
+static int sockaddr_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ struct ast_sockaddr *field = (struct ast_sockaddr *)(obj + args[0]);
+ return !(*buf = ast_strdup(ast_sockaddr_stringify(field))) ? -1 : 0;
+}
+
+static int noop_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ return 0;
+}
+
+static int chararray_handler_fn(const void *obj, const intptr_t *args, char **buf)
+{
+ char *field = (char *)(obj + args[0]);
+ return !(*buf = ast_strdup(field)) ? -1 : 0;
+}
+
+static sorcery_field_handler sorcery_field_default_handler(enum aco_option_type type)
+{
+ switch(type) {
+ case OPT_BOOL_T: return bool_handler_fn;
+ case OPT_CHAR_ARRAY_T: return chararray_handler_fn;
+ case OPT_DOUBLE_T: return double_handler_fn;
+ case OPT_INT_T: return int_handler_fn;
+ case OPT_NOOP_T: return noop_handler_fn;
+ case OPT_SOCKADDR_T: return sockaddr_handler_fn;
+ case OPT_STRINGFIELD_T: return stringfield_handler_fn;
+ case OPT_UINT_T: return uint_handler_fn;
+
+ default:
+ case OPT_CUSTOM_T: return NULL;
+ }
+
+ return NULL;
+}
+
+/*! \brief Hashing function for sorcery wizards */
+static int sorcery_wizard_hash(const void *obj, const int flags)
+{
+ const struct ast_sorcery_wizard *wizard = obj;
+ const char *name = obj;
+
+ return ast_str_hash(flags & OBJ_KEY ? name : wizard->name);
+}
+
+/*! \brief Comparator function for sorcery wizards */
+static int sorcery_wizard_cmp(void *obj, void *arg, int flags)
+{
+ struct ast_sorcery_wizard *wizard1 = obj, *wizard2 = arg;
+ const char *name = arg;
+
+ return !strcmp(wizard1->name, flags & OBJ_KEY ? name : wizard2->name) ? CMP_MATCH | CMP_STOP : 0;
+}
+
+int ast_sorcery_init(void)
+{
+ ast_assert(wizards == NULL);
+
+ if (!(wizards = ao2_container_alloc(WIZARD_BUCKETS, sorcery_wizard_hash, sorcery_wizard_cmp))) {
+ return -1;
+ }
+
+ return 0;
+}
+
+int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module)
+{
+ struct ast_sorcery_wizard *wizard;
+ int res = -1;
+
+ ast_assert(!ast_strlen_zero(interface->name));
+
+ ao2_lock(wizards);
+
+ if ((wizard = ao2_find(wizards, interface->name, OBJ_KEY | OBJ_NOLOCK))) {
+ ast_log(LOG_WARNING, "Attempted to register sorcery wizard '%s' twice\n",
+ interface->name);
+ goto done;
+ }
+
+ if (!(wizard = ao2_alloc(sizeof(*wizard), NULL))) {
+ goto done;
+ }
+
+ *wizard = *interface;
+ wizard->module = module;
+
+ ao2_link_flags(wizards, wizard, OBJ_NOLOCK);
+ res = 0;
+
+ ast_verb(2, "Sorcery registered wizard '%s'\n", interface->name);
+
+done:
+ ao2_cleanup(wizard);
+ ao2_unlock(wizards);
+
+ return res;
+}
+
+int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface)
+{
+ RAII_VAR(struct ast_sorcery_wizard *, wizard, ao2_find(wizards, interface->name, OBJ_KEY | OBJ_UNLINK), ao2_cleanup);
+
+ if (wizard) {
+ ast_verb(2, "Sorcery unregistered wizard '%s'\n", interface->name);
+ return 0;
+ } else {
+ return -1;
+ }
+}
+
+/*! \brief Destructor called when sorcery structure is destroyed */
+static void sorcery_destructor(void *obj)
+{
+ struct ast_sorcery *sorcery = obj;
+
+ ao2_cleanup(sorcery->types);
+}
+
+/*! \brief Hashing function for sorcery types */
+static int sorcery_type_hash(const void *obj, const int flags)
+{
+ const struct ast_sorcery_object_type *type = obj;
+ const char *name = obj;
+
+ return ast_str_hash(flags & OBJ_KEY ? name : type->name);
+}
+
+/*! \brief Comparator function for sorcery types */
+static int sorcery_type_cmp(void *obj, void *arg, int flags)
+{
+ struct ast_sorcery_object_type *type1 = obj, *type2 = arg;
+ const char *name = arg;
+
+ return !strcmp(type1->name, flags & OBJ_KEY ? name : type2->name) ? CMP_MATCH | CMP_STOP : 0;
+}
+
+struct ast_sorcery *ast_sorcery_open(void)
+{
+ struct ast_sorcery *sorcery;
+
+ if (!(sorcery = ao2_alloc(sizeof(*sorcery), sorcery_destructor))) {
+ return NULL;
+ }
+
+ if (!(sorcery->types = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, TYPE_BUCKETS, sorcery_type_hash, sorcery_type_cmp))) {
+ ao2_ref(sorcery, -1);
+ sorcery = NULL;
+ }
+
+ return sorcery;
+}
+
+/*! \brief Destructor function for object types */
+static void sorcery_object_type_destructor(void *obj)
+{
+ struct ast_sorcery_object_type *object_type = obj;
+
+ ao2_cleanup(object_type->wizards);
+ ao2_cleanup(object_type->fields);
+
+ if (object_type->info) {
+ aco_info_destroy(object_type->info);
+ ast_free(object_type->info);
+ }
+
+ ast_free(object_type->file);
+}
+
+/*! \brief Internal function which allocates an object type structure */
+static struct ast_sorcery_object_type *sorcery_object_type_alloc(const char *type)
+{
+ struct ast_sorcery_object_type *object_type;
+
+ if (!(object_type = ao2_alloc(sizeof(*object_type), sorcery_object_type_destructor))) {
+ return NULL;
+ }
+
+ /* Order matters for object wizards */
+ if (!(object_type->wizards = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, 1, NULL, NULL))) {
+ ao2_ref(object_type, -1);
+ return NULL;
+ }
+
+ if (!(object_type->fields = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, 1, NULL, NULL))) {
+ ao2_ref(object_type, -1);
+ return NULL;
+ }
+
+ if (!(object_type->info = ast_calloc(1, sizeof(*object_type->info) + 2 * sizeof(object_type->info->files[0])))) {
+ ao2_ref(object_type, -1);
+ return NULL;
+ }
+
+ if (!(object_type->file = ast_calloc(1, sizeof(*object_type->file) + 2 * sizeof(object_type->file->types[0])))) {
+ ao2_ref(object_type, -1);
+ return NULL;
+ }
+
+ object_type->info->files[0] = object_type->file;
+ object_type->info->files[1] = NULL;
+
+ ast_copy_string(object_type->name, type, sizeof(object_type->name));
+
+ return object_type;
+}
+
+/*! \brief Object wizard destructor */
+static void sorcery_object_wizard_destructor(void *obj)
+{
+ struct ast_sorcery_object_wizard *object_wizard = obj;
+
+ if (object_wizard->data) {
+ object_wizard->wizard->close(object_wizard->data);
+ }
+
+ if (object_wizard->wizard) {
+ ast_module_unref(object_wizard->wizard->module);
+ }
+}
+
+/*! \brief Internal function which creates an object type and adds a wizard mapping */
+static int sorcery_apply_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *name, const char *data, unsigned int caching)
+{
+ RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
+ RAII_VAR(struct ast_sorcery_wizard *, wizard, ao2_find(wizards, name, OBJ_KEY), ao2_cleanup);
+ RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, ao2_alloc(sizeof(*object_wizard), sorcery_object_wizard_destructor), ao2_cleanup);
+ int created = 0;
+
+ if (!wizard || !object_wizard) {
+ return -1;
+ }
+
+ if (!object_type) {
+ if (!(object_type = sorcery_object_type_alloc(type))) {
+ return -1;
+ }
+ created = 1;
+ }
+
+ if (wizard->open && !(object_wizard->data = wizard->open(data))) {
+ return -1;
+ }
+
+ ast_module_ref(wizard->module);
+
+ object_wizard->wizard = wizard;
+ object_wizard->caching = caching;
+
+ ao2_link(object_type->wizards, object_wizard);
+
+ if (created) {
+ ao2_link(sorcery->types, object_type);
+ }
+
+ return 0;
+}
+
+int ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name)
+{
+ struct ast_flags flags = { 0 };
+ struct ast_config *config = ast_config_load2("sorcery.conf", "sorcery", flags);
+ struct ast_variable *mapping;
+ int res = 0;
+
+ if (!config || (config == CONFIG_STATUS_FILEMISSING) || (config == CONFIG_STATUS_FILEINVALID)) {
+ return -1;
+ }
+
+ for (mapping = ast_variable_browse(config, name); mapping; mapping = mapping->next) {
+ RAII_VAR(char *, mapping_name, ast_strdup(mapping->name), ast_free);
+ RAII_VAR(char *, mapping_value, ast_strdup(mapping->value), ast_free);
+ char *options = mapping_name, *name = strsep(&options, "/");
+ char *data = mapping_value, *wizard = strsep(&data, ",");
+ unsigned int caching = 0;
+
+ /* If no wizard exists just skip, nothing we can do */
+ if (ast_strlen_zero(wizard)) {
+ continue;
+ }
+
+ /* If the wizard is configured as a cache treat it as such */
+ if (!ast_strlen_zero(options) && strstr(options, "cache")) {
+ caching = 1;
+ }
+
+ /* Any error immediately causes us to stop */
+ if ((res = sorcery_apply_wizard_mapping(sorcery, name, wizard, data, caching))) {
+ break;
+ }
+ }
+
+ ast_config_destroy(config);
+
+ return res;
+}
+
+int ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *name, const char *data)
+{
+ RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
+
+ /* Defaults can not be added if any existing mapping exists */
+ if (object_type) {
+ return -1;
+ }
+
+ return sorcery_apply_wizard_mapping(sorcery, type, name, data, 0);
+}
+
+int ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply)
+{
+ RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
+
+ if (!object_type) {
+ return -1;
+ }
+
+ object_type->type.type = ACO_ITEM;
+ object_type->type.category = "";
+ object_type->type.item_alloc = alloc;
+
+ object_type->transform = transform;
+ object_type->file->types[0] = &object_type->type;
+ object_type->file->types[1] = NULL;
+
+ if (aco_info_init(object_type->info)) {
+ return -1;
+ }
+
+ return 0;
+}
+
+int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type, const char *name, const char *default_val, enum aco_option_type opt_type,
+ aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, size_t argc, ...)
+{
+ RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
+ RAII_VAR(struct ast_sorcery_object_field *, object_field, NULL, ao2_cleanup);
+ int pos;
+ va_list args;
+
+ if (!object_type || !object_type->type.item_alloc) {
+ return -1;
+ }
+
+ if (!sorcery_handler) {
+ sorcery_handler = sorcery_field_default_handler(opt_type);
+ }
+
+ if (!(object_field = ao2_alloc(sizeof(*object_field) + argc * sizeof(object_field->args[0]), NULL))) {
[... 3041 lines stripped ...]
More information about the asterisk-commits
mailing list