sorcery.h File Reference

Sorcery Data Access Layer API. More...

#include "asterisk/config_options.h"
#include "asterisk/uuid.h"

Include dependency graph for sorcery.h:

Go to the source code of this file.

Data Structures
struct	ast_sorcery_global_observer
	Interface for the global sorcery observer. More...
struct	ast_sorcery_instance_observer
	Interface for the sorcery instance observer. More...
struct	ast_sorcery_object_details
	Structure which contains details about a sorcery object. More...
struct	ast_sorcery_observer
	Interface for a sorcery object type observer. More...
struct	ast_sorcery_wizard
	Interface for a sorcery wizard. More...
struct	ast_sorcery_wizard_observer
	Interface for the sorcery wizard observer. More...

Macros
#define	_sorcery_stringify(val)   #val
#define	ast_sorcery_apply_config(sorcery, name)    __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
#define	ast_sorcery_apply_default(sorcery, type, name, data)    __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
#define	ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching)    __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));
	Apply additional object wizard mappings.
#define	ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position)
	Insert an additional object wizard mapping at a specific position in the wizard list.
#define	ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply)    __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
	Register an internal, hidden object type.
#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, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
	Register a field within an object.
#define	ast_sorcery_object_field_register_alias(sorcery, type, name, default_val, opt_type, flags, ...)    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
	Register a field within an object as an alias.
#define	ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...)    __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
	Register a field within an object with custom handlers.
#define	ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...)    __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
	Register a field within an object with custom handlers as an alias.
#define	ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...)    __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
	Register a field within an object with custom handlers without documentation.
#define	ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...)    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
	Register a field within an object without documentation.
#define	ast_sorcery_object_register(sorcery, type, alloc, transform, apply)    __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
	Register an object type.
#define	ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply)    __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
	Register an object type that is not reloadable.
#define	ast_sorcery_object_type_apply_wizard(sorcery, object_type_name, wizard_type_name, wizard_args, flags, wizard, wizard_data)
	Apply additional object wizard mappings returning wizard information.
#define	ast_sorcery_object_type_insert_wizard(sorcery, object_type_name, wizard_type_name, wizard_args, flags, position, wizard, wizard_data)
	Insert an additional object wizard mapping at a specific position in the wizard list returning wizard information.
#define	ast_sorcery_object_type_remove_wizard(sorcery, object_type_name, wizard_type_name, wizard_args)
	Remove an object wizard mapping.
#define	ast_sorcery_objectset_create(sorcery, object)    ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
	Create an object set (KVP list) for an object.
#define	ast_sorcery_open()   __ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Open a new sorcery structure.
#define	ast_sorcery_register_bool(object, structure, option, field, def_value)
	Register a boolean field as type OPT_YESNO_T within an object.
#define	ast_sorcery_register_cust(object, option, def_value)
	Register a custom field within an object.
#define	ast_sorcery_register_int(object, structure, option, field, def_value)
	Register an int field as type OPT_INT_T within an object.
#define	ast_sorcery_register_sf(object, structure, option, field, def_value)
	Register a stringfield field as type OPT_STRINGFIELD_T within an object.
#define	ast_sorcery_register_uint(object, structure, option, field, def_value)
	Register an unsigned int field as type OPT_UINT_T within an object.
#define	ast_sorcery_remove_wizard_mapping(sorcery, type, name)    __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
	Remove an object wizard mapping.
#define	ast_sorcery_unref(sorcery)    ao2_cleanup(sorcery)
	Decrease the reference count of a sorcery structure.
#define	ast_sorcery_wizard_register(interface)   __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)
	See __ast_sorcery_wizard_register()
#define	MAX_OBJECT_FIELD   128
	Maximum length of an object field name.
#define	MAX_OBJECT_TYPE   64
	Maximum size of an object type.
#define	SORCERY_OBJECT(details)
	Macro which must be used at the beginning of each sorcery capable object.

Typedefs
typedef int(*	sorcery_apply_handler) (const struct ast_sorcery *sorcery, void *obj)
	A callback function for when an object set is successfully applied to an object.
typedef int(*	sorcery_copy_handler) (const void *src, void *dst)
	A callback function for copying the contents of one object to another.
typedef int(*	sorcery_diff_handler) (const void *original, const void *modified, struct ast_variable **changes)
	A callback function for generating a changeset between two objects.
typedef int(*	sorcery_field_handler) (const void *obj, const intptr_t *args, char **buf)
	A callback function for translating a value into a string.
typedef int(*	sorcery_fields_handler) (const void *obj, struct ast_variable **fields)
	A callback function for translating multiple values into an ast_variable list.
typedef struct ast_variable *(*	sorcery_transform_handler) (struct ast_variable *set)
	A callback function for performing a transformation on an object set.

Enumerations
enum	ast_sorcery_apply_result {   AST_SORCERY_APPLY_FAIL = -1 , AST_SORCERY_APPLY_SUCCESS = 0 , AST_SORCERY_APPLY_DUPLICATE = 1 , AST_SORCERY_APPLY_DEFAULT_UNNECESSARY = 2 ,   AST_SORCERY_APPLY_NO_CONFIGURATION = 3 }
enum	ast_sorcery_field_handler_flags { AST_HANDLER_PREFER_STRING , AST_HANDLER_PREFER_LIST , AST_HANDLER_ONLY_STRING , AST_HANDLER_ONLY_LIST }
	Field handler flags. More...
enum	ast_sorcery_retrieve_flags { AST_RETRIEVE_FLAG_DEFAULT = 0 , AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0) , AST_RETRIEVE_FLAG_ALL = (1 << 1) }
	Retrieval flags. More...
enum	ast_sorcery_wizard_apply_flags { AST_SORCERY_WIZARD_APPLY_NONE = (0 << 0) , AST_SORCERY_WIZARD_APPLY_CACHING = (1 << 0) , AST_SORCERY_WIZARD_APPLY_READONLY = (1 << 1) , AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE = (1 << 2) }
	Wizard Apply Flags. More...
enum	ast_sorcery_wizard_position { AST_SORCERY_WIZARD_POSITION_LAST = -1 , AST_SORCERY_WIZARD_POSITION_FIRST = 0 }
	Pre-defined locations to insert at. More...

Functions
enum ast_sorcery_apply_result	__ast_sorcery_apply_config (struct ast_sorcery *sorcery, const char *name, const char *module)
	Apply configured wizard mappings.
enum ast_sorcery_apply_result	__ast_sorcery_apply_default (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data)
	Apply default object wizard mappings.
enum ast_sorcery_apply_result	__ast_sorcery_apply_wizard_mapping (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching)
	Apply additional object wizard mappings.
enum ast_sorcery_apply_result	__ast_sorcery_insert_wizard_mapping (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching, int position)
	Insert an additional object wizard mapping at a specific position in the wizard list.
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, sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc, unsigned int alias, size_t argc,...)
	Register a field within an object.
int	__ast_sorcery_object_register (struct ast_sorcery *sorcery, const char *type, unsigned int hidden, unsigned int reloadable, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply)
	Register an object type.
enum ast_sorcery_apply_result	__ast_sorcery_object_type_insert_wizard (struct ast_sorcery *sorcery, const char *object_type_name, const char *module, const char *wizard_type_name, const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position, struct ast_sorcery_wizard **wizard, void **wizard_data)
	Insert an additional object wizard mapping at a specific position in the wizard list returning wizard information.
int	__ast_sorcery_object_type_remove_wizard (struct ast_sorcery *sorcery, const char *object_type_name, const char *module, const char *wizard_type_name, const char *wizard_args)
	Remove an object wizard mapping.
struct ast_sorcery *	__ast_sorcery_open (const char *module, const char *file, int line, const char *func)
int	__ast_sorcery_remove_wizard_mapping (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name)
	Remove an object wizard mapping.
int	__ast_sorcery_wizard_register (const struct ast_sorcery_wizard *interface, struct ast_module *module)
	Register a sorcery wizard.
void *	ast_sorcery_alloc (const struct ast_sorcery *sorcery, const char *type, const char *id)
	Allocate an object.
int	ast_sorcery_changeset_create (const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes)
	Create a changeset given two object sets.
void *	ast_sorcery_copy (const struct ast_sorcery *sorcery, const void *object)
	Create a copy of an object.
int	ast_sorcery_create (const struct ast_sorcery *sorcery, void *object)
	Create and potentially persist an object using an available wizard.
int	ast_sorcery_delete (const struct ast_sorcery *sorcery, void *object)
	Delete an object.
int	ast_sorcery_diff (const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes)
	Create a changeset of two objects.
void	ast_sorcery_force_reload (const struct ast_sorcery *sorcery)
	Inform any wizards to reload persistent objects, even if no changes determined.
void	ast_sorcery_force_reload_object (const struct ast_sorcery *sorcery, const char *type)
	Inform any wizards of a specific object type to reload persistent objects even if no changes determined.
void *	ast_sorcery_generic_alloc (size_t size, ao2_destructor_fn destructor)
	Allocate a generic sorcery capable object.
const char *	ast_sorcery_get_module (const struct ast_sorcery *sorcery)
	Get the module that has opened the provided sorcery instance.
struct ast_sorcery_object_type *	ast_sorcery_get_object_type (const struct ast_sorcery *sorcery, const char *type)
	Get the sorcery object type given a type name.
int	ast_sorcery_get_wizard_mapping (struct ast_sorcery *sorcery, const char *type, int index, struct ast_sorcery_wizard **wizard, void **data)
	By index, return a wizard mapped to an object type.
int	ast_sorcery_get_wizard_mapping_count (struct ast_sorcery *sorcery, const char *type)
	Return the number of wizards mapped to an object type.
int	ast_sorcery_global_observer_add (const struct ast_sorcery_global_observer *callbacks)
	Add a global observer to sorcery.
void	ast_sorcery_global_observer_remove (const struct ast_sorcery_global_observer *callbacks)
	Remove a global observer from sorcery.
int	ast_sorcery_init (void)
	Initialize the sorcery API.
int	ast_sorcery_instance_observer_add (struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
	Add an observer to a sorcery instance.
void	ast_sorcery_instance_observer_remove (struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
	Remove an observer from a sorcery instance.
int	ast_sorcery_is_object_field_registered (const struct ast_sorcery_object_type *object_type, const char *field_name)
	Determine if a particular object field has been registered with sorcery.
int	ast_sorcery_is_stale (const struct ast_sorcery *sorcery, void *object)
	Determine if a sorcery object is stale with respect to its backing datastore.
void	ast_sorcery_load (const struct ast_sorcery *sorcery)
	Inform any wizards to load persistent objects.
void	ast_sorcery_load_object (const struct ast_sorcery *sorcery, const char *type)
	Inform any wizards of a specific object type to load persistent objects.
void *	ast_sorcery_lockable_alloc (size_t size, ao2_destructor_fn destructor, void *lockobj)
	Allocate a generic sorcery capable object with locking.
int	ast_sorcery_object_fields_register (struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler, sorcery_fields_handler sorcery_handler)
	Register a regex for multiple fields within an object.
const struct timeval	ast_sorcery_object_get_created (const void *object)
	Get when the sorcery object was created.
const char *	ast_sorcery_object_get_extended (const void *object, const char *name)
	Get an extended field value from a sorcery object.
const char *	ast_sorcery_object_get_id (const void *object)
	Get the unique identifier of a sorcery object.
const char *	ast_sorcery_object_get_type (const void *object)
	Get the type of a sorcery object.
unsigned int	ast_sorcery_object_has_dynamic_contents (const void *object)
	Get whether an object contains dynamic contents or not.
int	ast_sorcery_object_id_compare (void *obj, void *arg, int flags)
	ao2 object comparator based on sorcery id.
int	ast_sorcery_object_id_hash (const void *obj, int flags)
	ao2 object hasher based on sorcery id.
int	ast_sorcery_object_id_sort (const void *obj, const void *arg, int flags)
	ao2 object sorter based on sorcery id.
int	ast_sorcery_object_set_congestion_levels (struct ast_sorcery *sorcery, const char *type, long low_water, long high_water)
	Set the high and low alert water marks of the sorcery object type.
void	ast_sorcery_object_set_copy_handler (struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy)
	Set the copy handler for an object type.
void	ast_sorcery_object_set_diff_handler (struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff)
	Set the diff handler for an object type.
int	ast_sorcery_object_set_extended (const void *object, const char *name, const char *value)
	Set an extended field value on a sorcery object.
void	ast_sorcery_object_set_has_dynamic_contents (const void *object)
	Set the dynamic contents flag on a sorcery object.
int	ast_sorcery_object_unregister (struct ast_sorcery *sorcery, const char *type)
	Unregister an object type.
int	ast_sorcery_objectset_apply (const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset)
	Apply an object set (KVP list) to an object.
struct ast_variable *	ast_sorcery_objectset_create2 (const struct ast_sorcery *sorcery, const void *object, enum ast_sorcery_field_handler_flags flags)
	Create an object set (KVP list) for an object.
struct ast_json *	ast_sorcery_objectset_json_create (const struct ast_sorcery *sorcery, const void *object)
	Create an object set in JSON format for an object.
int	ast_sorcery_observer_add (const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks)
	Add an observer to a specific object type.
void	ast_sorcery_observer_remove (const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks)
	Remove an observer from a specific object type.
void	ast_sorcery_ref (struct ast_sorcery *sorcery)
	Increase the reference count of a sorcery structure.
void	ast_sorcery_reload (const struct ast_sorcery *sorcery)
	Inform any wizards to reload persistent objects.
void	ast_sorcery_reload_object (const struct ast_sorcery *sorcery, const char *type)
	Inform any wizards of a specific object type to reload persistent objects.
void *	ast_sorcery_retrieve_by_fields (const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields)
	Retrieve an object or multiple objects using specific fields.
void *	ast_sorcery_retrieve_by_id (const struct ast_sorcery *sorcery, const char *type, const char *id)
	Retrieve an object using its unique identifier.
struct ast_sorcery *	ast_sorcery_retrieve_by_module_name (const char *module_name)
	Retrieves an existing sorcery instance by module name.
struct ao2_container *	ast_sorcery_retrieve_by_prefix (const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len)
	Retrieve multiple objects whose id begins with the specified prefix.
struct ao2_container *	ast_sorcery_retrieve_by_regex (const struct ast_sorcery *sorcery, const char *type, const char *regex)
	Retrieve multiple objects using a regular expression on their id.
int	ast_sorcery_update (const struct ast_sorcery *sorcery, void *object)
	Update an object.
int	ast_sorcery_wizard_observer_add (struct ast_sorcery_wizard *wizard, const struct ast_sorcery_wizard_observer *callbacks)
	Add an observer to a sorcery wizard.
void	ast_sorcery_wizard_observer_remove (struct ast_sorcery_wizard *interface, const struct ast_sorcery_wizard_observer *callbacks)
	Remove an observer from a sorcery wizard.
int	ast_sorcery_wizard_unregister (const struct ast_sorcery_wizard *interface)
	Unregister a sorcery wizard.

Variables
int	ast_sorcery_update_or_create_on_update_miss
	Global control for optional update->create fallback in backends.

Detailed Description

Sorcery Data Access Layer API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om Data Access Layer API

Definition in file sorcery.h.

Macro Definition Documentation

_sorcery_stringify

#define _sorcery_stringify

(

val

)

#val

Definition at line 1695 of file sorcery.h.

ast_sorcery_apply_config

#define ast_sorcery_apply_config	(		sorcery,
			name
	)		__ast_sorcery_apply_config((sorcery), (name), AST_MODULE)

Definition at line 455 of file sorcery.h.

                                 {
    AST_SORCERY_WIZARD_POSITION_LAST = -1,
    AST_SORCERY_WIZARD_POSITION_FIRST = 0,
};
 
/*!
 * \brief Insert an additional object wizard mapping at a specific position
 * in the wizard list
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object to apply to
 * \param module The name of the module, typically AST_MODULE
 * \param name Name of the wizard to use
 * \param data Data to be passed to wizard
 * \param caching Wizard should cache
 * \param position An index to insert to or one of ast_sorcery_wizard_position
 *
 * \return What occurred when applying the mapping
 *
 * \note This should be called *after* applying default mappings
 * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count
 * and iterating over them using ast_sorcery_get_wizard_mapping.
 *
 * \since 13.4.0
 */
enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sorcery *sorcery,
    const char *type, const char *module, const char *name, const char *data,
    unsigned int caching, int position);
 
/*!
 * \brief Insert an additional object wizard mapping at a specific position
 * in the wizard list
 *
 * \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
 * \param caching Wizard should cache
 * \param position One of ast_sorcery_wizard_position
 *
 * \return What occurred when applying the mapping
 *
 * \note This should be called *after* applying default mappings
 * \since 13.4.0
 */
#define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \
    __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
        (caching), (position))
 
/*!
 * \brief Wizard Apply Flags
 *
 * These flags apply only to a wizard/object-type combination.
 * The same wizard may be applied to a different object-type with
 * different flags and behavior.  If ALLOW_DUPLICATE is set
 * the wizard could even be applied to the same object-type
 * with different flags.
 */
enum ast_sorcery_wizard_apply_flags {
    /*! Apply no special behavior */
    AST_SORCERY_WIZARD_APPLY_NONE = (0 << 0),
    /*! This wizard will cache this object type's entries */
    AST_SORCERY_WIZARD_APPLY_CACHING = (1 << 0),
    /*! This wizard won't allow Create, Update or Delete operations on this object type */
    AST_SORCERY_WIZARD_APPLY_READONLY = (1 << 1),
    /*! This wizard will allow other instances of itself on the same object type */
    AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE = (1 << 2)
};
 
/*!
 * \brief Insert an additional object wizard mapping at a specific position
 * in the wizard list returning wizard information
 * \since 13.26.0
 * \since 16.3.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param object_type_name Name of the object type to apply to
 * \param module The name of the module, typically AST_MODULE
 * \param wizard_type_name Name of the wizard type to use
 * \param wizard_args Opaque string to be passed to the wizard
 *             May be NULL but see note below
 * \param flags One or more of enum ast_sorcery_wizard_apply_flags
 * \param position An index to insert to or one of ast_sorcery_wizard_position
 * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
 *             May be NULL if not needed.
 * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
 *             May be NULL if not needed.
 *
 * \return What occurred when applying the mapping
 *
 * \note This should be called *after* applying default mappings
 *
 * \note Although \p wizard_args is an optional parameter it is highly
 * recommended to supply one.  If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
 * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
 * to remove specific instances of a wizard type.
 */
enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast_sorcery *sorcery,
    const char *object_type_name, const char *module, const char *wizard_type_name,
    const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position,
    struct ast_sorcery_wizard **wizard, void **wizard_data);
 
/*!
 * \brief Insert an additional object wizard mapping at a specific position
 * in the wizard list returning wizard information
 * \since 13.26.0
 * \since 16.3.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param object_type_name Name of the object type to apply to
 * \param wizard_type_name Name of the wizard type to use
 * \param wizard_args Opaque string to be passed to the wizard
 *             May be NULL but see note below
 * \param flags One or more of enum ast_sorcery_wizard_apply_flags
 * \param position An index to insert to or one of ast_sorcery_wizard_position
 * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
 *             May be NULL if not needed.
 * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
 *             May be NULL if not needed.
 *
 * \return What occurred when applying the mapping
 *
 * \note This should be called *after* applying default mappings
 *
 * \note Although \p wizard_args is an optional parameter it is highly
 * recommended to supply one.  If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
 * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
 * to remove specific instances.
 */
#define ast_sorcery_object_type_insert_wizard(sorcery, \
    object_type_name, wizard_type_name, wizard_args, flags, \
    position, wizard, wizard_data) \
    __ast_sorcery_object_type_insert_wizard((sorcery), \
        (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
        position, (wizard), (wizard_data))
 
/*!
 * \brief Apply additional object wizard mappings returning wizard information
 * \since 13.26.0
 * \since 16.3.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param object_type_name Name of the object type to apply to
 * \param wizard_type_name Name of the wizard type to use
 * \param wizard_args Opaque string to be passed to the wizard
 *             May be NULL but see note below
 * \param flags One or more of enum ast_sorcery_wizard_apply_flags
 * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
 *             May be NULL if not needed.
 * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
 *             May be NULL if not needed.
 *
 * \return What occurred when applying the mapping
 *
 * \note This should be called *after* applying default mappings
 *
 * \note Although \p wizard_args is an optional parameter it is highly
 * recommended to supply one.  If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
 * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
 * to remove specific instances.
 */
#define ast_sorcery_object_type_apply_wizard(sorcery, \
    object_type_name, wizard_type_name, wizard_args, flags, \
    wizard, wizard_data) \
    __ast_sorcery_object_type_insert_wizard((sorcery), \
        (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
        AST_SORCERY_WIZARD_POSITION_LAST, (wizard), (wizard_data))
 
/*!
 * \brief Remove an object wizard mapping
 * \since 13.26.0
 * \since 16.3.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param object_type_name Name of the object type to remove from
 * \param module The name of the module, typically AST_MODULE
 * \param wizard_type_name The name of the of the wizard type to remove
 * \param wizard_args Opaque string originally passed to the wizard
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note If there were multiple instances of the same wizard type
 * added to this object type without using \p wizard_args, then
 * only the first wizard matching wizard_type will be removed.
 */
int __ast_sorcery_object_type_remove_wizard(struct ast_sorcery *sorcery,
    const char *object_type_name, const char *module, const char *wizard_type_name,
    const char *wizard_args);
 
/*!
 * \brief Remove an object wizard mapping
 * \since 13.26.0
 * \since 16.3.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param object_type_name Name of the object type to remove from
 * \param wizard_type_name The name of the of the wizard type to remove
 * \param wizard_args Opaque string originally passed to the wizard
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note If there were multiple instances of the same wizard type
 * added to this object type without using \p wizard_args, then
 * only the first wizard matching wizard_type will be removed.
 */
#define ast_sorcery_object_type_remove_wizard(sorcery, object_type_name, \
    wizard_type_name, wizard_args) \
    __ast_sorcery_object_type_remove_wizard((sorcery), (object_type_name), \
        AST_MODULE, (wizard_type_name), (wizard_args))
 
/*!
 * \brief Remove an object wizard mapping
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object to remove from
 * \param module The name of the module, typically AST_MODULE
 * \param name The name of the wizard to remove
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \since 13.4.0
 */
int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery,
    const char *type, const char *module, const char *name);
 
/*!
 * \brief Remove an object wizard mapping
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object to remove from
 * \param name The name of the wizard to remove
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \since 13.4.0
 */
#define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
    __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
 
/*!
 * \brief Return the number of wizards mapped to an object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 *
 * \return Number of wizards or -1 for error
 * \since 13.4.0
 */
int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery,
    const char *type);
 
/*!
 * \brief By index, return a wizard mapped to an object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 * \param index Index of the wizard
 * \param wizard A pointer to receive the wizard pointer
 * \param data A pointer to receive the data pointer
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \warning The wizard will have its reference count bumped so you must
 * call ao2_cleanup when you're done with it.
 *
 * \note The wizard and data returned are valid only for this object type
 * and only while the wizard is applied to the object type.
 *
 * \since 13.4.0
 */
int ast_sorcery_get_wizard_mapping(struct ast_sorcery *sorcery,
    const char *type, int index, struct ast_sorcery_wizard **wizard, void **data);
 
/*!
 * \brief Unregister an object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 *
 * \retval 0 success
 * \retval -1 failure
 */
int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type);
 
/*!
 * \brief Register an object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 * \param hidden All objects of this type are internal and should not be manipulated by users
 * \param reloadable All objects of this type are reloadable
 * \param alloc Required object allocation callback
 * \param transform Optional transformation callback
 * \param apply Optional object set apply callback
 *
 * \note In general, this function should not be used directly. One of the various
 * macro'd versions should be used instead.
 *
 * \retval 0 success
 * \retval -1 failure
 */
int __ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, unsigned int hidden, unsigned int reloadable, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply);
 
/*!
 * \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
 */
#define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
    __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
 
/*!
 * \brief Register an object type that is not reloadable
 *
 * \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
 */
#define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
    __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
 
/*!
 * \brief Register an internal, hidden 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
 */
#define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
    __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
 
/*!
 * \brief Set the high and low alert water marks of the sorcery object type.
 * \since 13.10.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 * \param low_water New queue low water mark. (-1 to set as 90% of high_water)
 * \param high_water New queue high water mark.
 *
 * \retval 0 on success.
 * \retval -1 on error (water marks not changed).
 */
int ast_sorcery_object_set_congestion_levels(struct ast_sorcery *sorcery, const char *type, long low_water, long high_water);
 
/*!
 * \brief Set the copy handler for an object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 * \param copy Copy handler
 */
void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
 
/*!
 * \brief Set the diff handler for an object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 * \param diff Diff handler
 */
void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
 
/*!
 * \brief Register a regex for multiple fields within an object
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object
 * \param regex A regular expression pattern for the fields
 * \param config_handler A custom handler for translating the string representation of the fields
 * \param sorcery_handler A custom handler for translating the native representation of the fields
 *
 * \retval 0 success
 * \retval -1 failure
 */
int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
                                       sorcery_fields_handler sorcery_handler);
 
/*!
 * \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 config_handler A custom handler for translating the string representation of the fields
 * \param sorcery_handler A custom handler for translating the native representation of the fields
 * \param multiple_handler A custom handler for translating the native representation of the fields
 * \param opt_type Option type
 * \param flags Option type specific flags
 * \param no_doc Field should not be documented
 * \param alias Interpret and apply field value only
 * \param argc
 *
 * \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,
    sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc,
    unsigned int alias, 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, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 
/*!
 * \brief Register a field within an object as an alias
 *
 * \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_alias(sorcery, type, name, default_val, opt_type, flags, ...) \
    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 
/*!
 * \brief Register a field within an object without documentation
 *
 * \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_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, 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 multiple_handler Custom multiple 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, multiple_handler, flags, ...) \
    __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
 
/*!
 * \brief Register a field within an object with custom handlers as an alias
 *
 * \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 multiple_handler Custom multiple handler
 * \param flags Option type specific flags
 *
 * \retval 0 success
 * \retval -1 failure
 */
#define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
    __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
 
/*!
 * \brief Register a field within an object with custom handlers without documentation
 *
 * \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 multiple_handler Custom multiple handler
 * \param flags Option type specific flags
 *
 * \retval 0 success
 * \retval -1 failure
 */
#define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
    __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 0, 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 of a specific object type to load persistent objects
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Name of the object type to load
 */
void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
 
/*!
 * \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 Inform any wizards to reload persistent objects, even if no changes determined
 *
 * \param sorcery Pointer to a sorcery structure
 *
 * \since 13.32.0
 * \since 16.9.0
 * \since 17.3.0
 */
void ast_sorcery_force_reload(const struct ast_sorcery *sorcery);
 
/*!
 * \brief Inform any wizards of a specific object type to reload persistent objects
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Name of the object type to reload
 */
void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
 
/*!
 * \brief Inform any wizards of a specific object type to reload persistent objects
 *        even if no changes determined
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Name of the object type to reload
 *
 * \since 13.32.0
 * \since 16.9.0
 * \since 17.3.0
 */
void ast_sorcery_force_reload_object(const struct ast_sorcery *sorcery, const char *type);
 
/*!
 * \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
 * \param flags Flags indicating which handler to use and in what order.
 *
 * \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_create2(const struct ast_sorcery *sorcery,
    const void *object, enum ast_sorcery_field_handler_flags flags);
 
/*!
 * \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
 *
 * \note This function attempts to use a field's sorcery_fields_handler first and if that
 * doesn't exist or fails, a field's sorcery_field_handler is used.  The difference is
 * that the former may return multiple list entries for the same field and the latter will only
 * return 1.  It's up to the field itself to determine what the appropriate content is.
 */
#define ast_sorcery_objectset_create(sorcery, object) \
    ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
 
/*!
 * \brief Create an object set in JSON format 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_json object must be unreferenced using ast_json_unref
 */
struct ast_json *ast_sorcery_objectset_json_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 a generic sorcery capable object
 *
 * \param size Size of the object
 * \param destructor Optional destructor function
 *
 * \retval non-NULL success
 * \retval NULL failure
 *
 * \note The returned object does not support AO2 locking.
 */
void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
 
/*!
 * \since 14.1.0
 * \brief Allocate a generic sorcery capable object with locking.
 *
 * \details Sorcery objects may be replaced with new allocations during reloads.
 * If locking is required on sorcery objects it must be shared between the old
 * object and the new one.  lockobj can be any AO2 object with locking enabled,
 * but in most cases named locks should be used to provide stable locking.
 *
 * \param size Size of the object
 * \param destructor Optional destructor function
 * \param lockobj An AO2 object that will provide locking.
 *
 * \retval non-NULL success
 * \retval NULL failure
 */
void *ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj);
 
/*!
 * \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 Add a global observer to sorcery
 *
 * \param callbacks Implementation of the global observer interface
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note You must be ready to accept observer invocations before this function is called
 */
int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks);
 
/*!
 * \brief Remove a global observer from sorcery.
 *
 * A global observer is notified...
 * After a new wizard is registered.
 * After a new sorcery instance is opened.
 * Before an instance is destroyed.
 * Before a wizard is unregistered.
 *
 * \param callbacks Implementation of the global observer interface
 */
void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks);
 
/*!
 * \brief Add an observer to a sorcery instance
 *
 * \param sorcery Pointer to a sorcery structure
 * \param callbacks Implementation of the instance observer interface
 *
 * An instance observer is notified...
 * Before an instance is loaded or reloaded.
 * After an instance is loaded or reloaded.
 * After a wizard is mapped to an object type.
 * After an object type is registered.
 * Before an object type is loaded or reloaded.
 * After an object type is loaded or reloaded.
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note You must be ready to accept observer invocations before this function is called
 */
int ast_sorcery_instance_observer_add(struct ast_sorcery *sorcery,
    const struct ast_sorcery_instance_observer *callbacks);
 
/*!
 * \brief Remove an observer from a sorcery instance
 *
 * \param sorcery Pointer to a sorcery structure
 * \param callbacks Implementation of the instance observer interface
 */
void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery,
    const struct ast_sorcery_instance_observer *callbacks);
 
/*!
 * \brief Add an observer to a sorcery wizard
 *
 * \param wizard Pointer to a previously registered wizard structure
 * \param callbacks Implementation of the wizard observer interface
 *
 * A wizard observer is notified...
 * Before a wizard is loaded or reloaded.
 * After a wizard is loaded or reloaded.
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note You must be ready to accept observer invocations before this function is called
 */
int ast_sorcery_wizard_observer_add(struct ast_sorcery_wizard *wizard,
    const struct ast_sorcery_wizard_observer *callbacks);
 
/*!
 * \brief Remove an observer from a sorcery wizard.
 *
 * \param interface Pointer to a sorcery structure
 * \param callbacks Implementation of the wizard observer interface
 */
void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *interface,
    const struct ast_sorcery_wizard_observer *callbacks);
 
/*!
 * \brief Add an observer to a specific object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object that should be observed
 * \param callbacks Implementation of the observer interface
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note You must be ready to accept observer invocations before this function is called
 */
int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
 
/*!
 * \brief Remove an observer from a specific object type
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object that should no longer be observed
 * \param callbacks Implementation of the observer interface
 */
void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
 
/*!
 * \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
 * \since 13.9.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object to retrieve
 * \param flags Flags to control behavior
 * \param fields Optional object 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.
 *
 * \note The fields parameter can contain realtime-style expressions in variable->name.
 *       All operators defined for ast_strings_match can be used except for regex as
 *       there's no common support for regex in the realtime backends at this time.
 *       If multiple variables are in the fields list, all must match for an object to
 *       be returned.  See ast_strings_match for more information.
 *
 * Example:
 *
 * The following code can be significantly faster when a realtime backend is in use
 * because the expression "qualify_frequency > 0" is passed to the database to limit
 * the number of rows returned.
 *
 *  struct ast_variable *var = ast_variable_new("qualify_frequency >", "0", "");
 *  struct ao2_container *aors;
 *
 *  if (!var) {
 *      return;
 *  }
 *
 *  aors = ast_sorcery_retrieve_by_fields(ast_sip_get_sorcery(),
 *      "aor", AST_RETRIEVE_FLAG_MULTIPLE, var);
 *
 */
void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
 
/*!
 * \brief Retrieve multiple objects using a regular expression on their id
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object to retrieve
 * \param regex Regular expression
 *
 * \retval non-NULL if error occurs
 * \retval NULL success
 *
 * \note The provided regex is treated as extended case sensitive.
 */
struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
 
/*!
 * \brief Retrieve multiple objects whose id begins with the specified prefix
 * \since 13.19.0
 *
 * \param sorcery Pointer to a sorcery structure
 * \param type Type of object to retrieve
 * \param prefix Object id prefix
 * \param prefix_len The length of prefix in bytes
 *
 * \retval non-NULL if error occurs
 * \retval NULL success
 *
 * \note The prefix is matched in a case sensitive manner.
 */
struct ao2_container *ast_sorcery_retrieve_by_prefix(const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len);
 
/*!
 * \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 Determine if a sorcery object is stale with respect to its backing datastore
 * \since 14.0.0
 *
 * This function will query the wizard(s) backing the particular sorcery object to
 * determine if the in-memory object is now stale. No action is taken to update
 * the object. Callers of this function may use one of the ast_sorcery_retrieve
 * functions to obtain a new instance of the object if desired.
 *
 * \retval 0 the object is not stale
 * \retval 1 the object is stale
 */
int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
 
/*!
 * \brief Decrease the reference count of a sorcery structure
 *
 * \param sorcery Pointer to a sorcery structure
 *
 * \note Prior to 16.0.0 this was a function which had to be used.
 *       Now you can use any variant of ao2_cleanup or ao2_ref to
 *       release a reference.
 */
#define ast_sorcery_unref(sorcery) \
    ao2_cleanup(sorcery)
 
/*!
 * \brief Get the unique identifier of a sorcery object
 *
 * \param object Pointer to a sorcery object
 *
 * \return unique identifier
 */
const char *ast_sorcery_object_get_id(const void *object);
 
/*!
 * \since 14.0.0
 * \brief Get when the sorcery object was created
 *
 * \param object Pointer to a sorcery object
 *
 * \return The time when the object was created
 */
const struct timeval ast_sorcery_object_get_created(const void *object);
 
/*!
 * \brief Get the type of a sorcery object
 *
 * \param object Pointer to a sorcery object
 *
 * \return type of object
 */
const char *ast_sorcery_object_get_type(const void *object);
 
/*!
 * \brief Get an extended field value from a sorcery object
 *
 * \param object Pointer to a sorcery object
 * \param name Name of the extended field value
 *
 * \retval non-NULL if found
 * \retval NULL if not found
 *
 * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
 */
const char *ast_sorcery_object_get_extended(const void *object, const char *name);
 
/*!
 * \brief Set an extended field value on a sorcery object
 *
 * \param object Pointer to a sorcery object
 * \param name Name of the extended field
 * \param value Value of the extended field
 *
 * \retval 0 success
 * \retval -1 failure
 *
 * \note The field name MUST begin with '@' to indicate it is an extended field.
 * \note If the extended field already exists it will be overwritten with the new value.
 */
int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
 
/*!
 * \brief Get whether an object contains dynamic contents or not
 *
 * \param object Pointer to a sorcery object
 *
 * \since 19
 * \since 18.3.0
 * \since 16.17.0
 */
unsigned int ast_sorcery_object_has_dynamic_contents(const void *object);
 
/*!
 * \brief Set the dynamic contents flag on a sorcery object
 *
 * \param object Pointer to a sorcery object
 *
 * \since 19
 * \since 18.3.0
 * \since 16.17.0
 */
void ast_sorcery_object_set_has_dynamic_contents(const void *object);
 
/*!
 * \brief ao2 object comparator based on sorcery id.
 */
int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
 
/*!
 * \brief ao2 object sorter based on sorcery id.
 */
int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
 
/*!
 * \brief ao2 object hasher based on sorcery id.
 */
int ast_sorcery_object_id_hash(const void *obj, int flags);
 
/*!
 * \brief Get the sorcery object type given a type name.
 *
 * \param sorcery The sorcery from which to retrieve the object type
 * \param type The type name
 */
struct ast_sorcery_object_type *ast_sorcery_get_object_type(const struct ast_sorcery *sorcery,
        const char *type);
 
/*!
 * \brief Determine if a particular object field has been registered with sorcery
 *
 * \param object_type The object type to check against
 * \param field_name The name of the field to check
 *
 * \retval 0 The field is not registered for this sorcery type
 * \retval 1 The field is registered for this sorcery type
 */
int ast_sorcery_is_object_field_registered(const struct ast_sorcery_object_type *object_type,
        const char *field_name);
 
/*!
 * \brief Get the module that has opened the provided sorcery instance.
 *
 * \param sorcery The sorcery instance
 *
 * \return The module
 */
const char *ast_sorcery_get_module(const struct ast_sorcery *sorcery);
 
/**
 * \brief Global control for optional update->create fallback in backends.
 *
 * When non-zero, writable Sorcery backends may attempt to call create()
 * if update() indicates the object is missing (e.g., 0 rows affected or
 * NOT_FOUND). This helps re-populate backends that temporarily missed an
 * insert.
 *
 * Default is 0 (off) to maintain legacy behavior.
 *
 * Configured via sorcery.conf:
 *   [general]
 *   update_or_create_on_update_miss = yes|no
 *
 * NOTE: Backends MUST gate their fallback logic on this variable.
 */
extern int ast_sorcery_update_or_create_on_update_miss;
 
/*!
 * \section AstSorceryConvenienceMacros Simple Sorcery Convenience Macros
 *
 * For simple scenarios, the following macros can be used to register
 * common object fields.  The only requirement is that your source code's
 * definition of it's sorcery handle be named "sorcery".
 *
 * Example structure:
 * \code
 * struct my_sorcery_object {
 *   SORCERY_OBJECT(details);
 *   AST_DECLARE_STRING_FIELDS(
 *     AST_STRING_FIELD(mystring);
 *   );
 *  enum some_enum_type myenum;
 *  int myint;
 *  unsigned int myuint;
 *  int mybool;
 * };
 * \endcode
 *
 * Example object type registration:
 * \code
 * ast_sorcery_object_register(sorcery, "myobject", ...);
 * \endcode
 */
 
/*!
 * \brief Register a boolean field as type OPT_YESNO_T within an object.
 * \param object The unquoted object type.
 * \param structure The unquoted name of the structure that contains the field
 *                  without the "struct" prefix.
 * \param option The unquoted name of the option as it appears in the config file.
 * \param field The unquoted name of the field in the structure.
 * \param def_value The quoted default value of the field. Should be "yes" or "no"
 *
 * \code
 * ast_sorcery_register_bool(myobject, my_sorcery_object, mybool, mybool, "yes");
 * \endcode
 */
#define ast_sorcery_register_bool(object, structure, option, field, def_value) \
    ast_sorcery_object_field_register(sorcery, #object, #option, \
        def_value, OPT_YESNO_T, 1, \
        FLDSET(struct structure, field))
 
/*!
 * \internal
 * \brief Stringify a value.
 *
 * Needed because the preprocessor doesn't evaluate macros before it stringifies them.
 */
#define _sorcery_stringify(val) #val
 
/*!
 * \brief Register an int field as type OPT_INT_T within an object.
 * \param object The unquoted object type.
 * \param structure The unquoted name of the structure that contains the field
 *                  without the "struct" prefix.
 * \param option The unquoted name of the option as it appears in the config file.
 * \param field The unquoted name of the field in the structure.
 * \param def_value The unquoted default value of the field.
 *
 * \code
 * ast_sorcery_register_int(myobject, my_sorcery_object, myint, myint, -32);
 * \endcode
 */
#define ast_sorcery_register_int(object, structure, option, field, def_value) \
    ast_sorcery_object_field_register(sorcery, #object, #option, \
        _sorcery_stringify(def_value), OPT_INT_T, PARSE_IN_RANGE, \
        FLDSET(struct structure, field), INT_MIN, INT_MAX)
 
/*!
 * \brief Register an unsigned int field as type OPT_UINT_T within an object.
 * \param object The unquoted object type.
 * \param structure The unquoted name of the structure that contains the field
 *                  without the "struct" prefix.
 * \param option The unquoted name of the option as it appears in the config file.
 * \param field The unquoted name of the field in the structure.
 * \param def_value The unquoted default value of the field.
 *
 * \code
 * ast_sorcery_register_uint(myobject, my_sorcery_object, myint, myint, 32);
 * \endcode
 */
#define ast_sorcery_register_uint(object, structure, option, field, def_value) \
    ast_sorcery_object_field_register(sorcery, #object, #option, \
        _stringify(def_value), OPT_UINT_T, PARSE_IN_RANGE, \
        FLDSET(struct structure, field), 0, UINT_MAX)
 
/*!
 * \brief Register a stringfield field as type OPT_STRINGFIELD_T within an object.
 * \param object The unquoted object type.
 * \param structure The unquoted name of the structure that contains the field
 *                  without the "struct" prefix.
 * \param option The unquoted name of the option as it appears in the config file.
 * \param field The unquoted name of the field in the structure.
 * \param def_value The quoted default value of the field.
 *
 * \code
 * ast_sorcery_register_sf(myobject, my_sorcery_object, mystring, mystring, "");
 * \endcode
 */
#define ast_sorcery_register_sf(object, structure, option, field, def_value) \
    ast_sorcery_object_field_register(sorcery, #object, #option, \
        def_value, OPT_STRINGFIELD_T, 0, \
        STRFLDSET(struct structure, field))
 
/*!
 * \brief Register a custom field within an object.
 * \param object The unquoted object type.
 * \param structure The unquoted name of the structure that contains the field
 *                  without the "struct" prefix.
 * \param option The unquoted name of the option as it appears in the config file.
 *
 * \code
 * ast_sorcery_register_cust(myobject, my_sorcery_object, mystring);
 * \endcode
 *
 * \note
 * You must have defined the following standard sorcery custom handler functions:
 * \li myobject_mystring_from_str(const struct aco_option *opt, struct ast_variable *var, void *obj)
 * \li myobject_mystring_to_str(const void *obj, const intptr_t *args, char **buf)
 */
#define ast_sorcery_register_cust(object, option, def_value) \
    ast_sorcery_object_field_register_custom(sorcery, #object, #option, \
        def_value, object ## _ ## option ## _from_str, \
        object ## _ ## option ## _to_str, NULL, 0, 0)
 
 
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
 
#endif /* _ASTERISK_SORCERY_H */

ast_sorcery_apply_default

#define ast_sorcery_apply_default	(		sorcery,
			type,
			name,
			data
	)		__ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))

Definition at line 476 of file sorcery.h.

ast_sorcery_apply_wizard_mapping

#define ast_sorcery_apply_wizard_mapping	(		sorcery,
			type,
			name,
			data,
			caching
	)		__ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));

Apply additional object wizard mappings.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to apply to
name	Name of the wizard to use
data	Data to be passed to wizard
caching	Wizard should cache

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Definition at line 510 of file sorcery.h.

ast_sorcery_insert_wizard_mapping

#define ast_sorcery_insert_wizard_mapping	(		sorcery,
			type,
			name,
			data,
			caching,
			position
	)

Value:

    __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
        (caching), (position))

Insert an additional object wizard mapping at a specific position in the wizard list.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to apply to
name	Name of the wizard to use
data	Data to be passed to wizard
caching	Wizard should cache
position	One of ast_sorcery_wizard_position

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Since

13.4.0

Definition at line 562 of file sorcery.h.

ast_sorcery_internal_object_register

#define ast_sorcery_internal_object_register	(		sorcery,
			type,
			alloc,
			transform,
			apply
	)		__ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))

Register an internal, hidden object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
alloc	Required object allocation callback
transform	Optional transformation callback
apply	Optional object set apply callback

Return values

0	success
-1	failure

Definition at line 867 of file sorcery.h.

ast_sorcery_object_field_register

#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, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)

Register a field within an object.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
opt_type	Option type
flags	Option type specific flags

Return values

0	success
-1	failure

Definition at line 955 of file sorcery.h.

ast_sorcery_object_field_register_alias

#define ast_sorcery_object_field_register_alias	(		sorcery,
			type,
			name,
			default_val,
			opt_type,
			flags,
			...
	)		__ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)

Register a field within an object as an alias.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
opt_type	Option type
flags	Option type specific flags

Return values

0	success
-1	failure

Definition at line 971 of file sorcery.h.

ast_sorcery_object_field_register_custom

#define ast_sorcery_object_field_register_custom	(		sorcery,
			type,
			name,
			default_val,
			config_handler,
			sorcery_handler,
			multiple_handler,
			flags,
			...
	)		__ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);

Register a field within an object with custom handlers.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
config_handler	Custom configuration handler
sorcery_handler	Custom sorcery handler
multiple_handler	Custom multiple handler
flags	Option type specific flags

Return values

0	success
-1	failure

Definition at line 1005 of file sorcery.h.

ast_sorcery_object_field_register_custom_alias

#define ast_sorcery_object_field_register_custom_alias	(		sorcery,
			type,
			name,
			default_val,
			config_handler,
			sorcery_handler,
			multiple_handler,
			flags,
			...
	)		__ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__);

Register a field within an object with custom handlers as an alias.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
config_handler	Custom configuration handler
sorcery_handler	Custom sorcery handler
multiple_handler	Custom multiple handler
flags	Option type specific flags

Return values

0	success
-1	failure

Definition at line 1023 of file sorcery.h.

ast_sorcery_object_field_register_custom_nodoc

#define ast_sorcery_object_field_register_custom_nodoc	(		sorcery,
			type,
			name,
			default_val,
			config_handler,
			sorcery_handler,
			multiple_handler,
			flags,
			...
	)		__ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);

Register a field within an object with custom handlers without documentation.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
config_handler	Custom configuration handler
sorcery_handler	Custom sorcery handler
multiple_handler	Custom multiple handler
flags	Option type specific flags

Return values

0	success
-1	failure

Definition at line 1041 of file sorcery.h.

ast_sorcery_object_field_register_nodoc

#define ast_sorcery_object_field_register_nodoc	(		sorcery,
			type,
			name,
			default_val,
			opt_type,
			flags,
			...
	)		__ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)

Register a field within an object without documentation.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
opt_type	Option type
flags	Option type specific flags

Return values

0	success
-1	failure

Definition at line 987 of file sorcery.h.

ast_sorcery_object_register

#define ast_sorcery_object_register	(		sorcery,
			type,
			alloc,
			transform,
			apply
	)		__ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))

Register an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
alloc	Required object allocation callback
transform	Optional transformation callback
apply	Optional object set apply callback

Return values

0	success
-1	failure

Definition at line 837 of file sorcery.h.

ast_sorcery_object_register_no_reload

#define ast_sorcery_object_register_no_reload	(		sorcery,
			type,
			alloc,
			transform,
			apply
	)		__ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))

Register an object type that is not reloadable.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
alloc	Required object allocation callback
transform	Optional transformation callback
apply	Optional object set apply callback

Return values

0	success
-1	failure

Definition at line 852 of file sorcery.h.

ast_sorcery_object_type_apply_wizard

#define ast_sorcery_object_type_apply_wizard	(		sorcery,
			object_type_name,
			wizard_type_name,
			wizard_args,
			flags,
			wizard,
			wizard_data
	)

Value:

    __ast_sorcery_object_type_insert_wizard((sorcery), \
        (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
        AST_SORCERY_WIZARD_POSITION_LAST, (wizard), (wizard_data))

Apply additional object wizard mappings returning wizard information.

Since

13.26.0

16.3.0

Parameters

	sorcery	Pointer to a sorcery structure
	object_type_name	Name of the object type to apply to
	wizard_type_name	Name of the wizard type to use
	wizard_args	Opaque string to be passed to the wizard May be NULL but see note below
	flags	One or more of enum ast_sorcery_wizard_apply_flags
[out]	wizard	A variable to receive a pointer to the ast_sorcery_wizard structure. May be NULL if not needed.
[out]	wizard_data	A variable to receive a pointer to the wizard's internal data. May be NULL if not needed.

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Although wizard_args is an optional parameter it is highly recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE flag, and you intend to ever remove a wizard mapping, you'll need wizard_args to remove specific instances.

Definition at line 678 of file sorcery.h.

ast_sorcery_object_type_insert_wizard

#define ast_sorcery_object_type_insert_wizard	(		sorcery,
			object_type_name,
			wizard_type_name,
			wizard_args,
			flags,
			position,
			wizard,
			wizard_data
	)

Value:

    __ast_sorcery_object_type_insert_wizard((sorcery), \
        (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
        position, (wizard), (wizard_data))

Insert an additional object wizard mapping at a specific position in the wizard list returning wizard information.

Since

13.26.0

16.3.0

Parameters

	sorcery	Pointer to a sorcery structure
	object_type_name	Name of the object type to apply to
	wizard_type_name	Name of the wizard type to use
	wizard_args	Opaque string to be passed to the wizard May be NULL but see note below
	flags	One or more of enum ast_sorcery_wizard_apply_flags
	position	An index to insert to or one of ast_sorcery_wizard_position
[out]	wizard	A variable to receive a pointer to the ast_sorcery_wizard structure. May be NULL if not needed.
[out]	wizard_data	A variable to receive a pointer to the wizard's internal data. May be NULL if not needed.

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Although wizard_args is an optional parameter it is highly recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE flag, and you intend to ever remove a wizard mapping, you'll need wizard_args to remove specific instances.

Definition at line 646 of file sorcery.h.

ast_sorcery_object_type_remove_wizard

#define ast_sorcery_object_type_remove_wizard	(		sorcery,
			object_type_name,
			wizard_type_name,
			wizard_args
	)

Value:

    __ast_sorcery_object_type_remove_wizard((sorcery), (object_type_name), \
        AST_MODULE, (wizard_type_name), (wizard_args))

Remove an object wizard mapping.

Since

13.26.0

16.3.0

Parameters

sorcery	Pointer to a sorcery structure
object_type_name	Name of the object type to remove from
wizard_type_name	The name of the of the wizard type to remove
wizard_args	Opaque string originally passed to the wizard

Return values

0	success
-1	failure

Note

If there were multiple instances of the same wizard type added to this object type without using wizard_args, then only the first wizard matching wizard_type will be removed.

Definition at line 724 of file sorcery.h.

ast_sorcery_objectset_create

#define ast_sorcery_objectset_create	(		sorcery,
			object
	)		ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)

Create an object set (KVP list) for an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object

Return values

non-NULL	success
NULL	if error occurred

Note

The returned ast_variable list must be destroyed using ast_variables_destroy

This function attempts to use a field's sorcery_fields_handler first and if that doesn't exist or fails, a field's sorcery_field_handler is used. The difference is that the former may return multiple list entries for the same field and the latter will only return 1. It's up to the field itself to determine what the appropriate content is.

Definition at line 1137 of file sorcery.h.

ast_sorcery_open

#define ast_sorcery_open

(

)

__ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Open a new sorcery structure.

Parameters

module

The module name (AST_MODULE)

When called, this will automatically also call __ast_sorcery_apply_config() with the module name as the configuration section.

Return values

non-NULL	success
NULL	if allocation failed

Definition at line 406 of file sorcery.h.

ast_sorcery_register_bool

#define ast_sorcery_register_bool	(		object,
			structure,
			option,
			field,
			def_value
	)

Value:

    ast_sorcery_object_field_register(sorcery, #object, #option, \
        def_value, OPT_YESNO_T, 1, \
        FLDSET(struct structure, field))

Register a boolean field as type OPT_YESNO_T within an object.

Simple Sorcery Convenience Macros

For simple scenarios, the following macros can be used to register common object fields. The only requirement is that your source code's definition of it's sorcery handle be named "sorcery".

Example structure:

struct my_sorcery_object {
  SORCERY_OBJECT(details);
  AST_DECLARE_STRING_FIELDS(
    AST_STRING_FIELD(mystring);
  );
 enum some_enum_type myenum;
 int myint;
 unsigned int myuint;
 int mybool;
};

Example object type registration:

ast_sorcery_object_register(sorcery, "myobject", ...);

Parameters

object	The unquoted object type.
structure	The unquoted name of the structure that contains the field without the "struct" prefix.
option	The unquoted name of the option as it appears in the config file.
field	The unquoted name of the field in the structure.
def_value	The quoted default value of the field. Should be "yes" or "no"

ast_sorcery_register_bool(myobject, my_sorcery_object, mybool, mybool, "yes");

Definition at line 1684 of file sorcery.h.

ast_sorcery_register_cust

#define ast_sorcery_register_cust	(		object,
			option,
			def_value
	)

Value:

    ast_sorcery_object_field_register_custom(sorcery, #object, #option, \
        def_value, object ## _ ## option ## _from_str, \
        object ## _ ## option ## _to_str, NULL, 0, 0)

Register a custom field within an object.

Parameters

object	The unquoted object type.
structure	The unquoted name of the structure that contains the field without the "struct" prefix.
option	The unquoted name of the option as it appears in the config file.

ast_sorcery_register_cust(myobject, my_sorcery_object, mystring);

Note

You must have defined the following standard sorcery custom handler functions:

• myobject_mystring_from_str(const struct aco_option *opt, struct ast_variable *var, void *obj)
• myobject_mystring_to_str(const void *obj, const intptr_t *args, char **buf)

Definition at line 1767 of file sorcery.h.

ast_sorcery_register_int

#define ast_sorcery_register_int	(		object,
			structure,
			option,
			field,
			def_value
	)

Value:

    ast_sorcery_object_field_register(sorcery, #object, #option, \
        _sorcery_stringify(def_value), OPT_INT_T, PARSE_IN_RANGE, \
        FLDSET(struct structure, field), INT_MIN, INT_MAX)

Register an int field as type OPT_INT_T within an object.

Parameters

object	The unquoted object type.
structure	The unquoted name of the structure that contains the field without the "struct" prefix.
option	The unquoted name of the option as it appears in the config file.
field	The unquoted name of the field in the structure.
def_value	The unquoted default value of the field.

ast_sorcery_register_int(myobject, my_sorcery_object, myint, myint, -32);

Definition at line 1710 of file sorcery.h.

ast_sorcery_register_sf

#define ast_sorcery_register_sf	(		object,
			structure,
			option,
			field,
			def_value
	)

Value:

    ast_sorcery_object_field_register(sorcery, #object, #option, \
        def_value, OPT_STRINGFIELD_T, 0, \
        STRFLDSET(struct structure, field))

Register a stringfield field as type OPT_STRINGFIELD_T within an object.

Parameters

object	The unquoted object type.
structure	The unquoted name of the structure that contains the field without the "struct" prefix.
option	The unquoted name of the option as it appears in the config file.
field	The unquoted name of the field in the structure.
def_value	The quoted default value of the field.

ast_sorcery_register_sf(myobject, my_sorcery_object, mystring, mystring, "");

Definition at line 1746 of file sorcery.h.

ast_sorcery_register_uint

#define ast_sorcery_register_uint	(		object,
			structure,
			option,
			field,
			def_value
	)

Value:

    ast_sorcery_object_field_register(sorcery, #object, #option, \
        _stringify(def_value), OPT_UINT_T, PARSE_IN_RANGE, \
        FLDSET(struct structure, field), 0, UINT_MAX)

Register an unsigned int field as type OPT_UINT_T within an object.

Parameters

object	The unquoted object type.
structure	The unquoted name of the structure that contains the field without the "struct" prefix.
option	The unquoted name of the option as it appears in the config file.
field	The unquoted name of the field in the structure.
def_value	The unquoted default value of the field.

ast_sorcery_register_uint(myobject, my_sorcery_object, myint, myint, 32);

Definition at line 1728 of file sorcery.h.

ast_sorcery_remove_wizard_mapping

#define ast_sorcery_remove_wizard_mapping	(		sorcery,
			type,
			name
	)		__ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))

Remove an object wizard mapping.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to remove from
name	The name of the wizard to remove

Return values

0	success
-1	failure

Since

13.4.0

Definition at line 757 of file sorcery.h.

ast_sorcery_unref

#define ast_sorcery_unref

(

sorcery

)

ao2_cleanup(sorcery)

Decrease the reference count of a sorcery structure.

Parameters

sorcery

Pointer to a sorcery structure

Note

Prior to 16.0.0 this was a function which had to be used. Now you can use any variant of ao2_cleanup or ao2_ref to release a reference.

Definition at line 1500 of file sorcery.h.

ast_sorcery_wizard_register

#define ast_sorcery_wizard_register

(

interface

)

__ast_sorcery_wizard_register(interface, AST_MODULE_SELF)

See __ast_sorcery_wizard_register()

Definition at line 383 of file sorcery.h.

MAX_OBJECT_FIELD

#define MAX_OBJECT_FIELD   128

Maximum length of an object field name.

Definition at line 110 of file sorcery.h.

MAX_OBJECT_TYPE

#define MAX_OBJECT_TYPE   64

Maximum size of an object type.

Definition at line 107 of file sorcery.h.

SORCERY_OBJECT

#define SORCERY_OBJECT

(

details

)

Value:

struct {                                           \
    struct ast_sorcery_object_details details; \
}                                                  \

Macro which must be used at the beginning of each sorcery capable object.

Definition at line 356 of file sorcery.h.

       {                                           \
    struct ast_sorcery_object_details details; \
}                                                  \
 

Typedef Documentation

sorcery_apply_handler

typedef int(* sorcery_apply_handler) (const struct ast_sorcery *sorcery, void *obj)

A callback function for when an object set is successfully applied to an object.

Note

On a failure return, the state of the object is left undefined. It is a bad idea to try to use this object.

Parameters

sorcery	Sorcery structure in use
obj	The object itself

Return values

0	Success
non-zero	Failure

Definition at line 194 of file sorcery.h.

sorcery_copy_handler

typedef int(* sorcery_copy_handler) (const void *src, void *dst)

A callback function for copying the contents of one object to another.

Parameters

src	The source object
dst	The destination object

Return values

0	success
-1	failure

Definition at line 205 of file sorcery.h.

sorcery_diff_handler

typedef int(* sorcery_diff_handler) (const void *original, const void *modified, struct ast_variable **changes)

A callback function for generating a changeset between two objects.

Parameters

original	The original object
modified	The modified object
changes	The changeset

Return values

0	success
-1	failure

Definition at line 217 of file sorcery.h.

sorcery_field_handler

typedef int(* sorcery_field_handler) (const void *obj, const intptr_t *args, char **buf)

A callback function for translating a value into a string.

Parameters

obj	Object to get value from
args	Where the field is
buf	Pointer to the buffer that the handler has created which contains the field value

Return values

0	success
-1	failure

Definition at line 158 of file sorcery.h.

sorcery_fields_handler

typedef int(* sorcery_fields_handler) (const void *obj, struct ast_variable **fields)

A callback function for translating multiple values into an ast_variable list.

Parameters

obj	Object to get values from
fields	Pointer to store the list of fields

Return values

0	success
-1	failure

Definition at line 169 of file sorcery.h.

sorcery_transform_handler

typedef struct ast_variable *(* sorcery_transform_handler) (struct ast_variable *set)

A callback function for performing a transformation on an object set.

Parameters

set	The existing object set

Return values

non-NULL	new object set if changed
NULL	if no changes present

Note

The returned ast_variable list must be new. You can not return the input set.

Definition at line 169 of file sorcery.h.

Enumeration Type Documentation

ast_sorcery_apply_result

enum ast_sorcery_apply_result

Enumerator
AST_SORCERY_APPLY_FAIL	Sorcery wizard failed to apply.
AST_SORCERY_APPLY_SUCCESS	Sorcery wizard applied successfully.
AST_SORCERY_APPLY_DUPLICATE	Sorcery wizard has already been applied to the object type.
AST_SORCERY_APPLY_DEFAULT_UNNECESSARY	Default sorcery wizard is unnecessary since a wizard has already been applied to the object type.
AST_SORCERY_APPLY_NO_CONFIGURATION	No sorcery.conf configuration file was found to apply.

Definition at line 423 of file sorcery.h.

                              {
    /*! Sorcery wizard failed to apply. */
    AST_SORCERY_APPLY_FAIL = -1,
    /*! Sorcery wizard applied successfully. */
    AST_SORCERY_APPLY_SUCCESS = 0,
    /*! Sorcery wizard has already been applied to the object type. */
    AST_SORCERY_APPLY_DUPLICATE = 1,
    /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
    AST_SORCERY_APPLY_DEFAULT_UNNECESSARY = 2,
    /*! No sorcery.conf configuration file was found to apply. */
    AST_SORCERY_APPLY_NO_CONFIGURATION = 3,
};

ast_sorcery_field_handler_flags

enum ast_sorcery_field_handler_flags

Field handler flags.

Enumerator
AST_HANDLER_PREFER_STRING	Try both handlers, string first.
AST_HANDLER_PREFER_LIST	Try both handlers, list first.
AST_HANDLER_ONLY_STRING	Use string handler only.
AST_HANDLER_ONLY_LIST	Use list handler only.

Definition at line 129 of file sorcery.h.

                                     {
    /*! \brief Try both handlers, string first */
    AST_HANDLER_PREFER_STRING,
 
    /*! \brief Try both handlers, list first */
    AST_HANDLER_PREFER_LIST,
 
    /*! \brief Use string handler only */
    AST_HANDLER_ONLY_STRING,
 
    /*! \brief Use list handler only */
    AST_HANDLER_ONLY_LIST,
};

ast_sorcery_retrieve_flags

enum ast_sorcery_retrieve_flags

Retrieval flags.

Enumerator
AST_RETRIEVE_FLAG_DEFAULT	Default retrieval flags.
AST_RETRIEVE_FLAG_MULTIPLE	Return all matching objects.
AST_RETRIEVE_FLAG_ALL	Perform no matching, return all objects.

Definition at line 115 of file sorcery.h.

                                {
    /*! \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),
};

ast_sorcery_wizard_apply_flags

enum ast_sorcery_wizard_apply_flags

Wizard Apply Flags.

These flags apply only to a wizard/object-type combination. The same wizard may be applied to a different object-type with different flags and behavior. If ALLOW_DUPLICATE is set the wizard could even be applied to the same object-type with different flags.

Enumerator
AST_SORCERY_WIZARD_APPLY_NONE	Apply no special behavior
AST_SORCERY_WIZARD_APPLY_CACHING	This wizard will cache this object type's entries
AST_SORCERY_WIZARD_APPLY_READONLY	This wizard won't allow Create, Update or Delete operations on this object type
AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE	This wizard will allow other instances of itself on the same object type

Definition at line 575 of file sorcery.h.

                                    {
    /*! Apply no special behavior */
    AST_SORCERY_WIZARD_APPLY_NONE = (0 << 0),
    /*! This wizard will cache this object type's entries */
    AST_SORCERY_WIZARD_APPLY_CACHING = (1 << 0),
    /*! This wizard won't allow Create, Update or Delete operations on this object type */
    AST_SORCERY_WIZARD_APPLY_READONLY = (1 << 1),
    /*! This wizard will allow other instances of itself on the same object type */
    AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE = (1 << 2)
};

ast_sorcery_wizard_position

enum ast_sorcery_wizard_position

Pre-defined locations to insert at.

Enumerator
AST_SORCERY_WIZARD_POSITION_LAST
AST_SORCERY_WIZARD_POSITION_FIRST

Definition at line 517 of file sorcery.h.

                                 {
    AST_SORCERY_WIZARD_POSITION_LAST = -1,
    AST_SORCERY_WIZARD_POSITION_FIRST = 0,
};

Function Documentation

__ast_sorcery_apply_config()

enum ast_sorcery_apply_result __ast_sorcery_apply_config	(	struct ast_sorcery *	sorcery,
		const char *	name,
		const char *	module
	)

Apply configured wizard mappings.

Parameters

sorcery	Pointer to a sorcery structure
name	Name of the category to use within the configuration file, normally the module name
module	The module name (AST_MODULE)

This function is called automatically by __ast_sorcery_open() using the module name as the configuration category. The only reason you should call this function is if your module wishes to apply configuration from additional sections of sorcery.conf.

If a configuration section attempts to apply the same sorcery wizard to an object type more than once, the wizard will only be applied one time.

Returns

What happened when attempting to apply the config.

Definition at line 1049 of file sorcery.c.

{
    struct ast_flags flags = { 0 };
    struct ast_config *config = ast_config_load2("sorcery.conf", "sorcery", flags);
    struct ast_variable *mapping;
    int res = AST_SORCERY_APPLY_SUCCESS;
 
    if (!config) {
        return AST_SORCERY_APPLY_NO_CONFIGURATION;
    }
 
    if (config == CONFIG_STATUS_FILEINVALID) {
        return AST_SORCERY_APPLY_FAIL;
    }
 
    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;
        char *type = strsep(&options, "/");
        char *data = mapping_value;
        char *wizard = strsep(&data, ",");
        unsigned int caching = 0;
 
        /* If no object type or wizard exists just skip, nothing we can do */
        if (ast_strlen_zero(type) || 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 (__ast_sorcery_apply_wizard_mapping(sorcery, type, module, wizard, data, caching) == AST_SORCERY_APPLY_FAIL) {
            res = AST_SORCERY_APPLY_FAIL;
            break;
        }
    }
 
    ast_config_destroy(config);
 
    return res;
}

References __ast_sorcery_apply_wizard_mapping(), ast_config_destroy(), ast_config_load2(), ast_free, AST_SORCERY_APPLY_FAIL, AST_SORCERY_APPLY_NO_CONFIGURATION, AST_SORCERY_APPLY_SUCCESS, ast_strdup, ast_strlen_zero(), ast_variable_browse(), config, CONFIG_STATUS_FILEINVALID, ast_flags::flags, name, ast_variable::name, ast_variable::next, options, RAII_VAR, sorcery, strsep(), type, and ast_variable::value.

Referenced by __ast_sorcery_open().

__ast_sorcery_apply_default()

enum ast_sorcery_apply_result __ast_sorcery_apply_default	(	struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	module,
		const char *	name,
		const char *	data
	)

Apply default object wizard mappings.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to apply to
module	The name of the module, typically AST_MODULE
name	Name of the wizard to use
data	Data to be passed to wizard

Returns

What occurred when applying the default

Note

This should be called after applying configuration sourced mappings

Only a single default can exist per object type

Definition at line 1095 of file sorcery.c.

{
    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 AST_SORCERY_APPLY_DEFAULT_UNNECESSARY;
    }
 
    return __ast_sorcery_apply_wizard_mapping(sorcery, type, module, name, data, 0);
}

References __ast_sorcery_apply_wizard_mapping(), ao2_cleanup, ao2_find, AST_SORCERY_APPLY_DEFAULT_UNNECESSARY, name, OBJ_KEY, RAII_VAR, sorcery, type, and ast_sorcery::types.

__ast_sorcery_apply_wizard_mapping()

enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping	(	struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	module,
		const char *	name,
		const char *	data,
		unsigned int	caching
	)

Apply additional object wizard mappings.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to apply to
module	The name of the module, typically AST_MODULE
name	Name of the wizard to use
data	Data to be passed to wizard
caching	Wizard should cache

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Apply additional object wizard mappings.

Definition at line 1041 of file sorcery.c.

{
    return __ast_sorcery_insert_wizard_mapping(sorcery, type, module, name,
        data, caching, AST_SORCERY_WIZARD_POSITION_LAST);
}

References __ast_sorcery_insert_wizard_mapping(), AST_SORCERY_WIZARD_POSITION_LAST, ast_sorcery_object_wizard::caching, ast_sorcery_object_wizard::data, name, sorcery, and type.

Referenced by __ast_sorcery_apply_config(), and __ast_sorcery_apply_default().

__ast_sorcery_insert_wizard_mapping()

enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping	(	struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	module,
		const char *	name,
		const char *	data,
		unsigned int	caching,
		int	position
	)

Insert an additional object wizard mapping at a specific position in the wizard list.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to apply to
module	The name of the module, typically AST_MODULE
name	Name of the wizard to use
data	Data to be passed to wizard
caching	Wizard should cache
position	An index to insert to or one of ast_sorcery_wizard_position

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count and iterating over them using ast_sorcery_get_wizard_mapping.

Since

13.4.0

Insert an additional object wizard mapping at a specific position in the wizard list.

Definition at line 1031 of file sorcery.c.

{
    return __ast_sorcery_object_type_insert_wizard(sorcery, type, module, name,
        data, caching ? AST_SORCERY_WIZARD_APPLY_CACHING : AST_SORCERY_WIZARD_APPLY_NONE,
        position, NULL, NULL);
}

References __ast_sorcery_object_type_insert_wizard(), AST_SORCERY_WIZARD_APPLY_CACHING, AST_SORCERY_WIZARD_APPLY_NONE, ast_sorcery_object_wizard::caching, ast_sorcery_object_wizard::data, name, NULL, sorcery, and type.

Referenced by __ast_sorcery_apply_wizard_mapping().

__ast_sorcery_object_field_register()

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,
		sorcery_fields_handler	multiple_handler,
		unsigned int	flags,
		unsigned int	no_doc,
		unsigned int	alias,
		size_t	argc,
			...
	)

Register a field within an object.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
name	Name of the field
default_val	Default value of the field
config_handler	A custom handler for translating the string representation of the fields
sorcery_handler	A custom handler for translating the native representation of the fields
multiple_handler	A custom handler for translating the native representation of the fields
opt_type	Option type
flags	Option type specific flags
no_doc	Field should not be documented
alias	Interpret and apply field value only
argc

Return values

0	success
-1	failure

Definition at line 1256 of file sorcery.c.

{
    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 (!strcmp(type, "id") || !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))) {
        return -1;
    }
 
    ast_copy_string(object_field->name, name, sizeof(object_field->name));
    object_field->handler = sorcery_handler;
    object_field->multiple_handler = multiple_handler;
 
    va_start(args, argc);
    for (pos = 0; pos < argc; pos++) {
        object_field->args[pos] = va_arg(args, size_t);
    }
    va_end(args);
 
    if (!alias) {
        ao2_link(object_type->fields, object_field);
    }
 
    /* TODO: Improve this hack */
    if (!argc) {
        __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc);
    } else if (argc == 1) {
        __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
            object_field->args[0]);
    } else if (argc == 2) {
        __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
            object_field->args[0], object_field->args[1]);
    } else if (argc == 3) {
        __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
            object_field->args[0], object_field->args[1], object_field->args[2]);
    } else {
        ast_assert(0); /* The hack... she does us no good for this */
    }
 
    return 0;
}

References __aco_option_register(), ACO_EXACT, ao2_alloc, ao2_cleanup, ao2_find, ao2_link, args, ast_assert, ast_copy_string(), ast_sorcery_object_field::multiple_handler, name, NULL, OBJ_KEY, RAII_VAR, sorcery, sorcery_field_default_handler(), type, and ast_sorcery::types.

__ast_sorcery_object_register()

int __ast_sorcery_object_register	(	struct ast_sorcery *	sorcery,
		const char *	type,
		unsigned int	hidden,
		unsigned int	reloadable,
		aco_type_item_alloc	alloc,
		sorcery_transform_handler	transform,
		sorcery_apply_handler	apply
	)

Register an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
hidden	All objects of this type are internal and should not be manipulated by users
reloadable	All objects of this type are reloadable
alloc	Required object allocation callback
transform	Optional transformation callback
apply	Optional object set apply callback

Note

In general, this function should not be used directly. One of the various macro'd versions should be used instead.

Return values

0	success
-1	failure

Definition at line 1144 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
 
    if (!object_type || object_type->type.item_alloc) {
        return -1;
    }
 
    object_type->type.name = object_type->name;
    object_type->type.type = ACO_ITEM;
    object_type->type.category = ".?";
    object_type->type.item_alloc = alloc;
    object_type->type.hidden = hidden;
 
    object_type->reloadable = reloadable;
    object_type->transform = transform;
    object_type->apply = apply;
    object_type->file->types[0] = &object_type->type;
    object_type->file->types[1] = NULL;
 
    if (aco_info_init(object_type->info)) {
        return -1;
    }
 
    if (ast_sorcery_object_fields_register(sorcery, type, "^@", sorcery_extended_config_handler, sorcery_extended_fields_handler)) {
        return -1;
    }
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, object_type_registered,
        sorcery->module_name, sorcery, type);
 
    return 0;
}

References aco_info_init(), ACO_ITEM, ao2_cleanup, ao2_find, ast_sorcery_object_type::apply, ast_sorcery_object_fields_register(), ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, NULL, OBJ_KEY, ast_sorcery::observers, RAII_VAR, ast_sorcery_object_type::reloadable, sorcery, sorcery_extended_config_handler(), sorcery_extended_fields_handler(), ast_sorcery_object_type::transform, type, and ast_sorcery::types.

__ast_sorcery_object_type_insert_wizard()

enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard	(	struct ast_sorcery *	sorcery,
		const char *	object_type_name,
		const char *	module,
		const char *	wizard_type_name,
		const char *	wizard_args,
		enum ast_sorcery_wizard_apply_flags	flags,
		int	position,
		struct ast_sorcery_wizard **	wizard,
		void **	wizard_data
	)

Insert an additional object wizard mapping at a specific position in the wizard list returning wizard information.

Since

13.26.0

16.3.0

Parameters

	sorcery	Pointer to a sorcery structure
	object_type_name	Name of the object type to apply to
	module	The name of the module, typically AST_MODULE
	wizard_type_name	Name of the wizard type to use
	wizard_args	Opaque string to be passed to the wizard May be NULL but see note below
	flags	One or more of enum ast_sorcery_wizard_apply_flags
	position	An index to insert to or one of ast_sorcery_wizard_position
[out]	wizard	A variable to receive a pointer to the ast_sorcery_wizard structure. May be NULL if not needed.
[out]	wizard_data	A variable to receive a pointer to the wizard's internal data. May be NULL if not needed.

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Although wizard_args is an optional parameter it is highly recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE flag, and you intend to ever remove a wizard mapping, you'll need wizard_args to remove specific instances of a wizard type.

Definition at line 933 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, object_type_name, OBJ_KEY), ao2_cleanup);
    RAII_VAR(struct ast_sorcery_internal_wizard *, internal_wizard, ao2_find(wizards, wizard_type_name, OBJ_KEY), ao2_cleanup);
    RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, NULL, ao2_cleanup);
    int created = 0;
 
    object_wizard = ao2_alloc(sizeof(*object_wizard)
        + (ast_strlen_zero(wizard_args) ? 0 : strlen(wizard_args) + 1),
        sorcery_object_wizard_destructor);
 
    if (!object_wizard) {
        return AST_SORCERY_APPLY_FAIL;
    }
 
    if (!internal_wizard
        || internal_wizard->callbacks.module != ast_module_running_ref(internal_wizard->callbacks.module)) {
        ast_log(LOG_ERROR,
            "Wizard '%s' could not be applied to object type '%s' as it was not found\n",
            wizard_type_name, object_type_name);
        return AST_SORCERY_APPLY_FAIL;
    }
 
    if (!object_type) {
        if (!(object_type = sorcery_object_type_alloc(object_type_name, module))) {
            ast_module_unref(internal_wizard->callbacks.module);
            return AST_SORCERY_APPLY_FAIL;
        }
        created = 1;
    }
 
    AST_VECTOR_RW_WRLOCK(&object_type->wizards);
    if (!created) {
        struct ast_sorcery_object_wizard *found;
 
#define WIZARD_COMPARE(a, b) ((a)->wizard == (b))
        found = AST_VECTOR_GET_CMP(&object_type->wizards, internal_wizard, WIZARD_COMPARE);
#undef WIZARD_COMPARE
        if (found
            && !((flags & AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE) || found->allow_duplicates)) {
            ast_debug(1, "Wizard %s already applied to object type %s\n",
                internal_wizard->callbacks.name, object_type->name);
            AST_VECTOR_RW_UNLOCK(&object_type->wizards);
            ast_module_unref(internal_wizard->callbacks.module);
            return AST_SORCERY_APPLY_DUPLICATE;
        }
    }
 
    ast_debug(5, "Calling wizard %s open callback on object type %s\n",
        wizard_type_name, object_type->name);
    if (internal_wizard->callbacks.open && !(object_wizard->data = internal_wizard->callbacks.open(wizard_args))) {
        ast_log(LOG_WARNING, "Wizard '%s' failed to open mapping for object type '%s' with data: %s\n",
            wizard_type_name, object_type->name, S_OR(wizard_args, ""));
        AST_VECTOR_RW_UNLOCK(&object_type->wizards);
        ast_module_unref(internal_wizard->callbacks.module);
        return AST_SORCERY_APPLY_FAIL;
    }
 
    object_wizard->wizard = ao2_bump(internal_wizard);
    object_wizard->caching = !!(flags & AST_SORCERY_WIZARD_APPLY_CACHING);
    object_wizard->read_only = !!(flags & AST_SORCERY_WIZARD_APPLY_READONLY);
    if (wizard_args) {
        strcpy(object_wizard->wizard_args, wizard_args); /* Safe */
    }
 
    if (position == AST_SORCERY_WIZARD_POSITION_LAST) {
        position = AST_VECTOR_SIZE(&object_type->wizards);
    }
 
    if (AST_VECTOR_INSERT_AT(&object_type->wizards, position, object_wizard) != 0) {
        AST_VECTOR_RW_UNLOCK(&object_type->wizards);
        return AST_SORCERY_APPLY_FAIL;
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
    ao2_bump(object_wizard);
 
    if (created) {
        ao2_link(sorcery->types, object_type);
    }
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, wizard_mapped,
        sorcery->module_name, sorcery, object_type_name, &internal_wizard->callbacks, wizard_args,
        object_wizard->data);
 
    if (wizard) {
        *wizard = &internal_wizard->callbacks;
    }
    if (wizard_data) {
        *wizard_data = object_wizard->data;
    }
 
    return AST_SORCERY_APPLY_SUCCESS;
}

References ast_sorcery_object_wizard::allow_duplicates, ao2_alloc, ao2_bump, ao2_cleanup, ao2_find, ao2_link, ast_debug, ast_log, ast_module_running_ref, ast_module_unref, AST_SORCERY_APPLY_DUPLICATE, AST_SORCERY_APPLY_FAIL, AST_SORCERY_APPLY_SUCCESS, AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE, AST_SORCERY_WIZARD_APPLY_CACHING, AST_SORCERY_WIZARD_APPLY_READONLY, AST_SORCERY_WIZARD_POSITION_LAST, ast_strlen_zero(), AST_VECTOR_GET_CMP, AST_VECTOR_INSERT_AT, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, LOG_ERROR, LOG_WARNING, ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, NULL, OBJ_KEY, ast_sorcery::observers, RAII_VAR, S_OR, sorcery, sorcery_object_type_alloc(), sorcery_object_wizard_destructor(), ast_sorcery::types, ast_sorcery_object_wizard::wizard, ast_sorcery_object_wizard::wizard_args, WIZARD_COMPARE, and wizards.

Referenced by __ast_sorcery_insert_wizard_mapping().

__ast_sorcery_object_type_remove_wizard()

int __ast_sorcery_object_type_remove_wizard	(	struct ast_sorcery *	sorcery,
		const char *	object_type_name,
		const char *	module,
		const char *	wizard_type_name,
		const char *	wizard_args
	)

Remove an object wizard mapping.

Since

13.26.0

16.3.0

Parameters

sorcery	Pointer to a sorcery structure
object_type_name	Name of the object type to remove from
module	The name of the module, typically AST_MODULE
wizard_type_name	The name of the of the wizard type to remove
wizard_args	Opaque string originally passed to the wizard

Return values

0	success
-1	failure

Note

If there were multiple instances of the same wizard type added to this object type without using wizard_args, then only the first wizard matching wizard_type will be removed.

Definition at line 884 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type,
        ao2_find(sorcery->types, object_type_name, OBJ_SEARCH_KEY), ao2_cleanup);
    int res = -1;
    int i;
 
    if (!object_type) {
        return res;
    }
 
    AST_VECTOR_RW_WRLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        struct ast_sorcery_object_wizard *wizard = AST_VECTOR_GET(&object_type->wizards, i);
 
        if (strcmp(wizard->wizard->callbacks.name, wizard_type_name) == 0
            && strcmp(S_OR(wizard->wizard_args, ""), S_OR(wizard_args, "")) == 0) {
            ao2_cleanup(AST_VECTOR_REMOVE_ORDERED(&object_type->wizards, i));
            res = 0;
            break;
        }
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return res;
}

References ao2_cleanup, ao2_find, AST_VECTOR_GET, AST_VECTOR_REMOVE_ORDERED, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, ast_sorcery_wizard::name, OBJ_SEARCH_KEY, RAII_VAR, S_OR, sorcery, ast_sorcery::types, ast_sorcery_object_wizard::wizard, and ast_sorcery_object_wizard::wizard_args.

__ast_sorcery_open()

struct ast_sorcery * __ast_sorcery_open	(	const char *	module,
		const char *	file,
		int	line,
		const char *	func
	)

Definition at line 665 of file sorcery.c.

{
    struct sorcery_proxy *proxy;
    struct ast_sorcery *sorcery;
 
    ast_assert(module_name != NULL);
 
    ao2_wrlock(instances);
    sorcery = __ao2_weakproxy_find(instances, module_name, OBJ_SEARCH_KEY | OBJ_NOLOCK,
        __PRETTY_FUNCTION__, file, line, func);
    if (sorcery) {
        ao2_unlock(instances);
 
        return sorcery;
    }
 
    proxy = ao2_t_weakproxy_alloc(sizeof(*proxy) + strlen(module_name) + 1, NULL, module_name);
    if (!proxy) {
        goto failure_cleanup;
    }
    strcpy(proxy->module_name, module_name); /* Safe */
 
    sorcery = __ao2_alloc(sizeof(*sorcery), sorcery_destructor, AO2_ALLOC_OPT_LOCK_MUTEX, module_name, file, line, func);
    if (!sorcery) {
        goto failure_cleanup;
    }
 
    sorcery->module_name = proxy->module_name;
 
    /* We have exclusive access to proxy and sorcery, no need for locking here. */
    if (ao2_t_weakproxy_set_object(proxy, sorcery, OBJ_NOLOCK, "weakproxy link")) {
        goto failure_cleanup;
    }
 
    if (ao2_weakproxy_subscribe(proxy, sorcery_proxy_cb, NULL, OBJ_NOLOCK)) {
        goto failure_cleanup;
    }
 
    sorcery->types = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, TYPE_BUCKETS,
        ast_sorcery_object_type_hash_fn, NULL, ast_sorcery_object_type_cmp_fn);
    if (!sorcery->types) {
        goto failure_cleanup;
    }
 
    if (!(sorcery->observers = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, NULL, NULL))) {
        goto failure_cleanup;
    }
 
    if (__ast_sorcery_apply_config(sorcery, module_name, module_name) == AST_SORCERY_APPLY_FAIL) {
        ast_log(LOG_ERROR, "Error attempting to apply configuration %s to sorcery.\n", module_name);
        goto failure_cleanup;
    }
 
    ao2_link_flags(instances, proxy, OBJ_NOLOCK);
    ao2_ref(proxy, -1);
 
    NOTIFY_GLOBAL_OBSERVERS(observers, instance_created, module_name, sorcery);
 
    ao2_unlock(instances);
    return sorcery;
 
failure_cleanup:
    /* cleanup of sorcery may result in locking instances, so make sure we unlock first. */
    ao2_unlock(instances);
    ao2_cleanup(sorcery);
    ao2_cleanup(proxy);
 
    return NULL;
}

References __ao2_alloc(), __ao2_weakproxy_find(), __ast_sorcery_apply_config(), AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_cleanup, ao2_container_alloc_hash, ao2_container_alloc_list, ao2_link_flags, ao2_ref, ao2_t_weakproxy_alloc, ao2_t_weakproxy_set_object, ao2_unlock, ao2_weakproxy_subscribe(), ao2_wrlock, ast_assert, ast_log, AST_SORCERY_APPLY_FAIL, instances, LOG_ERROR, sorcery_proxy::module_name, ast_sorcery::module_name, NOTIFY_GLOBAL_OBSERVERS, NULL, OBJ_NOLOCK, OBJ_SEARCH_KEY, ast_sorcery::observers, observers, sorcery, sorcery_destructor(), sorcery_proxy_cb(), TYPE_BUCKETS, and ast_sorcery::types.

__ast_sorcery_remove_wizard_mapping()

int __ast_sorcery_remove_wizard_mapping	(	struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	module,
		const char *	name
	)

Remove an object wizard mapping.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to remove from
module	The name of the module, typically AST_MODULE
name	The name of the wizard to remove

Return values

0	success
-1	failure

Since

13.4.0

Remove an object wizard mapping.

Definition at line 914 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    int res;
 
    if (!object_type) {
        return -1;
    }
 
    AST_VECTOR_RW_WRLOCK(&object_type->wizards);
#define WIZARD_NAME_COMPARE(a, b) (strcmp((a)->wizard->callbacks.name, (b)) == 0)
    res = AST_VECTOR_REMOVE_CMP_ORDERED(&object_type->wizards, name, WIZARD_NAME_COMPARE, ao2_cleanup);
#undef WIZARD_NAME_COMPARE
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return res;
}

References ao2_cleanup, ao2_find, AST_VECTOR_REMOVE_CMP_ORDERED, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, name, OBJ_KEY, RAII_VAR, sorcery, type, ast_sorcery::types, and WIZARD_NAME_COMPARE.

__ast_sorcery_wizard_register()

int __ast_sorcery_wizard_register	(	const struct ast_sorcery_wizard *	interface,
		struct ast_module *	module
	)

Register a sorcery wizard.

Parameters

interface	Pointer to a wizard interface
module	Pointer to the module implementing the interface

Return values

0	success
-1	failure

Definition at line 496 of file sorcery.c.

{
    struct ast_sorcery_internal_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), sorcery_internal_wizard_destructor))) {
        goto done;
    }
 
    wizard->callbacks = *interface;
    wizard->callbacks.module = module;
 
    wizard->observers = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, NULL, NULL);
    if (!wizard->observers) {
        goto done;
    }
 
    ao2_link_flags(wizards, wizard, OBJ_NOLOCK);
    res = 0;
 
    ast_verb(5, "Sorcery registered wizard '%s'\n", interface->name);
 
    NOTIFY_GLOBAL_OBSERVERS(observers, wizard_registered,
        interface->name, interface);
 
done:
    ao2_cleanup(wizard);
    ao2_unlock(wizards);
 
    return res;
}

References ao2_alloc, AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_cleanup, ao2_container_alloc_list, ao2_find, ao2_link_flags, ao2_lock, ao2_unlock, ast_assert, ast_log, ast_strlen_zero(), ast_verb, ast_sorcery_internal_wizard::callbacks, done, LOG_WARNING, ast_sorcery_wizard::name, NOTIFY_GLOBAL_OBSERVERS, NULL, OBJ_KEY, OBJ_NOLOCK, ast_sorcery_internal_wizard::observers, observers, sorcery_internal_wizard_destructor(), and wizards.

Referenced by ast_bucket_init().

ast_sorcery_alloc()

void * ast_sorcery_alloc	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	id
	)

Allocate an object.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to allocate
id	Optional unique identifier, if none is provided one will be generated

Return values

non-NULL	success
NULL	failure

Definition at line 1808 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_details *details;
 
    if (!object_type || !object_type->type.item_alloc ||
        !(details = object_type->type.item_alloc(id))) {
        return NULL;
    }
 
    if (ast_strlen_zero(id)) {
        char uuid[AST_UUID_STR_LEN];
 
        ast_uuid_generate_str(uuid, sizeof(uuid));
        details->object->id = ast_strdup(uuid);
    } else {
        details->object->id = ast_strdup(id);
    }
    if (!details->object->id) {
        ao2_ref(details, -1);
        return NULL;
    }
 
    details->object->created = ast_tvnow();
    ast_copy_string(details->object->type, type, sizeof(details->object->type));
 
    if (aco_set_defaults(&object_type->type, id, details)) {
        ao2_ref(details, -1);
        return NULL;
    }
 
    return details;
}

References aco_set_defaults(), ao2_cleanup, ao2_find, ao2_ref, ast_copy_string(), ast_strdup, ast_strlen_zero(), ast_tvnow(), ast_uuid_generate_str(), AST_UUID_STR_LEN, ast_sorcery_object::created, ast_sorcery_object::id, NULL, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, type, ast_sorcery_object::type, ast_sorcery::types, and uuid().

Referenced by alloc_artificial_auth(), ast_ari_asterisk_update_object(), ast_bucket_alloc(), ast_bucket_file_alloc(), ast_mwi_mailbox_alloc(), ast_sip_initialize_system(), ast_sip_location_create_contact(), ast_sorcery_copy(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), create_artificial_endpoint(), create_effective_profile(), create_object(), default_profile_create(), global_loaded_observer(), load_module(), load_module(), mock_retrieve_id(), permanent_uri_handler(), sip_cli_print_global(), sip_cli_print_system(), sorcery_astdb_retrieve_fields_common(), sorcery_astdb_retrieve_id(), sorcery_astdb_retrieve_prefix(), sorcery_astdb_retrieve_regex(), sorcery_config_internal_load(), sorcery_memory_cache_thrash_update(), sorcery_realtime_retrieve_fields(), sorcery_realtime_retrieve_multiple(), sorcery_test_retrieve_id(), and subscription_persistence_create().

ast_sorcery_changeset_create()

int ast_sorcery_changeset_create	(	const struct ast_variable *	original,
		const struct ast_variable *	modified,
		struct ast_variable **	changes
	)

Create a changeset given two object sets.

Parameters

original	Original object set
modified	Modified object set
changes	Pointer to hold any changes between the object sets

Return values

0	success
-1	failure

Note

The returned ast_variable list must be destroyed using ast_variables_destroy

Definition at line 1727 of file sorcery.c.

{
    const struct ast_variable *field;
    int res = 0;
 
    *changes = NULL;
 
    /* Unless the ast_variable list changes when examined... it can't differ from itself */
    if (original == modified) {
        return 0;
    }
 
    for (field = modified; field; field = field->next) {
        const char *old_value = ast_variable_find_in_list(original, field->name);
 
        if (!old_value || strcmp(old_value, field->value)) {
            struct ast_variable *tmp;
 
            if (!(tmp = ast_variable_new(field->name, field->value, ""))) {
                res = -1;
                break;
            }
 
            tmp->next = *changes;
            *changes = tmp;
        }
    }
 
    /* If an error occurred do not return a partial changeset */
    if (res) {
        ast_variables_destroy(*changes);
        *changes = NULL;
    }
 
    return res;
}

References ast_variable_find_in_list(), ast_variable_new, ast_variables_destroy(), ast_variable::name, ast_variable::next, NULL, and ast_variable::value.

Referenced by ast_sorcery_diff(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), can_reuse_registration(), and sorcery_is_criteria_met().

ast_sorcery_copy()

void * ast_sorcery_copy	(	const struct ast_sorcery *	sorcery,
		const void *	object
	)

Create a copy of an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Existing object

Return values

non-NULL	success
NULL	failure

Definition at line 1842 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_details *copy = ast_sorcery_alloc(sorcery, details->object->type, details->object->id);
    RAII_VAR(struct ast_variable *, objectset, NULL, ast_variables_destroy);
    int res = 0;
 
    if (!copy) {
        return NULL;
    } else if (object_type->copy) {
        res = object_type->copy(object, copy);
    } else if ((objectset = ast_sorcery_objectset_create(sorcery, object))) {
        res = ast_sorcery_objectset_apply(sorcery, copy, objectset);
    } else {
        /* No native copy available and could not create an objectset, this copy has failed */
        res = -1;
    }
 
    if (res) {
        ao2_cleanup(copy);
        copy = NULL;
    }
 
    return copy;
}

References ao2_cleanup, ao2_find, ast_sorcery_alloc(), ast_sorcery_objectset_apply(), ast_sorcery_objectset_create, ast_variables_destroy(), copy(), ast_sorcery_object::id, NULL, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, ast_sorcery_object::type, and ast_sorcery::types.

Referenced by ast_ari_asterisk_update_object(), ast_bucket_clone(), ast_bucket_file_clone(), ast_mwi_mailbox_copy(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), and register_aor_core().

ast_sorcery_create()

int ast_sorcery_create	(	const struct ast_sorcery *	sorcery,
		void *	object
	)

Create and potentially persist an object using an available wizard.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object

Return values

0	success
-1	failure

Definition at line 2126 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_wizard *object_wizard = NULL;
    struct ast_sorcery_object_wizard *found_wizard;
    int i;
    struct sorcery_details sdetails = {
        .sorcery = sorcery,
        .obj = object,
    };
 
    if (!object_type) {
        return -1;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
        if (!found_wizard->caching
            && sorcery_wizard_create(found_wizard, &sdetails) == CMP_MATCH) {
            object_wizard = found_wizard;
        }
    }
 
    if (object_wizard) {
        for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
            found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
            if (found_wizard->caching) {
                sorcery_wizard_create(found_wizard, &sdetails);
            }
        }
 
        if (ao2_container_count(object_type->observers)) {
            struct sorcery_observer_invocation *invocation;
 
            invocation = sorcery_observer_invocation_alloc(object_type, object);
            if (invocation
                && ast_taskprocessor_push(object_type->serializer, sorcery_observers_notify_create,
                    invocation)) {
                ao2_cleanup(invocation);
            }
        }
    }
 
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return object_wizard ? 0 : -1;
}

References ao2_cleanup, ao2_container_count(), ao2_find, ast_taskprocessor_push(), AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_object_wizard::caching, CMP_MATCH, NULL, OBJ_KEY, ast_sorcery_object_details::object, sorcery_observer_invocation::object_type, RAII_VAR, ast_sorcery_object_type::serializer, sorcery_details::sorcery, sorcery, sorcery_observer_invocation_alloc(), sorcery_observers_notify_create(), sorcery_wizard_create(), ast_sorcery_object::type, ast_sorcery::types, and ast_sorcery_object_type::wizards.

Referenced by ast_ari_asterisk_update_object(), ast_bucket_create(), ast_bucket_file_create(), ast_mwi_mailbox_update(), ast_sip_location_create_contact(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), create_effective_profile(), default_profile_create(), load_module(), and subscription_persistence_create().

ast_sorcery_delete()

int ast_sorcery_delete	(	const struct ast_sorcery *	sorcery,
		void *	object
	)

Delete an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object

Return values

0	success
-1	failure

Definition at line 2302 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_wizard *object_wizard = NULL;
    struct ast_sorcery_object_wizard *found_wizard;
    int i;
    struct sorcery_details sdetails = {
        .sorcery = sorcery,
        .obj = object,
    };
 
    if (!object_type) {
        return -1;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
        if (!found_wizard->caching
            && sorcery_wizard_delete(found_wizard, &sdetails) == CMP_MATCH) {
            object_wizard = found_wizard;
        }
    }
 
    if (object_wizard) {
        for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
            found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
            if (found_wizard->caching) {
                sorcery_wizard_delete(found_wizard, &sdetails);
            }
        }
 
        if (ao2_container_count(object_type->observers)) {
            struct sorcery_observer_invocation *invocation;
 
            invocation = sorcery_observer_invocation_alloc(object_type, object);
            if (invocation
                && ast_taskprocessor_push(object_type->serializer, sorcery_observers_notify_delete,
                    invocation)) {
                ao2_cleanup(invocation);
            }
        }
    }
 
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return object_wizard ? 0 : -1;
}

References ao2_cleanup, ao2_container_count(), ao2_find, ast_taskprocessor_push(), AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_object_wizard::caching, CMP_MATCH, NULL, OBJ_KEY, ast_sorcery_object_details::object, sorcery_observer_invocation::object_type, RAII_VAR, ast_sorcery_object_type::serializer, sorcery_details::sorcery, sorcery, sorcery_observer_invocation_alloc(), sorcery_observers_notify_delete(), sorcery_wizard_delete(), ast_sorcery_object::type, ast_sorcery::types, and ast_sorcery_object_type::wizards.

Referenced by ast_ari_asterisk_delete_object(), ast_bucket_delete(), ast_bucket_file_delete(), ast_sip_location_delete_contact(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), bucket_http_wizard_retrieve_id(), mwi_mailbox_delete(), sub_persistence_recreate(), subscription_persistence_recreate(), subscription_persistence_remove(), and unload_module().

ast_sorcery_diff()

int ast_sorcery_diff	(	const struct ast_sorcery *	sorcery,
		const void *	original,
		const void *	modified,
		struct ast_variable **	changes
	)

Create a changeset of two objects.

Parameters

sorcery	Pointer to a sorcery structure
original	Original object
modified	Modified object
changes	Pointer which will be populated with changes if any exist

Return values

0	success
-1	failure

Note

The returned ast_variable list must be destroyed using ast_variables_destroy

While the objects must be of the same type they do not have to be the same object

Definition at line 1869 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, ast_sorcery_object_get_type(original), OBJ_KEY), ao2_cleanup);
 
    *changes = NULL;
 
    if (strcmp(ast_sorcery_object_get_type(original), ast_sorcery_object_get_type(modified))) {
        return -1;
    }
 
    if (original == modified) {
        return 0;
    } else if (!object_type->diff) {
        RAII_VAR(struct ast_variable *, objectset1, NULL, ast_variables_destroy);
        RAII_VAR(struct ast_variable *, objectset2, NULL, ast_variables_destroy);
 
        objectset1 = ast_sorcery_objectset_create(sorcery, original);
        objectset2 = ast_sorcery_objectset_create(sorcery, modified);
 
        return ast_sorcery_changeset_create(objectset1, objectset2, changes);
    } else {
        return object_type->diff(original, modified, changes);
    }
}

References ao2_cleanup, ao2_find, ast_sorcery_changeset_create(), ast_sorcery_object_get_type(), ast_sorcery_objectset_create, ast_variables_destroy(), NULL, OBJ_KEY, RAII_VAR, sorcery, and ast_sorcery::types.

Referenced by ari_conf_owc_detect_changes(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_websocket_client_get_field_diff(), and transport_apply().

ast_sorcery_force_reload()

void ast_sorcery_force_reload

(

const struct ast_sorcery *

sorcery

)

Inform any wizards to reload persistent objects, even if no changes determined.

Parameters

sorcery

Pointer to a sorcery structure

Since

13.32.0

16.9.0

17.3.0

Definition at line 1489 of file sorcery.c.

{
    struct sorcery_load_details details = {
        .sorcery = sorcery,
        .reload = 1,
        .force = 1,
    };
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
        sorcery->module_name, sorcery, 1);
 
    ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loaded,
        sorcery->module_name, sorcery, 1);
}

References ao2_callback, ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, OBJ_NODATA, ast_sorcery::observers, sorcery_load_details::sorcery, sorcery, sorcery_object_load(), and ast_sorcery::types.

ast_sorcery_force_reload_object()

void ast_sorcery_force_reload_object	(	const struct ast_sorcery *	sorcery,
		const char *	type
	)

Inform any wizards of a specific object type to reload persistent objects even if no changes determined.

Parameters

sorcery	Pointer to a sorcery structure
type	Name of the object type to reload

Since

13.32.0

16.9.0

17.3.0

Definition at line 1521 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct sorcery_load_details details = {
        .sorcery = sorcery,
        .reload = 1,
        .force = 1,
    };
 
    if (!object_type) {
        return;
    }
 
    sorcery_object_load(object_type, &details, 0);
}

References ao2_cleanup, ao2_find, OBJ_KEY, RAII_VAR, sorcery_load_details::sorcery, sorcery, sorcery_object_load(), type, and ast_sorcery::types.

Referenced by acl_change_stasis_cb(), acl_change_stasis_cb(), as_config_reload(), global_loaded(), profile_reload(), tn_config_reload(), vs_config_reload(), and ws_client_load().

ast_sorcery_generic_alloc()

void * ast_sorcery_generic_alloc	(	size_t	size,
		ao2_destructor_fn	destructor
	)

Allocate a generic sorcery capable object.

Parameters

size	Size of the object
destructor	Optional destructor function

Return values

non-NULL	success
NULL	failure

Note

The returned object does not support AO2 locking.

Definition at line 1792 of file sorcery.c.

{
    void *object = ao2_alloc_options(size + sizeof(struct ast_sorcery_object),
        sorcery_object_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK);
    struct ast_sorcery_object_details *details = object;
 
    if (!object) {
        return NULL;
    }
 
    details->object = object + size;
    details->object->destructor = destructor;
 
    return object;
}

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ast_sorcery_object::destructor, NULL, ast_sorcery_object_details::object, and sorcery_object_destructor().

Referenced by acl_alloc(), ast_sip_endpoint_alloc(), asterisk_publication_config_alloc(), attestation_alloc(), auth_alloc(), bucket_alloc(), bucket_file_alloc(), client_config_alloc(), contact_alloc(), domain_alias_alloc(), general_alloc(), geoloc_location_alloc(), geoloc_profile_alloc(), global_alloc(), ip_identify_alloc(), mapping_alloc(), mwi_sorcery_object_alloc(), outbound_websocket_alloc(), phoneprov_alloc(), profile_alloc(), publication_resource_alloc(), resource_list_alloc(), sip_nat_hook_alloc(), sip_outbound_publish_alloc(), sip_outbound_registration_alloc(), sip_transport_alloc(), subscription_persistence_alloc(), system_alloc(), test_data_alloc(), test_sorcery_object_alloc(), test_sorcery_object_alloc(), test_sorcery_object_alloc(), tn_alloc(), user_alloc(), verification_alloc(), and wc_alloc().

ast_sorcery_get_module()

const char * ast_sorcery_get_module

(

const struct ast_sorcery *

sorcery

)

Get the module that has opened the provided sorcery instance.

Parameters

sorcery

The sorcery instance

Returns

The module

Definition at line 2600 of file sorcery.c.

{
    return sorcery->module_name;
}

References ast_sorcery::module_name, and sorcery.

Referenced by sorcery_memory_cache_load().

ast_sorcery_get_object_type()

struct ast_sorcery_object_type * ast_sorcery_get_object_type	(	const struct ast_sorcery *	sorcery,
		const char *	type
	)

Get the sorcery object type given a type name.

Parameters

sorcery	The sorcery from which to retrieve the object type
type	The type name

Definition at line 2558 of file sorcery.c.

{
    return ao2_find(sorcery->types, type, OBJ_SEARCH_KEY);
}

References ao2_find, OBJ_SEARCH_KEY, sorcery, type, and ast_sorcery::types.

Referenced by ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), AST_TEST_DEFINE(), load_module(), sorcery_astdb_filter_objectset(), sorcery_is_explicit_name_met(), and sorcery_realtime_filter_objectset().

ast_sorcery_get_wizard_mapping()

int ast_sorcery_get_wizard_mapping	(	struct ast_sorcery *	sorcery,
		const char *	type,
		int	index,
		struct ast_sorcery_wizard **	wizard,
		void **	data
	)

By index, return a wizard mapped to an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
index	Index of the wizard
wizard	A pointer to receive the wizard pointer
data	A pointer to receive the data pointer

Return values

0	success
-1	failure

Warning

The wizard will have its reference count bumped so you must call ao2_cleanup when you're done with it.

Note

The wizard and data returned are valid only for this object type and only while the wizard is applied to the object type.

Since

13.4.0

Definition at line 854 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_wizard *owizard;
 
    if (!object_type) {
        return -1;
    }
 
    if (index < 0 || index >= AST_VECTOR_SIZE(&object_type->wizards)) {
        return -1;
    }
 
    owizard = AST_VECTOR_GET(&object_type->wizards, index);
 
    if (wizard != NULL) {
        *wizard = &(owizard->wizard->callbacks);
        ao2_bump(owizard->wizard);
    } else {
        return -1;
    }
 
    if (data != NULL) {
        *data = owizard->data;
    }
 
    return 0;
}

References ao2_bump, ao2_cleanup, ao2_find, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, NULL, OBJ_KEY, RAII_VAR, sorcery, type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by AST_TEST_DEFINE().

ast_sorcery_get_wizard_mapping_count()

int ast_sorcery_get_wizard_mapping_count	(	struct ast_sorcery *	sorcery,
		const char *	type
	)

Return the number of wizards mapped to an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object

Returns

Number of wizards or -1 for error

Since

13.4.0

Definition at line 842 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
 
    if (!object_type) {
        return -1;
    }
 
    return AST_VECTOR_SIZE(&object_type->wizards);
}

References ao2_cleanup, ao2_find, AST_VECTOR_SIZE, OBJ_KEY, RAII_VAR, sorcery, type, and ast_sorcery::types.

Referenced by AST_TEST_DEFINE(), and AST_TEST_DEFINE().

ast_sorcery_global_observer_add()

int ast_sorcery_global_observer_add

(

const struct ast_sorcery_global_observer *

callbacks

)

Add a global observer to sorcery.

Parameters

callbacks

Implementation of the global observer interface

Return values

0	success
-1	failure

Note

You must be ready to accept observer invocations before this function is called

Definition at line 562 of file sorcery.c.

{
    struct sorcery_global_observer *cb;
 
    cb = ao2_alloc(sizeof(*cb), NULL);
    if (!cb) {
        return -1;
    }
 
    cb->callbacks = callbacks;
    ao2_link(observers, cb);
    ao2_ref(cb, -1);
 
    return 0;
}

References ao2_alloc, ao2_link, ao2_ref, sorcery_global_observer::callbacks, callbacks, NULL, and observers.

Referenced by AST_TEST_DEFINE(), and load_module().

ast_sorcery_global_observer_remove()

void ast_sorcery_global_observer_remove

(

const struct ast_sorcery_global_observer *

callbacks

)

Remove a global observer from sorcery.

A global observer is notified... After a new wizard is registered. After a new sorcery instance is opened. Before an instance is destroyed. Before a wizard is unregistered.

Parameters

callbacks

Implementation of the global observer interface

Definition at line 578 of file sorcery.c.

{
    ao2_callback(observers, OBJ_NODATA | OBJ_UNLINK, sorcery_generic_observer_remove, (void *)callbacks);
}

References ao2_callback, callbacks, OBJ_NODATA, OBJ_UNLINK, observers, and sorcery_generic_observer_remove().

Referenced by AST_TEST_DEFINE(), and unload_module().

ast_sorcery_init()

int ast_sorcery_init

(

void

)

Initialize the sorcery API.

Return values

0	success
-1	failure

Definition at line 444 of file sorcery.c.

{
    struct ast_taskpool_options options = {
        .version = AST_TASKPOOL_OPTIONS_VERSION,
        .auto_increment = 1,
        .max_size = 0,
        .idle_timeout = 60,
        .initial_size = 1,
        .minimum_size = 1,
    };
    ast_assert(wizards == NULL);
 
    parse_general_options();
 
    taskpool = ast_taskpool_create("sorcery", &options);
    if (!taskpool) {
        return -1;
    }
 
    wizards = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, WIZARD_BUCKETS,
        ast_sorcery_internal_wizard_hash_fn, NULL, ast_sorcery_internal_wizard_cmp_fn);
    if (!wizards) {
        return -1;
    }
 
    observers = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, NULL, NULL);
    if (!observers) {
        return -1;
    }
 
    instances = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, INSTANCE_BUCKETS,
        sorcery_proxy_hash_fn, NULL, sorcery_proxy_cmp_fn);
    if (!instances) {
        return -1;
    }
 
    if (ast_cli_register_multiple(cli_commands, ARRAY_LEN(cli_commands))) {
        return -1;
    }
 
    ast_register_cleanup(sorcery_cleanup);
 
    return 0;
}

References AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_hash, ao2_container_alloc_list, ARRAY_LEN, ast_assert, ast_cli_register_multiple, ast_register_cleanup(), ast_taskpool_create(), AST_TASKPOOL_OPTIONS_VERSION, cli_commands, INSTANCE_BUCKETS, instances, NULL, observers, options, parse_general_options(), sorcery_cleanup(), taskpool, WIZARD_BUCKETS, and wizards.

Referenced by asterisk_daemon().

ast_sorcery_instance_observer_add()

int ast_sorcery_instance_observer_add	(	struct ast_sorcery *	sorcery,
		const struct ast_sorcery_instance_observer *	callbacks
	)

Add an observer to a sorcery instance.

Parameters

sorcery	Pointer to a sorcery structure
callbacks	Implementation of the instance observer interface

An instance observer is notified... Before an instance is loaded or reloaded. After an instance is loaded or reloaded. After a wizard is mapped to an object type. After an object type is registered. Before an object type is loaded or reloaded. After an object type is loaded or reloaded.

Return values

0	success
-1	failure

Note

You must be ready to accept observer invocations before this function is called

Definition at line 584 of file sorcery.c.

{
    struct sorcery_instance_observer *cb;
 
    cb = ao2_alloc(sizeof(*cb), NULL);
    if (!cb) {
        return -1;
    }
 
    cb->callbacks = callbacks;
    ao2_link(sorcery->observers, cb);
    ao2_ref(cb, -1);
 
    return 0;
}

References ao2_alloc, ao2_link, ao2_ref, sorcery_instance_observer::callbacks, callbacks, NULL, ast_sorcery::observers, and sorcery.

Referenced by ast_sip_initialize_sorcery_global(), AST_TEST_DEFINE(), instance_created_observer(), load_module(), load_module(), and pjsip_outbound_registration_metrics_init().

ast_sorcery_instance_observer_remove()

void ast_sorcery_instance_observer_remove	(	struct ast_sorcery *	sorcery,
		const struct ast_sorcery_instance_observer *	callbacks
	)

Remove an observer from a sorcery instance.

Parameters

sorcery	Pointer to a sorcery structure
callbacks	Implementation of the instance observer interface

Definition at line 601 of file sorcery.c.

{
    ao2_callback(sorcery->observers, OBJ_NODATA | OBJ_UNLINK, sorcery_generic_observer_remove, (void *)callbacks);
}

References ao2_callback, callbacks, OBJ_NODATA, OBJ_UNLINK, ast_sorcery::observers, sorcery, and sorcery_generic_observer_remove().

Referenced by ast_sip_destroy_sorcery_global(), AST_TEST_DEFINE(), instance_destroying_observer(), pjsip_outbound_registration_metrics_init(), pjsip_outbound_registration_metrics_unload_cb(), and unload_module().

ast_sorcery_is_object_field_registered()

int ast_sorcery_is_object_field_registered	(	const struct ast_sorcery_object_type *	object_type,
		const char *	field_name
	)

Determine if a particular object field has been registered with sorcery.

Parameters

object_type	The object type to check against
field_name	The name of the field to check

Return values

0	The field is not registered for this sorcery type
1	The field is registered for this sorcery type

Definition at line 2578 of file sorcery.c.

{
    struct ast_sorcery_object_field *object_field;
    int res = 1;
 
    ast_assert(object_type != NULL);
 
    object_field = ao2_find(object_type->fields, field_name, OBJ_SEARCH_KEY);
 
    if (!object_field) {
        object_field = ao2_callback(object_type->fields, 0, is_registered_cb, (char *)field_name);
    }
 
    if (!object_field) {
        res = 0;
    }
 
    ao2_cleanup(object_field);
    return res;
}

References ao2_callback, ao2_cleanup, ao2_find, ast_assert, ast_sorcery_object_type::fields, is_registered_cb(), NULL, and OBJ_SEARCH_KEY.

Referenced by AST_TEST_DEFINE(), sorcery_astdb_filter_objectset(), sorcery_is_explicit_name_met(), and sorcery_realtime_filter_objectset().

ast_sorcery_is_stale()

int ast_sorcery_is_stale	(	const struct ast_sorcery *	sorcery,
		void *	object
	)

Determine if a sorcery object is stale with respect to its backing datastore.

Since

14.0.0

This function will query the wizard(s) backing the particular sorcery object to determine if the in-memory object is now stale. No action is taken to update the object. Callers of this function may use one of the ast_sorcery_retrieve functions to obtain a new instance of the object if desired.

Return values

0	the object is not stale
1	the object is stale

Definition at line 2352 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_wizard *found_wizard;
    int res = 0;
    int i;
 
    if (!object_type) {
        return -1;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
 
        if (found_wizard->wizard->callbacks.is_stale) {
            res |= found_wizard->wizard->callbacks.is_stale(sorcery, found_wizard->data, object);
            ast_debug(5, "After calling wizard '%s', object '%s' is %s\n",
                found_wizard->wizard->callbacks.name,
                ast_sorcery_object_get_id(object),
                res ? "stale" : "not stale");
        }
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return res;
}

References ao2_cleanup, ao2_find, ast_debug, ast_sorcery_object_get_id(), AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, ast_sorcery_wizard::is_stale, ast_sorcery_wizard::name, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, ast_sorcery_object::type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by ast_bucket_file_is_stale(), ast_bucket_is_stale(), and AST_TEST_DEFINE().

ast_sorcery_load()

void ast_sorcery_load

(

const struct ast_sorcery *

sorcery

)

Inform any wizards to load persistent objects.

Parameters

sorcery

Pointer to a sorcery structure

Definition at line 1441 of file sorcery.c.

{
    struct sorcery_load_details details = {
        .sorcery = sorcery,
        .reload = 0,
    };
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
        sorcery->module_name, sorcery, 0);
 
    ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loaded,
        sorcery->module_name, sorcery, 0);
}

References ao2_callback, ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, OBJ_NODATA, ast_sorcery::observers, sorcery_load_details::sorcery, sorcery, sorcery_object_load(), and ast_sorcery::types.

Referenced by ast_res_pjsip_initialize_configuration(), ast_sip_initialize_system(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), geoloc_config_load(), load_module(), load_module(), and load_module().

ast_sorcery_load_object()

void ast_sorcery_load_object	(	const struct ast_sorcery *	sorcery,
		const char *	type
	)

Inform any wizards of a specific object type to load persistent objects.

Parameters

sorcery	Pointer to a sorcery structure
type	Name of the object type to load

Definition at line 1457 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct sorcery_load_details details = {
        .sorcery = sorcery,
        .reload = 0,
    };
 
    if (!object_type) {
        return;
    }
 
    sorcery_object_load(object_type, &details, 0);
}

References ao2_cleanup, ao2_find, OBJ_KEY, RAII_VAR, sorcery_load_details::sorcery, sorcery, sorcery_object_load(), type, and ast_sorcery::types.

Referenced by ari_conf_load(), as_config_load(), ast_sip_initialize_sorcery_global(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), load_module(), load_module(), load_module(), load_module(), profile_load(), reregister_all(), tn_config_load(), and vs_config_load().

ast_sorcery_lockable_alloc()

void * ast_sorcery_lockable_alloc	(	size_t	size,
		ao2_destructor_fn	destructor,
		void *	lockobj
	)

Allocate a generic sorcery capable object with locking.

Since

14.1.0

Sorcery objects may be replaced with new allocations during reloads. If locking is required on sorcery objects it must be shared between the old object and the new one. lockobj can be any AO2 object with locking enabled, but in most cases named locks should be used to provide stable locking.

Parameters

size	Size of the object
destructor	Optional destructor function
lockobj	An AO2 object that will provide locking.

Return values

non-NULL	success
NULL	failure

Definition at line 1776 of file sorcery.c.

{
    void *object = ao2_alloc_with_lockobj(size + sizeof(struct ast_sorcery_object),
        sorcery_object_destructor, lockobj, "");
    struct ast_sorcery_object_details *details = object;
 
    if (!object) {
        return NULL;
    }
 
    details->object = object + size;
    details->object->destructor = destructor;
 
    return object;
}

References ao2_alloc_with_lockobj, ast_sorcery_object::destructor, NULL, ast_sorcery_object_details::object, and sorcery_object_destructor().

Referenced by aor_alloc().

ast_sorcery_object_fields_register()

int ast_sorcery_object_fields_register	(	struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	regex,
		aco_option_handler	config_handler,
		sorcery_fields_handler	sorcery_handler
	)

Register a regex for multiple fields within an object.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
regex	A regular expression pattern for the fields
config_handler	A custom handler for translating the string representation of the fields
sorcery_handler	A custom handler for translating the native representation of the fields

Return values

0	success
-1	failure

Definition at line 1224 of file sorcery.c.

{
#define MAX_REGEX_ERROR_LEN 128
    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 rc;
 
    if (!object_type || !object_type->type.item_alloc || !config_handler
        || !(object_field = ao2_alloc(sizeof(*object_field), sorcery_object_field_destructor))) {
        return -1;
    }
 
    ast_copy_string(object_field->name, regex, sizeof(object_field->name));
    object_field->multiple_handler = sorcery_handler;
 
    if (!(object_field->name_regex = ast_calloc(1, sizeof(regex_t)))) {
        return -1;
    }
 
    if ((rc = regcomp(object_field->name_regex, regex, REG_EXTENDED | REG_NOSUB))) {
        char *regerr = ast_alloca(MAX_REGEX_ERROR_LEN);
        regerror(rc, object_field->name_regex, regerr, MAX_REGEX_ERROR_LEN);
        ast_log(LOG_ERROR, "Regular expression '%s' failed to compile: %s\n", regex, regerr);
        return -1;
    }
 
    ao2_link(object_type->fields, object_field);
    __aco_option_register(object_type->info, regex, ACO_REGEX, object_type->file->types, "", OPT_CUSTOM_T, config_handler, 0, 1, 0);
 
    return 0;
}

References __aco_option_register(), ACO_REGEX, ao2_alloc, ao2_cleanup, ao2_find, ao2_link, ast_alloca, ast_calloc, ast_copy_string(), ast_log, LOG_ERROR, MAX_REGEX_ERROR_LEN, NULL, OBJ_KEY, OPT_CUSTOM_T, RAII_VAR, regex(), sorcery, sorcery_object_field_destructor(), type, and ast_sorcery::types.

Referenced by __ast_sorcery_object_register(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), load_module(), and load_module().

ast_sorcery_object_get_created()

const struct timeval ast_sorcery_object_get_created

(

const void *

object

)

Get when the sorcery object was created.

Since

14.0.0

Parameters

object

Pointer to a sorcery object

Returns

The time when the object was created

Definition at line 2387 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    return details->object->created;
}

References ast_sorcery_object::created, and ast_sorcery_object_details::object.

ast_sorcery_object_get_extended()

const char * ast_sorcery_object_get_extended	(	const void *	object,
		const char *	name
	)

Get an extended field value from a sorcery object.

Parameters

object	Pointer to a sorcery object
name	Name of the extended field value

Return values

non-NULL	if found
NULL	if not found

Note

The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object

Definition at line 2399 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    struct ast_variable *field;
 
    for (field = details->object->extended; field; field = field->next) {
        if (!strcmp(field->name + 1, name)) {
            return field->value;
        }
    }
 
    return NULL;
}

References ast_sorcery_object::extended, name, ast_variable::name, ast_variable::next, NULL, ast_sorcery_object_details::object, and ast_variable::value.

Referenced by AST_TEST_DEFINE(), asterisk_start_devicestate_publishing(), asterisk_start_mwi_publishing(), delete_existing_cb(), and publisher_start().

ast_sorcery_object_get_id()

const char * ast_sorcery_object_get_id

(

const void *

object

)

Get the unique identifier of a sorcery object.

Parameters

object

Pointer to a sorcery object

Returns

unique identifier

Definition at line 2381 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    return details->object->id;
}

References ast_sorcery_object::id, and ast_sorcery_object_details::object.

Referenced by __print_debug_details(), aeap_cli_show(), aeap_tab_complete_name(), allocate_subscription_tree(), allow_and_or_replace_unsolicited(), ami_outbound_registration_task(), ami_show_registration_contact_statuses(), anonymous_identify(), aor_deleted_observer(), apply_acls(), ari_conf_get_owc_for_app(), ari_conf_owc_detect_changes(), ari_show_owc(), ari_show_user(), ast_ari_create_per_call_websocket(), ast_bucket_file_json(), ast_bucket_json(), ast_geoloc_eprofile_create_from_profile(), ast_mwi_mailbox_get_id(), ast_mwi_mailbox_update(), ast_res_pjsip_find_or_create_contact_status(), ast_res_pjsip_initialize_configuration(), ast_sip_create_dialog_uac(), ast_sip_create_subscription(), ast_sip_for_each_contact(), ast_sip_format_contact_ami(), ast_sip_get_contact_status(), ast_sip_get_device_state(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_transport(), ast_sip_location_create_contact(), ast_sip_location_retrieve_aor_contacts_nolock_filtered(), ast_sip_session_alloc(), ast_sip_session_create_outgoing(), ast_sip_session_get_name(), ast_sip_set_tpselector_from_transport(), ast_sip_subscription_destroy(), ast_sorcery_is_stale(), ast_sorcery_object_id_hash(), ast_sorcery_object_id_sort(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_websocket_client_connect(), ast_websocket_client_get_field_diff(), asterisk_publication_devicestate(), asterisk_publication_devicestate_refresh(), asterisk_publication_devicestate_state_change(), asterisk_publication_mailboxstate(), asterisk_publication_mwi_refresh(), asterisk_publication_mwi_state_change(), attestation_apply(), auth_apply(), auth_observer(), bucket_file_run_curl(), bucket_http_test_wizard_create(), bucket_http_test_wizard_delete(), bucket_http_test_wizard_update(), build_resource_tree(), can_reuse_registration(), cancel_and_unpublish(), challenge(), chan_pjsip_indicate(), chan_pjsip_new(), change_outgoing_sdp_stream_media_address(), change_outgoing_sdp_stream_media_address(), check_algorithm(), check_state(), cli_aor_get_id(), cli_aor_print_body(), cli_complete_endpoint(), cli_complete_registration(), cli_complete_uri(), cli_contact_print_body(), cli_endpoint_print_body(), cli_iterator(), cli_list_subscriptions_detail(), cli_print_body(), cli_print_body(), cli_print_body(), cli_print_body(), cli_show_subscriptions_detail(), client_config_apply(), codec_prefs_handler(), common_identify(), complete_sorcery_object(), config_object_cli_show(), config_object_tab_complete_name(), connected_line_method_handler(), contact_apply_handler(), contact_function_get_permanent(), create_dialog_uas(), create_effective_profile(), create_out_of_dialog_request(), create_outgoing_sdp_stream(), create_rtp(), create_unsolicited_mwi_subscriptions(), current_state_reusable(), destroy_subscription(), digest_check_auth(), digest_create_request_with_auth(), digest_lookup(), direct_media_glare_mitigation_handler(), direct_media_method_handler(), domain_alias_apply(), endpt_send_request(), eprofile_apply(), expire_objects_from_cache(), file_extension_from_url_path(), find_authorization(), find_internal_state_by_transport(), find_or_create_temporary_state(), find_registrar_aor(), format_ami_aor_handler(), format_ami_auth_handler(), format_ami_endpoint_identify(), format_ami_endpoint_transport(), from_user_handler(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_location_apply_handler(), geoloc_profile_apply_handler(), get_account_id(), get_creds_for_header(), get_curl_instance(), get_resource_display_name(), handle_export_primitives(), handle_incoming_request(), handle_incoming_request(), handle_outgoing_request(), handle_slash(), has_mwi_subscription(), header_identify_match_check(), ident_handler(), internal_state_alloc(), ip_identify_apply(), ip_identify_match_check(), ip_identify_match_handler(), line_identify(), load_engine(), load_module(), load_module(), log_caps(), mark_object_as_stale_in_cache(), matches_engine(), media_cache_handle_show_item(), media_cache_item_del_from_astdb(), media_cache_item_sync_to_astdb(), media_cache_prnt_summary(), memory_cache_stale_update_object(), msg_send(), mwi_contact_changed(), mwi_observe_delete(), mwi_post_event(), mwi_subscription_alloc(), mwi_validate_for_aor(), new_subscribe(), outbound_session_apply_config(), outbound_session_create(), outbound_websocket_apply(), outbound_websocket_dtor(), outbound_websocket_validate_cb(), outbound_websocket_websocket_client_id_from_str(), password_digest_handler(), permanent_uri_handler(), permanent_uri_sort_fn(), persistent_endpoint_find_or_create(), pjsip_aor_function_read(), profile_apply(), publish_request_initial(), publisher_start(), publisher_stop(), pubsub_on_rx_mwi_notify_request(), pubsub_on_rx_publish_request(), pubsub_on_rx_refresh(), pubsub_on_rx_subscribe_request(), qualify_contact_cb(), read_pjsip(), redirect_method_handler(), refer_client_on_evsub_state(), refer_incoming_ari_request(), refer_incoming_attended_request(), refer_incoming_blind_request(), refer_incoming_invite_request(), refer_incoming_refer_request(), refer_progress_alloc(), refer_send(), register_aor_core(), registrar_contact_delete(), registrar_on_rx_request(), registration_deleted_observer(), registration_state_cmp(), registration_state_hash(), remove_from_cache(), remove_subscription(), request_identify_match_check(), resource_list_apply_handler(), rfc3326_add_reason_header(), rx_data_to_ast_msg(), session_destructor(), session_inv_on_redirected(), session_inv_on_tsx_state_changed(), session_outgoing_nat_hook(), show_owc_cb(), show_users_cb(), sip_aor_to_ami(), sip_endpoint_apply_handler(), sip_options_aor_alloc(), sip_options_aor_observer_deleted_task(), sip_options_aor_observer_modified_task(), sip_options_apply_aor_configuration(), sip_options_contact_status_notify_task(), sip_options_endpoint_observer_deleted_task(), sip_options_endpoint_observer_modified_task(), sip_options_endpoint_state_compositor_find_or_alloc(), sip_options_endpoint_unlink_aor_feeders(), sip_options_qualify_contact(), sip_options_remove_contact_status(), sip_options_synchronize_aor(), sip_options_synchronize_endpoint(), sip_outbound_publish_apply(), sip_outbound_publish_callback(), sip_outbound_publish_state_alloc(), sip_outbound_publish_synchronize(), sip_outbound_publisher_alloc(), sip_outbound_publisher_init(), sip_outbound_publisher_set_uris(), sip_outbound_registration_apply(), sip_outbound_registration_regc_alloc(), sip_outbound_registration_state_alloc(), sip_sorcery_object_ami_set_type_name(), sip_subscription_send_request(), sip_subscription_to_ami(), sorcery_astdb_create(), sorcery_astdb_delete(), sorcery_astdb_update(), sorcery_config_fields_cmp(), sorcery_memory_cache_complete_object_name(), sorcery_memory_cache_create(), sorcery_memory_cache_delete(), sorcery_memory_cache_fields_cmp(), sorcery_memory_cache_print_object(), sorcery_memory_cache_retrieve_id(), sorcery_memory_cached_object_cmp(), sorcery_memory_cached_object_hash(), sorcery_memory_cmp(), sorcery_memory_create(), sorcery_memory_delete(), sorcery_memory_fields_cmp(), sorcery_memory_hash(), sorcery_memory_update(), sorcery_realtime_create(), sorcery_realtime_delete(), sorcery_realtime_update(), stale_item_update(), stir_shaken_handler(), subscription_established(), subscription_persistence_create(), subscription_persistence_remove(), subscription_tree_destructor(), t38_initialize_session(), tn_apply(), tn_get_etn(), tos_handler(), transport_apply(), transport_tls_file_handler(), transport_tos_handler(), uac_algorithms_handler(), uas_algorithms_handler(), unload_engine(), update_devstate(), user_apply(), user_dtor(), users_apply_handler(), validate_publish_config(), verification_apply(), verify(), wc_apply(), and wc_dtor().

ast_sorcery_object_get_type()

const char * ast_sorcery_object_get_type

(

const void *

object

)

Get the type of a sorcery object.

Parameters

object

Pointer to a sorcery object

Returns

type of object

Definition at line 2393 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    return details->object->type;
}

References ast_sorcery_object_details::object, and ast_sorcery_object::type.

Referenced by aeap_cli_show(), ast_sorcery_diff(), AST_TEST_DEFINE(), config_object_cli_show(), memory_cache_stale_check_object(), memory_cache_stale_update_object(), sip_aor_to_ami(), sip_sorcery_object_ami_set_type_name(), sorcery_astdb_create(), sorcery_astdb_delete(), sorcery_astdb_update(), and stale_item_update().

ast_sorcery_object_has_dynamic_contents()

unsigned int ast_sorcery_object_has_dynamic_contents

(

const void *

object

)

Get whether an object contains dynamic contents or not.

Parameters

object

Pointer to a sorcery object

Since

19

18.3.0

16.17.0

Definition at line 2441 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
 
    return details->object->has_dynamic_contents;
}

References ast_sorcery_object::has_dynamic_contents, and ast_sorcery_object_details::object.

Referenced by sorcery_config_internal_load().

ast_sorcery_object_id_compare()

int ast_sorcery_object_id_compare	(	void *	obj,
		void *	arg,
		int	flags
	)

ao2 object comparator based on sorcery id.

Definition at line 2528 of file sorcery.c.

{
    int cmp;
 
    cmp = ast_sorcery_object_id_sort(obj, arg, flags);
    if (cmp) {
        return 0;
    }
    return CMP_MATCH;
}

References ast_sorcery_object_id_sort(), and CMP_MATCH.

Referenced by ast_media_cache_init(), ast_sorcery_retrieve_by_fields(), ast_sorcery_retrieve_by_prefix(), ast_sorcery_retrieve_by_regex(), cli_aor_get_container(), cli_endpoint_get_container(), cli_get_container(), cli_get_container(), cli_get_container(), cli_get_container(), handle_registrations(), register_aor_core(), sip_options_aor_alloc(), and sorcery_config_internal_load().

ast_sorcery_object_id_hash()

int ast_sorcery_object_id_hash	(	const void *	obj,
		int	flags
	)

ao2 object hasher based on sorcery id.

Definition at line 2539 of file sorcery.c.

{
    const char *key;
 
    switch (flags & OBJ_SEARCH_MASK) {
    case OBJ_SEARCH_KEY:
        key = obj;
        break;
    case OBJ_SEARCH_OBJECT:
        key = ast_sorcery_object_get_id(obj);
        break;
    default:
        /* Hash can only work on something with a full key. */
        ast_assert(0);
        return 0;
    }
    return ast_str_hash(key);
}

References ast_assert, ast_sorcery_object_get_id(), ast_str_hash(), OBJ_SEARCH_KEY, OBJ_SEARCH_MASK, and OBJ_SEARCH_OBJECT.

Referenced by ast_media_cache_init(), sip_options_aor_alloc(), and sorcery_config_internal_load().

ast_sorcery_object_id_sort()

int ast_sorcery_object_id_sort	(	const void *	obj,
		const void *	arg,
		int	flags
	)

ao2 object sorter based on sorcery id.

Definition at line 2504 of file sorcery.c.

{
    const void *object_left = obj;
    const void *object_right = arg;
    const char *right_key = arg;
    int cmp;
 
    switch (flags & OBJ_SEARCH_MASK) {
    case OBJ_SEARCH_OBJECT:
        right_key = ast_sorcery_object_get_id(object_right);
        /* Fall through */
    case OBJ_SEARCH_KEY:
        cmp = strcmp(ast_sorcery_object_get_id(object_left), right_key);
        break;
    case OBJ_SEARCH_PARTIAL_KEY:
        cmp = strncmp(ast_sorcery_object_get_id(object_left), right_key, strlen(right_key));
        break;
    default:
        cmp = 0;
        break;
    }
    return cmp;
}

References ast_sorcery_object_get_id(), OBJ_SEARCH_KEY, OBJ_SEARCH_MASK, OBJ_SEARCH_OBJECT, and OBJ_SEARCH_PARTIAL_KEY.

Referenced by ast_sorcery_object_id_compare(), ast_sorcery_retrieve_by_fields(), ast_sorcery_retrieve_by_prefix(), ast_sorcery_retrieve_by_regex(), cli_aor_get_container(), cli_endpoint_get_container(), cli_get_container(), cli_get_container(), cli_get_container(), cli_get_container(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_config_show_profiles(), and sip_options_aor_alloc().

ast_sorcery_object_set_congestion_levels()

int ast_sorcery_object_set_congestion_levels	(	struct ast_sorcery *	sorcery,
		const char *	type,
		long	low_water,
		long	high_water
	)

Set the high and low alert water marks of the sorcery object type.

Since

13.10.0

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
low_water	New queue low water mark. (-1 to set as 90% of high_water)
high_water	New queue high water mark.

Return values

0	on success.
-1	on error (water marks not changed).

Definition at line 1178 of file sorcery.c.

{
    struct ast_sorcery_object_type *object_type;
    int res = -1;
 
    object_type = ao2_find(sorcery->types, type, OBJ_SEARCH_KEY);
    if (object_type) {
        res = ast_taskprocessor_alert_set_levels(object_type->serializer,
            low_water, high_water);
        ao2_ref(object_type, -1);
    }
    return res;
}

References ao2_find, ao2_ref, ast_taskprocessor_alert_set_levels(), OBJ_SEARCH_KEY, ast_sorcery_object_type::serializer, sorcery, type, and ast_sorcery::types.

Referenced by ast_sip_initialize_sorcery_location().

ast_sorcery_object_set_copy_handler()

void ast_sorcery_object_set_copy_handler	(	struct ast_sorcery *	sorcery,
		const char *	type,
		sorcery_copy_handler	copy
	)

Set the copy handler for an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
copy	Copy handler

Definition at line 1192 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
 
    if (!object_type) {
        return;
    }
 
    object_type->copy = copy;
}

References ao2_cleanup, ao2_find, copy(), OBJ_KEY, RAII_VAR, sorcery, type, and ast_sorcery::types.

Referenced by ast_bucket_init(), and AST_TEST_DEFINE().

ast_sorcery_object_set_diff_handler()

void ast_sorcery_object_set_diff_handler	(	struct ast_sorcery *	sorcery,
		const char *	type,
		sorcery_diff_handler	diff
	)

Set the diff handler for an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object
diff	Diff handler

Definition at line 1203 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
 
    if (!object_type) {
        return;
    }
 
    object_type->diff = diff;
}

References ao2_cleanup, ao2_find, ast_sorcery_object_type::diff, OBJ_KEY, RAII_VAR, sorcery, type, and ast_sorcery::types.

Referenced by AST_TEST_DEFINE().

ast_sorcery_object_set_extended()

int ast_sorcery_object_set_extended	(	const void *	object,
		const char *	name,
		const char *	value
	)

Set an extended field value on a sorcery object.

Parameters

object	Pointer to a sorcery object
name	Name of the extended field
value	Value of the extended field

Return values

0	success
-1	failure

Note

The field name MUST begin with '@' to indicate it is an extended field.

If the extended field already exists it will be overwritten with the new value.

Definition at line 2413 of file sorcery.c.

{
    RAII_VAR(struct ast_variable *, field, NULL, ast_variables_destroy);
    struct ast_variable *extended = ast_variable_new(name, value, ""), *previous = NULL;
    const struct ast_sorcery_object_details *details = object;
 
    if (!extended) {
        return -1;
    }
 
    for (field = details->object->extended; field; previous = field, field = field->next) {
        if (!strcmp(field->name, name)) {
            if (previous) {
                previous->next = field->next;
            } else {
                details->object->extended = field->next;
            }
            field->next = NULL;
            break;
        }
    }
 
    extended->next = details->object->extended;
    details->object->extended = extended;
 
    return 0;
}

References ast_variable_new, ast_variables_destroy(), ast_sorcery_object::extended, name, ast_variable::next, NULL, ast_sorcery_object_details::object, RAII_VAR, and value.

Referenced by AST_TEST_DEFINE(), and sorcery_extended_config_handler().

ast_sorcery_object_set_has_dynamic_contents()

void ast_sorcery_object_set_has_dynamic_contents

(

const void *

object

)

Set the dynamic contents flag on a sorcery object.

Parameters

object

Pointer to a sorcery object

Since

19

18.3.0

16.17.0

Definition at line 2448 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
 
    details->object->has_dynamic_contents = 1;
}

References ast_sorcery_object::has_dynamic_contents, and ast_sorcery_object_details::object.

Referenced by ip_identify_apply(), and transport_tls_file_handler().

ast_sorcery_object_unregister()

int ast_sorcery_object_unregister	(	struct ast_sorcery *	sorcery,
		const char *	type
	)

Unregister an object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object

Return values

0	success
-1	failure

Definition at line 1125 of file sorcery.c.

{
    struct ast_sorcery_object_type *object_type;
    int res = -1;
 
    ao2_wrlock(sorcery->types);
    object_type = ao2_find(sorcery->types, type, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (object_type && object_type->type.type == ACO_ITEM) {
        ao2_unlink_flags(sorcery->types, object_type, OBJ_NOLOCK);
        res = 0;
    }
    ao2_unlock(sorcery->types);
 
    /* XXX may need to add an instance unregister observer callback on success. */
 
    ao2_cleanup(object_type);
    return res;
}

References ACO_ITEM, ao2_cleanup, ao2_find, ao2_unlink_flags, ao2_unlock, ao2_wrlock, OBJ_NOLOCK, OBJ_SEARCH_KEY, sorcery, type, aco_type::type, ast_sorcery_object_type::type, and ast_sorcery::types.

Referenced by geoloc_config_unload(), unload_module(), unload_module(), and unload_module().

ast_sorcery_objectset_apply()

int ast_sorcery_objectset_apply	(	const struct ast_sorcery *	sorcery,
		void *	object,
		struct ast_variable *	objectset
	)

Apply an object set (KVP list) to an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object
objectset	Object set itself

Return values

0	success
-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.

Definition at line 1696 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    RAII_VAR(struct ast_variable *, transformed, NULL, ast_variables_destroy);
    struct ast_variable *field;
    int res = 0;
 
    if (!object_type) {
        return -1;
    }
 
    if (object_type->transform && (transformed = object_type->transform(objectset))) {
        field = transformed;
    } else {
        field = objectset;
    }
 
    for (; field; field = field->next) {
        if ((res = aco_process_var(&object_type->type, details->object->id, field, object))) {
            break;
        }
    }
 
    if (!res && object_type->apply) {
        res = object_type->apply(sorcery, object);
    }
 
    return res;
}

References aco_process_var(), ao2_cleanup, ao2_find, ast_variables_destroy(), ast_sorcery_object::id, ast_variable::next, NULL, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, ast_sorcery_object::type, and ast_sorcery::types.

Referenced by ast_ari_asterisk_update_object(), ast_sorcery_copy(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), create_effective_profile(), create_object(), sorcery_astdb_retrieve_fields_common(), sorcery_astdb_retrieve_id(), sorcery_astdb_retrieve_prefix(), sorcery_astdb_retrieve_regex(), sorcery_config_internal_load(), sorcery_realtime_retrieve_fields(), and sorcery_realtime_retrieve_multiple().

ast_sorcery_objectset_create2()

struct ast_variable * ast_sorcery_objectset_create2	(	const struct ast_sorcery *	sorcery,
		const void *	object,
		enum ast_sorcery_field_handler_flags	flags
	)

Create an object set (KVP list) for an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object
flags	Flags indicating which handler to use and in what order.

Return values

non-NULL	success
NULL	if error occurred

Note

The returned ast_variable list must be destroyed using ast_variables_destroy

Definition at line 1575 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ao2_iterator i;
    struct ast_sorcery_object_field *object_field;
    struct ast_variable *head = NULL;
    struct ast_variable *tail = NULL;
 
    if (!object_type) {
        return NULL;
    }
 
    i = ao2_iterator_init(object_type->fields, 0);
 
    for (; (object_field = ao2_iterator_next(&i)); ao2_ref(object_field, -1)) {
        struct ast_variable *tmp;
 
        switch (flags) {
        case AST_HANDLER_PREFER_LIST:
            if ((tmp = get_multiple_fields_as_var_list(object, object_field)) ||
                (tmp = get_single_field_as_var_list(object, object_field))) {
                break;
            }
            continue;
        case AST_HANDLER_PREFER_STRING:
            if ((tmp = get_single_field_as_var_list(object, object_field)) ||
                (tmp = get_multiple_fields_as_var_list(object, object_field))) {
                break;
            }
            continue;
        case AST_HANDLER_ONLY_LIST:
            if ((tmp = get_multiple_fields_as_var_list(object, object_field))) {
                break;
            }
            continue;
        case AST_HANDLER_ONLY_STRING:
            if ((tmp = get_single_field_as_var_list(object, object_field))) {
                break;
            }
            continue;
        default:
            continue;
        }
 
        tail = ast_variable_list_append_hint(&head, tail, tmp);
    }
 
    ao2_iterator_destroy(&i);
 
    return head;
}

References ao2_cleanup, ao2_find, ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, AST_HANDLER_ONLY_LIST, AST_HANDLER_ONLY_STRING, AST_HANDLER_PREFER_LIST, AST_HANDLER_PREFER_STRING, ast_variable_list_append_hint(), get_multiple_fields_as_var_list(), get_single_field_as_var_list(), NULL, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, ast_sorcery_object::type, and ast_sorcery::types.

Referenced by ast_sip_sorcery_object_to_ami(), config_object_cli_show(), and sip_aor_to_ami().

ast_sorcery_objectset_json_create()

struct ast_json * ast_sorcery_objectset_json_create	(	const struct ast_sorcery *	sorcery,
		const void *	object
	)

Create an object set in JSON format for an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object

Return values

non-NULL	success
NULL	if error occurred

Note

The returned ast_json object must be unreferenced using ast_json_unref

Definition at line 1629 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ao2_iterator i;
    struct ast_sorcery_object_field *object_field;
    struct ast_json *json = ast_json_object_create();
    int res = 0;
 
    if (!object_type || !json) {
        ast_json_unref(json);
        return NULL;
    }
 
    i = ao2_iterator_init(object_type->fields, 0);
 
    for (; !res && (object_field = ao2_iterator_next(&i)); ao2_ref(object_field, -1)) {
        if (object_field->multiple_handler) {
            struct ast_variable *tmp = NULL;
            struct ast_variable *field;
 
            if ((res = object_field->multiple_handler(object, &tmp))) {
                ast_variables_destroy(tmp);
                ao2_ref(object_field, -1);
                break;
            }
 
            for (field = tmp; field; field = field->next) {
                struct ast_json *value = ast_json_string_create(field->value);
 
                if (!value || ast_json_object_set(json, field->name, value)) {
                    res = -1;
                    break;
                }
            }
 
            ast_variables_destroy(tmp);
        } else if (object_field->handler) {
            char *buf = NULL;
            struct ast_json *value = NULL;
 
            if (object_field->handler(object, object_field->args, &buf)
                || !(value = ast_json_string_create(buf))
                || ast_json_object_set(json, object_field->name, value)) {
                ast_free(buf);
                ast_debug(5, "Skipping field '%s' for object type '%s'\n",
                    object_field->name, object_type->name);
                continue;
            }
 
            ast_free(buf);
        } else {
            continue;
        }
    }
 
    ao2_iterator_destroy(&i);
 
    /* If any error occurs we destroy the JSON object so a partial objectset is not returned */
    if (res) {
        ast_json_unref(json);
        json = NULL;
    }
 
    return json;
}

References ao2_cleanup, ao2_find, ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, ast_sorcery_object_field::args, ast_debug, ast_free, ast_json_object_create(), ast_json_object_set(), ast_json_string_create(), ast_json_unref(), ast_variables_destroy(), buf, ast_sorcery_object_field::handler, ast_sorcery_object_field::multiple_handler, ast_variable::name, ast_sorcery_object_field::name, ast_variable::next, NULL, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, ast_sorcery_object::type, ast_sorcery::types, ast_variable::value, and value.

Referenced by ast_bucket_file_json(), ast_bucket_json(), AST_TEST_DEFINE(), and sorcery_astdb_create().

ast_sorcery_observer_add()

int ast_sorcery_observer_add	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		const struct ast_sorcery_observer *	callbacks
	)

Add an observer to a specific object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object that should be observed
callbacks	Implementation of the observer interface

Return values

0	success
-1	failure

Note

You must be ready to accept observer invocations before this function is called

Definition at line 2455 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_type_observer *observer;
    int res;
 
    if (!object_type || !callbacks) {
        return -1;
    }
 
    if (!(observer = ao2_alloc(sizeof(*observer), NULL))) {
        return -1;
    }
 
    observer->callbacks = callbacks;
    res = 0;
    if (!ao2_link(object_type->observers, observer)) {
        res = -1;
    }
    ao2_ref(observer, -1);
 
    return res;
}

References ao2_alloc, ao2_cleanup, ao2_find, ao2_link, ao2_ref, callbacks, NULL, OBJ_KEY, observer, RAII_VAR, sorcery, type, and ast_sorcery::types.

Referenced by ari_conf_init(), ari_sorcery_observer_add(), ast_bucket_file_observer_add(), ast_bucket_observer_add(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_distributor(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_transport_management(), AST_TEST_DEFINE(), ast_websocket_client_observer_add(), load_module(), load_module(), load_module(), load_module(), load_module(), load_module(), load_module(), pjsip_outbound_registration_metrics_init(), and sip_options_init_task().

ast_sorcery_observer_remove()

void ast_sorcery_observer_remove	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		const struct ast_sorcery_observer *	callbacks
	)

Remove an observer from a specific object type.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object that should no longer be observed
callbacks	Implementation of the observer interface

Definition at line 2487 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, NULL, ao2_cleanup);
    struct ast_sorcery_observer *cbs = (struct ast_sorcery_observer *) callbacks;/* Remove const for traversal. */
 
    if (!sorcery) {
        return;
    }
    object_type = ao2_find(sorcery->types, type, OBJ_KEY);
    if (!object_type) {
        return;
    }
 
    ao2_callback(object_type->observers, OBJ_NODATA | OBJ_UNLINK,
        sorcery_observer_remove, cbs);
}

References ao2_callback, ao2_cleanup, ao2_find, callbacks, NULL, OBJ_KEY, OBJ_NODATA, OBJ_UNLINK, RAII_VAR, sorcery, sorcery_observer_remove(), type, and ast_sorcery::types.

Referenced by ari_sorcery_observer_remove(), ast_bucket_file_observer_remove(), ast_bucket_observer_remove(), ast_res_pjsip_cleanup_options_handling(), ast_sip_destroy_distributor(), ast_sip_destroy_sorcery_auth(), ast_sip_destroy_sorcery_location(), ast_sip_destroy_transport_management(), ast_websocket_client_observer_remove(), load_module(), pjsip_outbound_registration_metrics_init(), pjsip_outbound_registration_metrics_unload_cb(), unload_module(), unload_module(), unload_module(), unload_module(), unload_module(), unload_module(), and unload_module().

ast_sorcery_ref()

void ast_sorcery_ref

(

struct ast_sorcery *

sorcery

)

Increase the reference count of a sorcery structure.

Parameters

sorcery

Pointer to a sorcery structure

Definition at line 1537 of file sorcery.c.

{
    ao2_ref(sorcery, +1);
}

References ao2_ref, and sorcery.

Referenced by geoloc_get_sorcery().

ast_sorcery_reload()

void ast_sorcery_reload

(

const struct ast_sorcery *

sorcery

)

Inform any wizards to reload persistent objects.

Parameters

sorcery

Pointer to a sorcery structure

Definition at line 1472 of file sorcery.c.

{
    struct sorcery_load_details details = {
        .sorcery = sorcery,
        .reload = 1,
    };
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
        sorcery->module_name, sorcery, 1);
 
    ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
 
    NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loaded,
        sorcery->module_name, sorcery, 1);
 
}

References ao2_callback, ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, OBJ_NODATA, ast_sorcery::observers, sorcery_load_details::sorcery, sorcery, sorcery_object_load(), and ast_sorcery::types.

Referenced by ast_res_pjsip_reload_configuration(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_websocket_client_reload(), geoloc_config_reload(), load_module(), reload_module(), reload_module(), reload_module(), and reload_module().

ast_sorcery_reload_object()

void ast_sorcery_reload_object	(	const struct ast_sorcery *	sorcery,
		const char *	type
	)

Inform any wizards of a specific object type to reload persistent objects.

Parameters

sorcery	Pointer to a sorcery structure
type	Name of the object type to reload

Definition at line 1506 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct sorcery_load_details details = {
        .sorcery = sorcery,
        .reload = 1,
    };
 
    if (!object_type) {
        return;
    }
 
    sorcery_object_load(object_type, &details, 0);
}

References ao2_cleanup, ao2_find, OBJ_KEY, RAII_VAR, sorcery_load_details::sorcery, sorcery, sorcery_object_load(), type, and ast_sorcery::types.

Referenced by apply_list_configuration(), ari_conf_load(), ast_sip_initialize_distributor(), ast_sip_initialize_transport_management(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), load_module(), load_module(), load_module(), load_module(), load_module(), load_module(), load_users(), reload_module(), reload_module(), reload_module(), and reload_module().

ast_sorcery_retrieve_by_fields()

void * ast_sorcery_retrieve_by_fields	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		unsigned int	flags,
		struct ast_variable *	fields
	)

Retrieve an object or multiple objects using specific fields.

Since

13.9.0

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to retrieve
flags	Flags to control behavior
fields	Optional object fields and values to match against

Return values

non-NULL	if found
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.

If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects of the given type.

The fields parameter can contain realtime-style expressions in variable->name. All operators defined for ast_strings_match can be used except for regex as there's no common support for regex in the realtime backends at this time. If multiple variables are in the fields list, all must match for an object to be returned. See ast_strings_match for more information.

Example:

The following code can be significantly faster when a realtime backend is in use because the expression "qualify_frequency > 0" is passed to the database to limit the number of rows returned.

struct ast_variable *var = ast_variable_new("qualify_frequency >", "0", ""); struct ao2_container *aors;

if (!var) { return; }

aors = ast_sorcery_retrieve_by_fields(ast_sip_get_sorcery(), "aor", AST_RETRIEVE_FLAG_MULTIPLE, var);

Definition at line 1961 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    void *object = NULL;
    int i;
    unsigned int cached = 0;
 
    if (!object_type) {
        return NULL;
    }
 
    /* If returning multiple objects create a container to store them in */
    if ((flags & AST_RETRIEVE_FLAG_MULTIPLE)) {
        object = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT, ast_sorcery_object_id_sort, ast_sorcery_object_id_compare);
        if (!object) {
            return NULL;
        }
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        struct ast_sorcery_object_wizard *wizard =
            AST_VECTOR_GET(&object_type->wizards, i);
 
        if ((flags & AST_RETRIEVE_FLAG_MULTIPLE)) {
            if (wizard->wizard->callbacks.retrieve_multiple) {
                wizard->wizard->callbacks.retrieve_multiple(sorcery, wizard->data, object_type->name, object, fields);
            }
        } else if (fields && wizard->wizard->callbacks.retrieve_fields) {
            if (wizard->wizard->callbacks.retrieve_fields) {
                object = wizard->wizard->callbacks.retrieve_fields(sorcery, wizard->data, object_type->name, fields);
            }
        }
 
        if (((flags & AST_RETRIEVE_FLAG_MULTIPLE) && (!ao2_container_count(object) || !wizard->caching)) || !object) {
            continue;
        }
 
        cached = wizard->caching;
 
        break;
    }
 
    /* If we are returning a single object and it came from a non-cache source create it in any caches */
    if (!(flags & AST_RETRIEVE_FLAG_MULTIPLE) && !cached && object) {
        struct sorcery_details sdetails = {
            .sorcery = sorcery,
            .obj = object,
        };
 
        AST_VECTOR_CALLBACK(&object_type->wizards, sorcery_cache_create, NULL, &sdetails, 0);
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return object;
}

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_cleanup, ao2_container_alloc_list, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT, ao2_container_count(), ao2_find, AST_RETRIEVE_FLAG_MULTIPLE, ast_sorcery_object_id_compare(), ast_sorcery_object_id_sort(), AST_VECTOR_CALLBACK, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, NULL, OBJ_KEY, RAII_VAR, ast_sorcery_wizard::retrieve_fields, ast_sorcery_wizard::retrieve_multiple, sorcery_details::sorcery, sorcery, sorcery_cache_create(), type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by acl_on_rx_msg(), ami_show_registration_contact_statuses(), ami_show_resource_lists(), ari_conf_get_owcs(), ari_conf_get_users(), ast_aeap_client_configs_get(), ast_mwi_mailbox_get_all(), ast_sip_get_endpoints(), ast_sip_initialize_sorcery_transport(), ast_sip_initialize_system(), ast_sip_location_prune_boot_contacts(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_websocket_client_retrieve_all(), asterisk_publication_send_refresh(), auth_observer(), check_expiration_thread(), cli_complete_registration(), cli_contact_get_container(), cli_get_aors(), cli_get_auths(), cli_iterator(), common_identify(), create_mwi_subscriptions(), eprofile_get_all(), format_ami_endpoint_identify(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_config_show_profiles(), get_all_contacts(), get_publishes_and_update_state(), get_registrations(), get_system_cfg(), get_tn_all(), global_loaded_observer(), handle_export_primitives(), load_all_endpoints(), load_users(), memory_cache_populate(), process_nat(), profile_get_all(), sip_options_aor_observer_modified_task(), sip_options_synchronize_task(), stale_cache_update(), and subscription_persistence_load().

ast_sorcery_retrieve_by_id()

void * ast_sorcery_retrieve_by_id	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	id
	)

Retrieve an object using its unique identifier.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to retrieve
id	Unique object identifier

Return values

non-NULL	if found
NULL	if not found

Definition at line 1917 of file sorcery.c.

{
    struct ast_sorcery_object_type *object_type;
    void *object = NULL;
    int i;
    unsigned int cached = 0;
 
    if (ast_strlen_zero(id)) {
        return NULL;
    }
 
    object_type = ao2_find(sorcery->types, type, OBJ_SEARCH_KEY);
    if (!object_type) {
        return NULL;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        struct ast_sorcery_object_wizard *wizard =
            AST_VECTOR_GET(&object_type->wizards, i);
 
        if (wizard->wizard->callbacks.retrieve_id &&
            !(object = wizard->wizard->callbacks.retrieve_id(sorcery, wizard->data, object_type->name, id))) {
            continue;
        }
 
        cached = wizard->caching;
        break;
    }
 
    if (!cached && object) {
        struct sorcery_details sdetails = {
            .sorcery = sorcery,
            .obj = object,
        };
 
        AST_VECTOR_CALLBACK(&object_type->wizards, sorcery_cache_create, NULL, &sdetails, 0);
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    ao2_ref(object_type, -1);
    return object;
}

References ao2_find, ao2_ref, ast_strlen_zero(), AST_VECTOR_CALLBACK, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_type::name, NULL, OBJ_SEARCH_KEY, ast_sorcery_wizard::retrieve_id, sorcery_details::sorcery, sorcery, sorcery_cache_create(), type, ast_sorcery::types, ast_sorcery_object_wizard::wizard, and ast_sorcery_object_type::wizards.

Referenced by add_security_headers(), ami_show_endpoint(), ami_sip_qualify(), anonymous_identify(), ari_conf_get_general(), ari_conf_get_owc(), ari_conf_get_user(), ari_conf_validate_user(), as_get_cfg(), as_is_config_loaded(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), ast_bucket_file_retrieve(), ast_bucket_retrieve(), ast_geoloc_datastore_create_from_profile_name(), ast_geoloc_eprofile_refresh_location(), ast_geoloc_get_location(), ast_geoloc_get_profile(), ast_mwi_mailbox_get(), ast_mwi_mailbox_update(), ast_sip_default_outbound_endpoint(), ast_sip_for_each_auth(), ast_sip_location_retrieve_aor(), ast_sip_location_retrieve_contact(), ast_sip_retrieve_auths(), ast_sip_retrieve_auths_vector(), ast_sip_rewrite_uri_to_local(), ast_sip_set_tpselector_from_transport_name(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), ast_websocket_client_retrieve_by_id(), asterisk_publication_devicestate_state_change(), asterisk_publication_mwi_state_change(), asterisk_publication_new(), chan_pjsip_devicestate(), check_state(), cli_aor_retrieve_by_id(), cli_endpoint_retrieve_by_id(), cli_iterate(), cli_qualify(), cli_reload_qualify_aor(), cli_reload_qualify_endpoint(), cli_retrieve_by_id(), cli_retrieve_by_id(), cli_retrieve_by_id(), cli_retrieve_by_id(), cli_show_qualify_endpoint(), client_config_get(), common_identify(), contact_observer_updated(), create_effective_profile(), create_rtp(), eprofile_get_cfg(), find_aor2(), find_aor_name(), find_endpoint(), format_ami_endpoint_transport(), geoloc_profile_apply_handler(), get_log_mappings(), get_write_timeout(), handle_atsign(), handle_registration_response(), handle_single_token(), handle_slash(), line_identify(), load_endpoint(), mwi_contact_changed(), mwi_contact_deleted(), mwi_subscription_shutdown(), on_rx_process_symmetric_transport(), outbound_websocket_validate_cb(), pjsip_acf_dial_contacts_read(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), process_nat(), profile_get_cfg(), publish_request_initial(), push_notify(), request(), retrieve_resource_list(), send_unsolicited_mwi_notify(), sip_options_contact_add_management_task(), sip_options_qualify_contact(), sorcery_function_read(), sorcery_memory_cache_thrash_retrieve(), stale_item_update(), sub_persistence_recreate(), t38_initialize_session(), tn_get_cfg(), tn_get_etn(), transfer(), vs_get_cfg(), and vs_is_config_loaded().

ast_sorcery_retrieve_by_module_name()

struct ast_sorcery * ast_sorcery_retrieve_by_module_name

(

const char *

module_name

)

Retrieves an existing sorcery instance by module name.

Parameters

module_name

The module name

Return values

non-NULL	success
NULL	if no instance was found

Note

The returned instance has its reference count incremented. The caller must decrement the count when they're finished with it.

Retrieves an existing sorcery instance by module name.

Definition at line 736 of file sorcery.c.

{
    return ao2_weakproxy_find(instances, module_name, OBJ_SEARCH_KEY, "");
}

References ao2_weakproxy_find, instances, ast_sorcery::module_name, and OBJ_SEARCH_KEY.

Referenced by ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), AST_TEST_DEFINE(), and sorcery_function_read().

ast_sorcery_retrieve_by_prefix()

struct ao2_container * ast_sorcery_retrieve_by_prefix	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	prefix,
		const size_t	prefix_len
	)

Retrieve multiple objects whose id begins with the specified prefix.

Since

13.19.0

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to retrieve
prefix	Object id prefix
prefix_len	The length of prefix in bytes

Return values

non-NULL	if error occurs
NULL	success

Note

The prefix is matched in a case sensitive manner.

Definition at line 2053 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct ao2_container *objects;
    int i;
 
    if (!object_type) {
        return NULL;
    }
 
    objects = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT, ast_sorcery_object_id_sort, ast_sorcery_object_id_compare);
    if (!objects) {
        return NULL;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        struct ast_sorcery_object_wizard *wizard =
            AST_VECTOR_GET(&object_type->wizards, i);
 
        if (!wizard->wizard->callbacks.retrieve_prefix) {
            continue;
        }
 
        wizard->wizard->callbacks.retrieve_prefix(sorcery, wizard->data, object_type->name, objects, prefix, prefix_len);
 
        if (wizard->caching && ao2_container_count(objects)) {
            break;
        }
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return objects;
}

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_cleanup, ao2_container_alloc_list, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT, ao2_container_count(), ao2_find, ast_sorcery_object_id_compare(), ast_sorcery_object_id_sort(), AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, NULL, OBJ_KEY, prefix, RAII_VAR, ast_sorcery_wizard::retrieve_prefix, sorcery, type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by aor_deleted_observer(), ast_sip_location_retrieve_aor_contacts_nolock_filtered(), cli_complete_endpoint(), and sip_options_apply_aor_configuration().

ast_sorcery_retrieve_by_regex()

struct ao2_container * ast_sorcery_retrieve_by_regex	(	const struct ast_sorcery *	sorcery,
		const char *	type,
		const char *	regex
	)

Retrieve multiple objects using a regular expression on their id.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to retrieve
regex	Regular expression

Return values

non-NULL	if error occurs
NULL	success

Note

The provided regex is treated as extended case sensitive.

Definition at line 2018 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    struct ao2_container *objects;
    int i;
 
    if (!object_type) {
        return NULL;
    }
 
    objects = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT, ast_sorcery_object_id_sort, ast_sorcery_object_id_compare);
    if (!objects) {
        return NULL;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        struct ast_sorcery_object_wizard *wizard =
            AST_VECTOR_GET(&object_type->wizards, i);
 
        if (!wizard->wizard->callbacks.retrieve_regex) {
            continue;
        }
 
        wizard->wizard->callbacks.retrieve_regex(sorcery, wizard->data, object_type->name, objects, regex);
 
        if (wizard->caching && ao2_container_count(objects)) {
            break;
        }
    }
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return objects;
}

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_cleanup, ao2_container_alloc_list, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT, ao2_container_count(), ao2_find, ast_sorcery_object_id_compare(), ast_sorcery_object_id_sort(), AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, NULL, OBJ_KEY, RAII_VAR, regex(), ast_sorcery_wizard::retrieve_regex, sorcery, type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by ast_mwi_mailbox_get_by_regex(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), cli_aor_get_container(), cli_contact_get_container(), cli_endpoint_get_container(), cli_get_container(), cli_get_container(), cli_get_container(), cli_get_container(), geoloc_config_list_locations(), geoloc_config_list_profiles(), and geoloc_config_show_profiles().

ast_sorcery_update()

int ast_sorcery_update	(	const struct ast_sorcery *	sorcery,
		void *	object
	)

Update an object.

Parameters

sorcery	Pointer to a sorcery structure
object	Pointer to a sorcery object

Return values

0	success
-1	failure

Definition at line 2214 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = object;
    RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
    struct ast_sorcery_object_wizard *object_wizard = NULL;
    struct ast_sorcery_object_wizard *found_wizard;
    int i;
    struct sorcery_details sdetails = {
        .sorcery = sorcery,
        .obj = object,
    };
 
    if (!object_type) {
        return -1;
    }
 
    AST_VECTOR_RW_RDLOCK(&object_type->wizards);
    for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
        found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
        if (!found_wizard->caching
            && sorcery_wizard_update(found_wizard, &sdetails) == CMP_MATCH) {
            object_wizard = found_wizard;
        }
    }
 
    if (object_wizard) {
        for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
            found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
            if (found_wizard->caching) {
                sorcery_wizard_update(found_wizard, &sdetails);
            }
        }
 
        if (ao2_container_count(object_type->observers)) {
            struct sorcery_observer_invocation *invocation;
 
            invocation = sorcery_observer_invocation_alloc(object_type, object);
            if (invocation
                && ast_taskprocessor_push(object_type->serializer, sorcery_observers_notify_update,
                    invocation)) {
                ao2_cleanup(invocation);
            }
        }
    }
 
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
 
    return object_wizard ? 0 : -1;
}

References ao2_cleanup, ao2_container_count(), ao2_find, ast_taskprocessor_push(), AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_object_wizard::caching, CMP_MATCH, NULL, OBJ_KEY, ast_sorcery_object_details::object, sorcery_observer_invocation::object_type, RAII_VAR, ast_sorcery_object_type::serializer, sorcery_details::sorcery, sorcery, sorcery_observer_invocation_alloc(), sorcery_observers_notify_update(), sorcery_wizard_update(), ast_sorcery_object::type, ast_sorcery::types, and ast_sorcery_object_type::wizards.

Referenced by ast_ari_asterisk_update_object(), ast_bucket_file_update(), ast_mwi_mailbox_update(), ast_sip_location_update_contact(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), create_effective_profile(), sorcery_memory_cache_thrash_update(), and subscription_persistence_update().

ast_sorcery_wizard_observer_add()

int ast_sorcery_wizard_observer_add	(	struct ast_sorcery_wizard *	wizard,
		const struct ast_sorcery_wizard_observer *	callbacks
	)

Add an observer to a sorcery wizard.

Parameters

wizard	Pointer to a previously registered wizard structure
callbacks	Implementation of the wizard observer interface

A wizard observer is notified... Before a wizard is loaded or reloaded. After a wizard is loaded or reloaded.

Return values

0	success
-1	failure

Note

You must be ready to accept observer invocations before this function is called

Definition at line 607 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_internal_wizard *, wizard,
        interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL,
            ao2_cleanup);
 
    if (wizard) {
        struct sorcery_wizard_observer *cb;
 
        cb = ao2_alloc(sizeof(*cb), NULL);
        if (!cb) {
            return -1;
        }
 
        cb->callbacks = callbacks;
        ao2_link(wizard->observers, cb);
        ao2_ref(cb, -1);
 
        return 0;
    }
 
    return -1;
}

References ao2_alloc, ao2_cleanup, ao2_find, ao2_link, ao2_ref, sorcery_wizard_observer::callbacks, callbacks, ast_sorcery_wizard::name, NULL, OBJ_SEARCH_KEY, RAII_VAR, and wizards.

Referenced by AST_TEST_DEFINE().

ast_sorcery_wizard_observer_remove()

void ast_sorcery_wizard_observer_remove	(	struct ast_sorcery_wizard *	interface,
		const struct ast_sorcery_wizard_observer *	callbacks
	)

Remove an observer from a sorcery wizard.

Parameters

interface	Pointer to a sorcery structure
callbacks	Implementation of the wizard observer interface

Definition at line 632 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_internal_wizard *, wizard,
        interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL,
            ao2_cleanup);
 
    if (wizard) {
        ao2_callback(wizard->observers, OBJ_NODATA | OBJ_UNLINK, sorcery_generic_observer_remove, (void *)callbacks);
    }
}

References ao2_callback, ao2_cleanup, ao2_find, callbacks, ast_sorcery_wizard::name, NULL, OBJ_NODATA, OBJ_SEARCH_KEY, OBJ_UNLINK, RAII_VAR, sorcery_generic_observer_remove(), and wizards.

Referenced by AST_TEST_DEFINE().

ast_sorcery_wizard_unregister()

int ast_sorcery_wizard_unregister

(

const struct ast_sorcery_wizard *

interface

)

Unregister a sorcery wizard.

Parameters

interface

Pointer to the wizard interface

Return values

0	success
-1	failure

Definition at line 538 of file sorcery.c.

{
    struct ast_sorcery_internal_wizard *wizard =
        interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL;
 
    if (wizard) {
        NOTIFY_GLOBAL_OBSERVERS(observers, wizard_unregistering, wizard->callbacks.name, &wizard->callbacks);
        ao2_unlink(wizards, wizard);
        ao2_ref(wizard, -1);
        ast_verb(5, "Sorcery unregistered wizard '%s'\n", interface->name);
        return 0;
    } else {
        return -1;
    }
}

References ao2_find, ao2_ref, ao2_unlink, ast_verb, ast_sorcery_internal_wizard::callbacks, if(), name, ast_sorcery_wizard::name, NOTIFY_GLOBAL_OBSERVERS, NULL, OBJ_SEARCH_KEY, observers, and wizards.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), bucket_cleanup(), sorcery_memory_cache_thrash_destroy(), unload_module(), unload_module(), unload_module(), unload_module(), and unload_module().

Variable Documentation

ast_sorcery_update_or_create_on_update_miss

int ast_sorcery_update_or_create_on_update_miss

extern

Global control for optional update->create fallback in backends.

When non-zero, writable Sorcery backends may attempt to call create() if update() indicates the object is missing (e.g., 0 rows affected or NOT_FOUND). This helps re-populate backends that temporarily missed an insert.

Default is 0 (off) to maintain legacy behavior.

Configured via sorcery.conf: [general] update_or_create_on_update_miss = yes|no

NOTE: Backends MUST gate their fallback logic on this variable.

Definition at line 288 of file sorcery.c.

Referenced by AST_TEST_DEFINE(), cli_show_settings(), parse_general_options(), sorcery_astdb_update(), sorcery_memory_update(), and sorcery_realtime_update().