sorcery.c File Reference

Sorcery Data Access Layer API. More...

#include "asterisk.h"
#include "asterisk/logger.h"
#include "asterisk/sorcery.h"
#include "asterisk/astobj2.h"
#include "asterisk/format.h"
#include "asterisk/format_cap.h"
#include "asterisk/strings.h"
#include "asterisk/config_options.h"
#include "asterisk/netsock2.h"
#include "asterisk/module.h"
#include "asterisk/taskprocessor.h"
#include "asterisk/taskpool.h"
#include "asterisk/json.h"
#include "asterisk/vector.h"
#include "asterisk/cli.h"

Include dependency graph for sorcery.c:

Go to the source code of this file.

Data Structures
struct	ast_sorcery
	Full structure for sorcery. More...
struct	ast_sorcery_internal_wizard
	Structure for an internal wizard instance. More...
struct	ast_sorcery_object
	Structure for internal sorcery object information. More...
struct	ast_sorcery_object_field
	Structure for registered object field. More...
struct	ast_sorcery_object_type
	Structure for registered object type. More...
struct	ast_sorcery_object_type_observer
	Structure for registered object type observer. More...
struct	ast_sorcery_object_wizard
	Structure for a wizard instance which operates on objects. More...
struct	sorcery_details
	Structure used when calling create, update, or delete. More...
struct	sorcery_global_observer
	A global observer wrapper. More...
struct	sorcery_instance_observer
	An instance observer wrapper. More...
struct	sorcery_load_details
	Structure for passing load/reload details. More...
struct	sorcery_observer_invocation
	Structure used for observer invocations. More...
struct	sorcery_proxy
	Proxy object for sorcery. More...
struct	sorcery_wizard_observer
	A wizard observer wrapper. More...

Macros
#define	INITIAL_WIZARD_VECTOR_SIZE   5
#define	INSTANCE_BUCKETS   17
	Number of buckets for instances (should be prime for performance reasons)
#define	MAX_REGEX_ERROR_LEN   128
#define	NOTIFY_GENERIC_OBSERVERS(container, type, callback, ...)
#define	NOTIFY_GLOBAL_OBSERVERS(container, callback, ...)    NOTIFY_GENERIC_OBSERVERS(container, sorcery_global_observer, callback, __VA_ARGS__)
#define	NOTIFY_INSTANCE_OBSERVERS(container, callback, ...)    NOTIFY_GENERIC_OBSERVERS(container, sorcery_instance_observer, callback, __VA_ARGS__)
#define	NOTIFY_WIZARD_OBSERVERS(container, callback, ...)    NOTIFY_GENERIC_OBSERVERS(container, sorcery_wizard_observer, callback, __VA_ARGS__)
#define	OBJECT_FIELD_BUCKETS   29
	Number of buckets for object fields (should be prime for performance reasons)
#define	TYPE_BUCKETS   53
	Number of buckets for types (should be prime for performance reasons)
#define	WIZARD_BUCKETS   7
	Number of buckets for wizards (should be prime for performance reasons)
#define	WIZARD_COMPARE(a, b)   ((a)->wizard == (b))
#define	WIZARD_NAME_COMPARE(a, b)   (strcmp((a)->wizard->callbacks.name, (b)) == 0)

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)
	Internal function which creates an object type and adds a 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)
	Internal function which creates an object type and inserts a wizard mapping.
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_name, 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)
	Internal function removes a 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)
	Search function for sorcery instances.
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 *interface, 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.
	AST_VECTOR_RW (ast_sorcery_object_wizards, struct ast_sorcery_object_wizard *)
	Interface for a sorcery object type wizards.
static int	bool_handler_fn (const void *obj, const intptr_t *args, char **buf)
static int	chararray_handler_fn (const void *obj, const intptr_t *args, char **buf)
static char *	cli_show_settings (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
	Hashing and comparison functions for sorcery wizards.
static int	codec_handler_fn (const void *obj, const intptr_t *args, char **buf)
static int	double_handler_fn (const void *obj, const intptr_t *args, char **buf)
static struct ast_variable *	get_multiple_fields_as_var_list (const void *object, struct ast_sorcery_object_field *object_field)
static struct ast_variable *	get_single_field_as_var_list (const void *object, struct ast_sorcery_object_field *object_field)
static int	int_handler_fn (const void *obj, const intptr_t *args, char **buf)
static int	is_registered_cb (void *obj, void *arg, int flags)
static void	parse_general_options (void)
	Compare function for sorcery instances.
static int	sockaddr_handler_fn (const void *obj, const intptr_t *args, char **buf)
static int	sorcery_cache_create (void *obj, void *arg, int flags)
	Internal function used to create an object in caching wizards.
static void	sorcery_cleanup (void)
	Cleanup function for graceful shutdowns.
static void	sorcery_destructor (void *obj)
	Destructor called when sorcery structure is destroyed.
static int	sorcery_extended_config_handler (const struct aco_option *opt, struct ast_variable *var, void *obj)
static int	sorcery_extended_fields_handler (const void *obj, struct ast_variable **fields)
static sorcery_field_handler	sorcery_field_default_handler (enum aco_option_type type)
static int	sorcery_generic_observer_remove (void *obj, void *arg, int flags)
	Internal callback function for removing a generic observer.
static void	sorcery_internal_wizard_destructor (void *obj)
static void	sorcery_object_destructor (void *object)
static void	sorcery_object_field_destructor (void *obj)
static int	sorcery_object_load (void *obj, void *arg, int flags)
static struct ast_sorcery_object_type *	sorcery_object_type_alloc (const char *type, const char *module)
	Internal function which allocates an object type structure.
static void	sorcery_object_type_destructor (void *obj)
	Destructor function for object types.
static void	sorcery_object_wizard_destructor (void *obj)
	Object wizard destructor.
static struct sorcery_observer_invocation *	sorcery_observer_invocation_alloc (struct ast_sorcery_object_type *object_type, void *object)
	Allocator function for observer invocation.
static void	sorcery_observer_invocation_destroy (void *obj)
	Destructor for observer invocation.
static int	sorcery_observer_notify_create (void *obj, void *arg, int flags)
	Internal callback function which notifies an individual observer that an object has been created.
static int	sorcery_observer_notify_delete (void *obj, void *arg, int flags)
	Internal callback function which notifies an individual observer that an object has been deleted.
static int	sorcery_observer_notify_loaded (void *obj, void *arg, int flags)
	Internal callback function which notifies an individual observer that an object type has been loaded.
static int	sorcery_observer_notify_update (void *obj, void *arg, int flags)
	Internal callback function which notifies an individual observer that an object has been updated.
static int	sorcery_observer_remove (void *obj, void *arg, int flags)
	Internal callback function for removing an observer.
static int	sorcery_observers_notify_create (void *data)
	Internal callback function which notifies observers that an object has been created.
static int	sorcery_observers_notify_delete (void *data)
	Internal callback function which notifies observers that an object has been deleted.
static int	sorcery_observers_notify_loaded (void *data)
	Internal callback function which notifies observers that an object type has been loaded.
static int	sorcery_observers_notify_update (void *data)
	Internal callback function which notifies observers that an object has been updated.
static void	sorcery_proxy_cb (void *weakproxy, void *data)
	Hashing function for sorcery types.
static int	sorcery_reloadable (const struct ast_sorcery *sorcery, const char *type)
	Retrieves whether or not the type is reloadable.
static int	sorcery_wizard_create (const struct ast_sorcery_object_wizard *object_wizard, const struct sorcery_details *details)
	Internal function which returns if the wizard has created the object.
static int	sorcery_wizard_delete (const struct ast_sorcery_object_wizard *object_wizard, const struct sorcery_details *details)
	Internal function which returns if a wizard has deleted the object.
static int	sorcery_wizard_load (void *obj, void *arg, int flags)
static int	sorcery_wizard_update (const struct ast_sorcery_object_wizard *object_wizard, const struct sorcery_details *details)
	Internal function which returns if a wizard has updated the object.
static int	stringfield_handler_fn (const void *obj, const intptr_t *args, char **buf)
static int	uint_handler_fn (const void *obj, const intptr_t *args, char **buf)
static int	yesno_handler_fn (const void *obj, const intptr_t *args, char **buf)

Variables
int	ast_sorcery_update_or_create_on_update_miss = 0
	Global control for optional update->create fallback in backends.
static struct ast_cli_entry	cli_commands []
static struct ao2_container *	instances
	Registered sorcery instances.
struct ao2_container *	observers
	Registered global observers.
static struct ast_taskpool *	taskpool
	Taskpool for observers.
static struct ao2_container *	wizards
	Registered sorcery wizards.

Detailed Description

Sorcery Data Access Layer API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file sorcery.c.

Macro Definition Documentation

INITIAL_WIZARD_VECTOR_SIZE

#define INITIAL_WIZARD_VECTOR_SIZE   5

INSTANCE_BUCKETS

#define INSTANCE_BUCKETS   17

Number of buckets for instances (should be prime for performance reasons)

Definition at line 58 of file sorcery.c.

MAX_REGEX_ERROR_LEN

#define MAX_REGEX_ERROR_LEN   128

NOTIFY_GENERIC_OBSERVERS

#define NOTIFY_GENERIC_OBSERVERS	(		container,
			type,
			callback,
			...
	)

Definition at line 63 of file sorcery.c.

                                                                  { \
    struct ao2_iterator i = ao2_iterator_init(container, 0); \
    struct type *observer; \
    ao2_rdlock(container); \
    while ((observer = ao2_iterator_next(&i))) { \
        if (observer->callbacks->callback) { \
            observer->callbacks->callback(__VA_ARGS__); \
        } \
        ao2_cleanup(observer); \
    } \
    ao2_unlock(container); \
    ao2_iterator_cleanup(&i); \
})

NOTIFY_GLOBAL_OBSERVERS

#define NOTIFY_GLOBAL_OBSERVERS	(		container,
			callback,
			...
	)		NOTIFY_GENERIC_OBSERVERS(container, sorcery_global_observer, callback, __VA_ARGS__)

Definition at line 77 of file sorcery.c.

NOTIFY_INSTANCE_OBSERVERS

#define NOTIFY_INSTANCE_OBSERVERS	(		container,
			callback,
			...
	)		NOTIFY_GENERIC_OBSERVERS(container, sorcery_instance_observer, callback, __VA_ARGS__)

Definition at line 80 of file sorcery.c.

NOTIFY_WIZARD_OBSERVERS

#define NOTIFY_WIZARD_OBSERVERS	(		container,
			callback,
			...
	)		NOTIFY_GENERIC_OBSERVERS(container, sorcery_wizard_observer, callback, __VA_ARGS__)

Definition at line 83 of file sorcery.c.

OBJECT_FIELD_BUCKETS

#define OBJECT_FIELD_BUCKETS   29

Number of buckets for object fields (should be prime for performance reasons)

Definition at line 61 of file sorcery.c.

TYPE_BUCKETS

#define TYPE_BUCKETS   53

Number of buckets for types (should be prime for performance reasons)

Definition at line 55 of file sorcery.c.

WIZARD_BUCKETS

#define WIZARD_BUCKETS   7

Number of buckets for wizards (should be prime for performance reasons)

Definition at line 52 of file sorcery.c.

WIZARD_COMPARE

#define WIZARD_COMPARE	(		a,
			b
	)		((a)->wizard == (b))

WIZARD_NAME_COMPARE

#define WIZARD_NAME_COMPARE	(		a,
			b
	)		(strcmp((a)->wizard->callbacks.name, (b)) == 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
	)

Internal function which creates an object type and adds a wizard mapping.

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
	)

Internal function which creates an object type and inserts a wizard mapping.

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_name,
		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
	)

Internal function removes a wizard mapping.

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

)

Search function for sorcery instances.

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().

AST_VECTOR_RW()

AST_VECTOR_RW	(	ast_sorcery_object_wizards	,
		struct ast_sorcery_object_wizard *
	)

Interface for a sorcery object type wizards.

bool_handler_fn()

static int bool_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 314 of file sorcery.c.

{
    unsigned int *field = (unsigned int *)(obj + args[0]);
    return !(*buf = ast_strdup(*field ? "true" : "false")) ? -1 : 0;
}

References args, ast_strdup, and buf.

Referenced by sorcery_field_default_handler().

chararray_handler_fn()

static int chararray_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 332 of file sorcery.c.

{
    char *field = (char *)(obj + args[0]);
    return !(*buf = ast_strdup(field)) ? -1 : 0;
}

References args, ast_strdup, and buf.

Referenced by sorcery_field_default_handler().

cli_show_settings()

static char * cli_show_settings ( struct ast_cli_entry *  e, int  cmd, struct ast_cli_args *  a  )

static

Hashing and comparison functions for sorcery wizards.

Definition at line 376 of file sorcery.c.

{
    switch (cmd) {
    case CLI_INIT:
        e->command = "sorcery show settings";
        e->usage = "Usage: sorcery show settings\n"
               "      Show global configuration options\n";
        return NULL;
    case CLI_GENERATE:
        return NULL;
    }
 
    ast_cli(a->fd, "\nSorcery global settings\n");
    ast_cli(a->fd, "-----------------\n");
    ast_cli(a->fd, "  Update->Create fallback in backends: %s\n",
        ast_sorcery_update_or_create_on_update_miss ? "enabled" : "disabled");
 
    return CLI_SUCCESS;
}

References a, ast_cli(), ast_sorcery_update_or_create_on_update_miss, CLI_GENERATE, CLI_INIT, CLI_SUCCESS, and NULL.

codec_handler_fn()

static int codec_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 338 of file sorcery.c.

{
    struct ast_str *codec_buf = ast_str_alloca(AST_FORMAT_CAP_NAMES_LEN);
    struct ast_format_cap **cap = (struct ast_format_cap **)(obj + args[0]);
    return !(*buf = ast_strdup(ast_format_cap_get_names(*cap, &codec_buf)));
}

References args, ast_format_cap_get_names(), AST_FORMAT_CAP_NAMES_LEN, ast_str_alloca, ast_strdup, and buf.

Referenced by sorcery_field_default_handler().

double_handler_fn()

static int double_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 302 of file sorcery.c.

{
    double *field = (double *)(obj + args[0]);
    return (ast_asprintf(buf, "%f", *field) < 0) ? -1 : 0;
}

References args, ast_asprintf, and buf.

Referenced by sorcery_field_default_handler().

get_multiple_fields_as_var_list()

static struct ast_variable * get_multiple_fields_as_var_list ( const void *  object, struct ast_sorcery_object_field *  object_field  )

static

Definition at line 1559 of file sorcery.c.

{
    struct ast_variable *tmp = NULL;
 
    if (!object_field->multiple_handler) {
        return NULL;
    }
 
    if (object_field->multiple_handler(object, &tmp)) {
        ast_variables_destroy(tmp);
        tmp = NULL;
    }
 
    return tmp;
}

References ast_variables_destroy(), ast_sorcery_object_field::multiple_handler, and NULL.

Referenced by ast_sorcery_objectset_create2().

get_single_field_as_var_list()

static struct ast_variable * get_single_field_as_var_list ( const void *  object, struct ast_sorcery_object_field *  object_field  )

static

Definition at line 1542 of file sorcery.c.

{
    struct ast_variable *tmp = NULL;
    char *buf = NULL;
 
    if (!object_field->handler) {
        return NULL;
    }
 
    if (!(object_field->handler(object, object_field->args, &buf))) {
        tmp = ast_variable_new(object_field->name, S_OR(buf, ""), "");
    }
    ast_free(buf);
 
    return tmp;
}

References ast_sorcery_object_field::args, ast_free, ast_variable_new, buf, ast_sorcery_object_field::handler, ast_sorcery_object_field::name, NULL, and S_OR.

Referenced by ast_sorcery_objectset_create2().

int_handler_fn()

static int int_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 290 of file sorcery.c.

{
    int *field = (int *)(obj + args[0]);
    return (ast_asprintf(buf, "%d", *field) < 0) ? -1 : 0;
}

References args, ast_asprintf, and buf.

Referenced by sorcery_field_default_handler().

is_registered_cb()

static int is_registered_cb ( void *  obj, void *  arg, int  flags  )

static

Definition at line 2564 of file sorcery.c.

{
    struct ast_sorcery_object_field *object_field = obj;
    char *name = arg;
    int rc = 0;
 
    if (object_field->name_regex
        && !regexec(object_field->name_regex, name, 0, NULL, 0)) {
        rc = CMP_MATCH;
    }
 
    return rc;
}

References CMP_MATCH, name, ast_sorcery_object_field::name_regex, and NULL.

Referenced by ast_sorcery_is_object_field_registered().

parse_general_options()

static void parse_general_options ( void  )

static

Compare function for sorcery instances.

Hashing function for sorcery instances

Definition at line 425 of file sorcery.c.

{
    struct ast_flags flags = { 0 };
    struct ast_config *cfg = ast_config_load2("sorcery.conf", "sorcery", flags);
    const struct ast_variable *var;
 
    if (!cfg || cfg == CONFIG_STATUS_FILEINVALID) {
        return;
    }
 
    for (var = ast_variable_browse(cfg, "general"); var; var = var->next) {
        if (!strcasecmp(var->name, "update_or_create_on_update_miss")) {
            ast_sorcery_update_or_create_on_update_miss = ast_true(var->value);
        }
    }
 
    ast_config_destroy(cfg);
}

References ast_config_destroy(), ast_config_load2(), ast_sorcery_update_or_create_on_update_miss, ast_true(), ast_variable_browse(), CONFIG_STATUS_FILEINVALID, ast_flags::flags, ast_variable::next, and var.

Referenced by ast_sorcery_init().

sockaddr_handler_fn()

static int sockaddr_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 326 of file sorcery.c.

{
    struct ast_sockaddr *field = (struct ast_sockaddr *)(obj + args[0]);
    return !(*buf = ast_strdup(ast_sockaddr_stringify(field))) ? -1 : 0;
}

References args, ast_sockaddr_stringify(), ast_strdup, and buf.

Referenced by sorcery_field_default_handler().

sorcery_cache_create()

static int sorcery_cache_create ( void *  obj, void *  arg, int  flags  )

static

Internal function used to create an object in caching wizards.

Definition at line 1903 of file sorcery.c.

{
    const struct ast_sorcery_object_wizard *object_wizard = obj;
    const struct sorcery_details *details = arg;
 
    if (!object_wizard->caching || !object_wizard->wizard->callbacks.create) {
        return 0;
    }
 
    object_wizard->wizard->callbacks.create(details->sorcery, object_wizard->data, details->obj);
 
    return 0;
}

References ast_sorcery_object_wizard::caching, ast_sorcery_internal_wizard::callbacks, ast_sorcery_wizard::create, ast_sorcery_object_wizard::data, sorcery_details::obj, sorcery_details::sorcery, and ast_sorcery_object_wizard::wizard.

Referenced by ast_sorcery_retrieve_by_fields(), and ast_sorcery_retrieve_by_id().

sorcery_cleanup()

static void sorcery_cleanup ( void  )

static

Cleanup function for graceful shutdowns.

Definition at line 402 of file sorcery.c.

{
    ast_cli_unregister_multiple(cli_commands, ARRAY_LEN(cli_commands));
    ast_taskpool_shutdown(taskpool);
    taskpool = NULL;
    ao2_cleanup(wizards);
    wizards = NULL;
    ao2_cleanup(observers);
    observers = NULL;
    ao2_cleanup(instances);
    instances = NULL;
}

References ao2_cleanup, ARRAY_LEN, ast_cli_unregister_multiple(), ast_taskpool_shutdown(), cli_commands, instances, NULL, observers, taskpool, and wizards.

Referenced by ast_sorcery_init().

sorcery_destructor()

static void sorcery_destructor ( void *  obj )

static

Destructor called when sorcery structure is destroyed.

Definition at line 645 of file sorcery.c.

{
    struct ast_sorcery *sorcery = obj;
 
    if (sorcery->observers) {
        NOTIFY_GLOBAL_OBSERVERS(observers, instance_destroying, sorcery->module_name, sorcery);
    }
    ao2_cleanup(sorcery->observers);
    ao2_cleanup(sorcery->types);
}

References ao2_cleanup, ast_sorcery::module_name, NOTIFY_GLOBAL_OBSERVERS, ast_sorcery::observers, observers, sorcery, and ast_sorcery::types.

Referenced by __ast_sorcery_open().

sorcery_extended_config_handler()

static int sorcery_extended_config_handler ( const struct aco_option *  opt, struct ast_variable *  var, void *  obj  )

static

Definition at line 1107 of file sorcery.c.

{
    return ast_sorcery_object_set_extended(obj, var->name, var->value);
}

References ast_sorcery_object_set_extended(), and var.

Referenced by __ast_sorcery_object_register().

sorcery_extended_fields_handler()

static int sorcery_extended_fields_handler ( const void *  obj, struct ast_variable **  fields  )

static

Definition at line 1112 of file sorcery.c.

{
    const struct ast_sorcery_object_details *details = obj;
 
    if (details->object->extended) {
        *fields = ast_variables_dup(details->object->extended);
    } else {
        *fields = NULL;
    }
 
    return 0;
}

References ast_variables_dup(), ast_sorcery_object::extended, NULL, and ast_sorcery_object_details::object.

Referenced by __ast_sorcery_object_register().

sorcery_field_default_handler()

static sorcery_field_handler sorcery_field_default_handler ( enum aco_option_type  type )

static

Definition at line 345 of file sorcery.c.

{
    switch(type) {
    case OPT_BOOL_T: return bool_handler_fn;
    case OPT_YESNO_T: return yesno_handler_fn;
    case OPT_CHAR_ARRAY_T: return chararray_handler_fn;
    case OPT_CODEC_T: return codec_handler_fn;
    case OPT_DOUBLE_T: return double_handler_fn;
    case OPT_INT_T: return int_handler_fn;
    case OPT_SOCKADDR_T: return sockaddr_handler_fn;
    case OPT_STRINGFIELD_T: return stringfield_handler_fn;
    case OPT_UINT_T: return uint_handler_fn;
 
    default:
    case OPT_CUSTOM_T: return NULL;
    }
 
    return NULL;
}

References bool_handler_fn(), chararray_handler_fn(), codec_handler_fn(), double_handler_fn(), int_handler_fn(), NULL, OPT_BOOL_T, OPT_CHAR_ARRAY_T, OPT_CODEC_T, OPT_CUSTOM_T, OPT_DOUBLE_T, OPT_INT_T, OPT_SOCKADDR_T, OPT_STRINGFIELD_T, OPT_UINT_T, OPT_YESNO_T, sockaddr_handler_fn(), stringfield_handler_fn(), type, uint_handler_fn(), and yesno_handler_fn().

Referenced by __ast_sorcery_object_field_register().

sorcery_generic_observer_remove()

static int sorcery_generic_observer_remove ( void *  obj, void *  arg, int  flags  )

static

Internal callback function for removing a generic observer.

Definition at line 555 of file sorcery.c.

{
    const struct sorcery_global_observer *observer = obj;
 
    return (observer->callbacks == arg) ? CMP_MATCH : 0;
}

References CMP_MATCH, and observer.

Referenced by ast_sorcery_global_observer_remove(), ast_sorcery_instance_observer_remove(), and ast_sorcery_wizard_observer_remove().

sorcery_internal_wizard_destructor()

static void sorcery_internal_wizard_destructor ( void *  obj )

static

Definition at line 489 of file sorcery.c.

{
    struct ast_sorcery_internal_wizard *wizard = obj;
 
    ao2_cleanup(wizard->observers);
}

References ao2_cleanup, and ast_sorcery_internal_wizard::observers.

Referenced by __ast_sorcery_wizard_register().

sorcery_object_destructor()

static void sorcery_object_destructor ( void *  object )

static

Definition at line 1764 of file sorcery.c.

{
    struct ast_sorcery_object_details *details = object;
 
    if (details->object->destructor) {
        details->object->destructor(object);
    }
 
    ast_variables_destroy(details->object->extended);
    ast_free(details->object->id);
}

References ast_free, ast_variables_destroy(), ast_sorcery_object::destructor, ast_sorcery_object::extended, ast_sorcery_object::id, and ast_sorcery_object_details::object.

Referenced by ast_sorcery_generic_alloc(), and ast_sorcery_lockable_alloc().

sorcery_object_field_destructor()

static void sorcery_object_field_destructor ( void *  obj )

static

Definition at line 1214 of file sorcery.c.

{
    struct ast_sorcery_object_field *object_field = obj;
 
    if (object_field->name_regex) {
        regfree(object_field->name_regex);
        ast_free(object_field->name_regex);
    }
}

References ast_free, and ast_sorcery_object_field::name_regex.

Referenced by ast_sorcery_object_fields_register().

sorcery_object_load()

static int sorcery_object_load ( void *  obj, void *  arg, int  flags  )

static

Definition at line 1400 of file sorcery.c.

{
    struct ast_sorcery_object_type *type = obj;
    struct sorcery_load_details *details = arg;
 
    if (!type->type.item_alloc) {
        return 0;
    }
 
    details->type = type->name;
 
    if (details->reload && !sorcery_reloadable(details->sorcery, details->type)) {
        ast_log(LOG_NOTICE, "Type '%s' is not reloadable, maintaining previous values\n",
            details->type);
        return 0;
    }
 
    NOTIFY_INSTANCE_OBSERVERS(details->sorcery->observers, object_type_loading,
        details->sorcery->module_name, details->sorcery, type->name, details->reload);
 
    AST_VECTOR_RW_RDLOCK(&type->wizards);
    AST_VECTOR_CALLBACK(&type->wizards, sorcery_wizard_load, NULL, details, 0);
    AST_VECTOR_RW_UNLOCK(&type->wizards);
 
    NOTIFY_INSTANCE_OBSERVERS(details->sorcery->observers, object_type_loaded,
        details->sorcery->module_name, details->sorcery, type->name, details->reload);
 
    if (ao2_container_count(type->observers)) {
        struct sorcery_observer_invocation *invocation;
 
        invocation = sorcery_observer_invocation_alloc(type, NULL);
        if (invocation
            && ast_taskprocessor_push(type->serializer, sorcery_observers_notify_loaded,
                invocation)) {
            ao2_cleanup(invocation);
        }
    }
 
    return 0;
}

References ao2_cleanup, ao2_container_count(), ast_log, ast_taskprocessor_push(), AST_VECTOR_CALLBACK, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, LOG_NOTICE, ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, NULL, ast_sorcery::observers, sorcery_load_details::reload, sorcery_load_details::sorcery, sorcery_observer_invocation_alloc(), sorcery_observers_notify_loaded(), sorcery_reloadable(), sorcery_wizard_load(), type, and sorcery_load_details::type.

Referenced by ast_sorcery_force_reload(), ast_sorcery_force_reload_object(), ast_sorcery_load(), ast_sorcery_load_object(), ast_sorcery_reload(), and ast_sorcery_reload_object().

sorcery_object_type_alloc()

static struct ast_sorcery_object_type * sorcery_object_type_alloc ( const char *  type, const char *  module  )

static

Internal function which allocates an object type structure.

Definition at line 764 of file sorcery.c.

{
#define INITIAL_WIZARD_VECTOR_SIZE 5
    struct ast_sorcery_object_type *object_type;
    char tps_name[AST_TASKPROCESSOR_MAX_NAME + 1];
 
    if (!(object_type = ao2_alloc(sizeof(*object_type), sorcery_object_type_destructor))) {
        return NULL;
    }
 
    /* Order matters for object wizards */
    if (AST_VECTOR_RW_INIT(&object_type->wizards, INITIAL_WIZARD_VECTOR_SIZE) != 0) {
        ao2_ref(object_type, -1);
        return NULL;
    }
 
    object_type->fields = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_NOLOCK, 0,
        OBJECT_FIELD_BUCKETS, ast_sorcery_object_field_hash_fn, NULL, ast_sorcery_object_field_cmp_fn);
    if (!object_type->fields) {
        ao2_ref(object_type, -1);
        return NULL;
    }
 
    object_type->observers = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_RWLOCK, 0,
        NULL, NULL);
    if (!object_type->observers) {
        ao2_ref(object_type, -1);
        return NULL;
    }
 
    object_type->info = ast_calloc(1,
        sizeof(*object_type->info) + 2 * sizeof(object_type->info->files[0]));
    if (!object_type->info) {
        ao2_ref(object_type, -1);
        return NULL;
    }
 
    object_type->file = ast_calloc(1,
        sizeof(*object_type->file) + 2 * sizeof(object_type->file->types[0]));
    if (!object_type->file) {
        ao2_ref(object_type, -1);
        return NULL;
    }
 
    /* Create name with seq number appended. */
    ast_taskprocessor_build_name(tps_name, sizeof(tps_name), "sorcery/%s", type);
 
    if (!(object_type->serializer = ast_taskpool_serializer(tps_name, taskpool))) {
        ao2_ref(object_type, -1);
        return NULL;
    }
 
    object_type->info->files[0] = object_type->file;
    object_type->info->files[1] = NULL;
    object_type->info->module = module;
 
    ast_copy_string(object_type->name, type, sizeof(object_type->name));
 
    return object_type;
}

References ao2_alloc, AO2_ALLOC_OPT_LOCK_NOLOCK, AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_hash, ao2_container_alloc_list, ao2_ref, ast_calloc, ast_copy_string(), ast_taskpool_serializer(), ast_taskprocessor_build_name(), AST_TASKPROCESSOR_MAX_NAME, AST_VECTOR_RW_INIT, ast_sorcery_object_type::fields, ast_sorcery_object_type::file, aco_info::files, ast_sorcery_object_type::info, INITIAL_WIZARD_VECTOR_SIZE, ast_sorcery_object_type::name, NULL, OBJECT_FIELD_BUCKETS, ast_sorcery_object_type::observers, ast_sorcery_object_type::serializer, sorcery_object_type_destructor(), taskpool, type, aco_file::types, and ast_sorcery_object_type::wizards.

Referenced by __ast_sorcery_object_type_insert_wizard().

sorcery_object_type_destructor()

static void sorcery_object_type_destructor ( void *  obj )

static

Destructor function for object types.

Definition at line 742 of file sorcery.c.

{
    struct ast_sorcery_object_type *object_type = obj;
 
    AST_VECTOR_RW_WRLOCK(&object_type->wizards);
    AST_VECTOR_CALLBACK_VOID(&object_type->wizards, ao2_cleanup);
    AST_VECTOR_RW_UNLOCK(&object_type->wizards);
    AST_VECTOR_RW_FREE(&object_type->wizards);
    ao2_cleanup(object_type->fields);
    ao2_cleanup(object_type->observers);
 
    if (object_type->info) {
        aco_info_destroy(object_type->info);
        ast_free(object_type->info);
    }
 
    ast_free(object_type->file);
 
    ast_taskprocessor_unreference(object_type->serializer);
}

References aco_info_destroy(), ao2_cleanup, ast_free, ast_taskprocessor_unreference(), AST_VECTOR_CALLBACK_VOID, AST_VECTOR_RW_FREE, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, ast_sorcery_object_type::fields, ast_sorcery_object_type::file, ast_sorcery_object_type::info, ast_sorcery_object_type::observers, ast_sorcery_object_type::serializer, and ast_sorcery_object_type::wizards.

Referenced by sorcery_object_type_alloc().

sorcery_object_wizard_destructor()

static void sorcery_object_wizard_destructor ( void *  obj )

static

Object wizard destructor.

Definition at line 826 of file sorcery.c.

{
    struct ast_sorcery_object_wizard *object_wizard = obj;
 
    if (object_wizard->data && object_wizard->wizard->callbacks.close) {
        object_wizard->wizard->callbacks.close(object_wizard->data);
    }
 
    if (object_wizard->wizard) {
        ast_module_unref(object_wizard->wizard->callbacks.module);
    }
 
    ao2_cleanup(object_wizard->wizard);
}

References ao2_cleanup, ast_module_unref, ast_sorcery_internal_wizard::callbacks, ast_sorcery_wizard::close, ast_sorcery_object_wizard::data, and ast_sorcery_object_wizard::wizard.

Referenced by __ast_sorcery_object_type_insert_wizard().

sorcery_observer_invocation_alloc()

static struct sorcery_observer_invocation * sorcery_observer_invocation_alloc ( struct ast_sorcery_object_type *  object_type, void *  object  )

static

Allocator function for observer invocation.

Definition at line 1356 of file sorcery.c.

{
    struct sorcery_observer_invocation *invocation;
 
    invocation = ao2_alloc_options(sizeof(*invocation),
        sorcery_observer_invocation_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!invocation) {
        return NULL;
    }
 
    ao2_ref(object_type, +1);
    invocation->object_type = object_type;
 
    if (object) {
        ao2_ref(object, +1);
        invocation->object = object;
    }
 
    return invocation;
}

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, NULL, sorcery_observer_invocation::object, sorcery_observer_invocation::object_type, and sorcery_observer_invocation_destroy().

Referenced by ast_sorcery_create(), ast_sorcery_delete(), ast_sorcery_update(), and sorcery_object_load().

sorcery_observer_invocation_destroy()

static void sorcery_observer_invocation_destroy ( void *  obj )

static

Destructor for observer invocation.

Definition at line 1347 of file sorcery.c.

{
    struct sorcery_observer_invocation *invocation = obj;
 
    ao2_cleanup(invocation->object_type);
    ao2_cleanup(invocation->object);
}

References ao2_cleanup, sorcery_observer_invocation::object, and sorcery_observer_invocation::object_type.

Referenced by sorcery_observer_invocation_alloc().

sorcery_observer_notify_create()

static int sorcery_observer_notify_create ( void *  obj, void *  arg, int  flags  )

static

Internal callback function which notifies an individual observer that an object has been created.

Definition at line 2104 of file sorcery.c.

{
    const struct ast_sorcery_object_type_observer *observer = obj;
 
    if (observer->callbacks->created) {
        observer->callbacks->created(arg);
    }
 
    return 0;
}

References observer.

Referenced by sorcery_observers_notify_create().

sorcery_observer_notify_delete()

static int sorcery_observer_notify_delete ( void *  obj, void *  arg, int  flags  )

static

Internal callback function which notifies an individual observer that an object has been deleted.

Definition at line 2265 of file sorcery.c.

{
    const struct ast_sorcery_object_type_observer *observer = obj;
 
    if (observer->callbacks->deleted) {
        observer->callbacks->deleted(arg);
    }
 
    return 0;
}

References observer.

Referenced by sorcery_observers_notify_delete().

sorcery_observer_notify_loaded()

static int sorcery_observer_notify_loaded ( void *  obj, void *  arg, int  flags  )

static

Internal callback function which notifies an individual observer that an object type has been loaded.

Definition at line 1378 of file sorcery.c.

{
    const struct ast_sorcery_object_type_observer *observer = obj;
 
    if (observer->callbacks->loaded) {
        observer->callbacks->loaded(arg);
    }
 
    return 0;
}

References observer.

Referenced by sorcery_observers_notify_loaded().

sorcery_observer_notify_update()

static int sorcery_observer_notify_update ( void *  obj, void *  arg, int  flags  )

static

Internal callback function which notifies an individual observer that an object has been updated.

Definition at line 2177 of file sorcery.c.

{
    const struct ast_sorcery_object_type_observer *observer = obj;
 
    if (observer->callbacks->updated) {
        observer->callbacks->updated(arg);
    }
 
    return 0;
}

References observer.

Referenced by sorcery_observers_notify_update().

sorcery_observer_remove()

static int sorcery_observer_remove ( void *  obj, void *  arg, int  flags  )

static

Internal callback function for removing an observer.

Definition at line 2480 of file sorcery.c.

{
    const struct ast_sorcery_object_type_observer *observer = obj;
 
    return (observer->callbacks == arg) ? CMP_MATCH : 0;
}

References CMP_MATCH, and observer.

Referenced by ast_sorcery_observer_remove().

sorcery_observers_notify_create()

static int sorcery_observers_notify_create ( void *  data )

static

Internal callback function which notifies observers that an object has been created.

Definition at line 2116 of file sorcery.c.

{
    struct sorcery_observer_invocation *invocation = data;
 
    ao2_callback(invocation->object_type->observers, OBJ_NODATA, sorcery_observer_notify_create, invocation->object);
    ao2_cleanup(invocation);
 
    return 0;
}

References ao2_callback, ao2_cleanup, OBJ_NODATA, sorcery_observer_invocation::object, sorcery_observer_invocation::object_type, ast_sorcery_object_type::observers, and sorcery_observer_notify_create().

Referenced by ast_sorcery_create().

sorcery_observers_notify_delete()

static int sorcery_observers_notify_delete ( void *  data )

static

Internal callback function which notifies observers that an object has been deleted.

Definition at line 2277 of file sorcery.c.

{
    struct sorcery_observer_invocation *invocation = data;
 
    ao2_callback(invocation->object_type->observers, OBJ_NODATA, sorcery_observer_notify_delete, invocation->object);
    ao2_cleanup(invocation);
 
    return 0;
}

References ao2_callback, ao2_cleanup, OBJ_NODATA, sorcery_observer_invocation::object, sorcery_observer_invocation::object_type, ast_sorcery_object_type::observers, and sorcery_observer_notify_delete().

Referenced by ast_sorcery_delete().

sorcery_observers_notify_loaded()

static int sorcery_observers_notify_loaded ( void *  data )

static

Internal callback function which notifies observers that an object type has been loaded.

Definition at line 1390 of file sorcery.c.

{
    struct sorcery_observer_invocation *invocation = data;
 
    ao2_callback(invocation->object_type->observers, OBJ_NODATA, sorcery_observer_notify_loaded, invocation->object_type->name);
    ao2_cleanup(invocation);
 
    return 0;
}

References ao2_callback, ao2_cleanup, ast_sorcery_object_type::name, OBJ_NODATA, sorcery_observer_invocation::object_type, ast_sorcery_object_type::observers, and sorcery_observer_notify_loaded().

Referenced by sorcery_object_load().

sorcery_observers_notify_update()

static int sorcery_observers_notify_update ( void *  data )

static

Internal callback function which notifies observers that an object has been updated.

Definition at line 2189 of file sorcery.c.

{
    struct sorcery_observer_invocation *invocation = data;
 
    ao2_callback(invocation->object_type->observers, OBJ_NODATA, sorcery_observer_notify_update, invocation->object);
    ao2_cleanup(invocation);
 
    return 0;
}

References ao2_callback, ao2_cleanup, OBJ_NODATA, sorcery_observer_invocation::object, sorcery_observer_invocation::object_type, ast_sorcery_object_type::observers, and sorcery_observer_notify_update().

Referenced by ast_sorcery_update().

sorcery_proxy_cb()

static void sorcery_proxy_cb ( void *  weakproxy, void *  data  )

static

Hashing function for sorcery types.

Definition at line 660 of file sorcery.c.

{
    ao2_unlink(instances, weakproxy);
}

References ao2_unlink, and instances.

Referenced by __ast_sorcery_open().

sorcery_reloadable()

static int sorcery_reloadable ( const struct ast_sorcery *  sorcery, const char *  type  )

static

Retrieves whether or not the type is reloadable.

Definition at line 1310 of file sorcery.c.

{
    RAII_VAR(struct ast_sorcery_object_type *, object_type,
         ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
    return object_type && object_type->reloadable;
}

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

Referenced by sorcery_object_load().

sorcery_wizard_create()

static int sorcery_wizard_create ( const struct ast_sorcery_object_wizard *  object_wizard, const struct sorcery_details *  details  )

static

Internal function which returns if the wizard has created the object.

Definition at line 2089 of file sorcery.c.

{
    if (!object_wizard->wizard->callbacks.create || object_wizard->read_only) {
        ast_debug(5, "Sorcery wizard '%s' does not support creation\n", object_wizard->wizard->callbacks.name);
        return 0;
    }
 
    if (object_wizard->wizard->callbacks.create(details->sorcery, object_wizard->data, details->obj)) {
        return 0;
    }
 
    return CMP_MATCH;
}

References ast_debug, ast_sorcery_internal_wizard::callbacks, CMP_MATCH, ast_sorcery_wizard::create, ast_sorcery_object_wizard::data, ast_sorcery_wizard::name, sorcery_details::obj, ast_sorcery_object_wizard::read_only, sorcery_details::sorcery, and ast_sorcery_object_wizard::wizard.

Referenced by ast_sorcery_create().

sorcery_wizard_delete()

static int sorcery_wizard_delete ( const struct ast_sorcery_object_wizard *  object_wizard, const struct sorcery_details *  details  )

static

Internal function which returns if a wizard has deleted the object.

Definition at line 2288 of file sorcery.c.

{
    if (!object_wizard->wizard->callbacks.delete || object_wizard->read_only) {
        ast_debug(5, "Sorcery wizard '%s' does not support deletion\n", object_wizard->wizard->callbacks.name);
        return 0;
    }
 
    if (object_wizard->wizard->callbacks.delete(details->sorcery, object_wizard->data, details->obj)) {
        return 0;
    }
 
    return CMP_MATCH;
}

References ast_debug, ast_sorcery_internal_wizard::callbacks, CMP_MATCH, ast_sorcery_object_wizard::data, ast_sorcery_wizard::delete, ast_sorcery_wizard::name, sorcery_details::obj, ast_sorcery_object_wizard::read_only, sorcery_details::sorcery, and ast_sorcery_object_wizard::wizard.

Referenced by ast_sorcery_delete().

sorcery_wizard_load()

static int sorcery_wizard_load ( void *  obj, void *  arg, int  flags  )

static

Definition at line 1317 of file sorcery.c.

{
    struct ast_sorcery_object_wizard *wizard = obj;
    struct sorcery_load_details *details = arg;
    void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
 
    if (details->reload) {
        if (details->force && wizard->wizard->callbacks.force_reload) {
            load = wizard->wizard->callbacks.force_reload;
        } else {
            load = wizard->wizard->callbacks.reload;
        }
    } else {
        load = wizard->wizard->callbacks.load;
    }
 
    if (load) {
        NOTIFY_WIZARD_OBSERVERS(wizard->wizard->observers, wizard_loading,
            wizard->wizard->callbacks.name, &wizard->wizard->callbacks, details->type, details->reload);
 
        load(wizard->data, details->sorcery, details->type);
 
        NOTIFY_WIZARD_OBSERVERS(wizard->wizard->observers, wizard_loaded,
            wizard->wizard->callbacks.name, &wizard->wizard->callbacks, details->type, details->reload);
    }
 
    return 0;
}

References ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, sorcery_load_details::force, ast_sorcery_wizard::force_reload, ast_sorcery_wizard::load, ast_sorcery_wizard::name, NOTIFY_WIZARD_OBSERVERS, ast_sorcery_internal_wizard::observers, ast_sorcery_wizard::reload, sorcery_load_details::reload, sorcery_load_details::sorcery, sorcery, type, sorcery_load_details::type, and ast_sorcery_object_wizard::wizard.

Referenced by sorcery_object_load().

sorcery_wizard_update()

static int sorcery_wizard_update ( const struct ast_sorcery_object_wizard *  object_wizard, const struct sorcery_details *  details  )

static

Internal function which returns if a wizard has updated the object.

Definition at line 2200 of file sorcery.c.

{
    if (!object_wizard->wizard->callbacks.update || object_wizard->read_only) {
        ast_debug(5, "Sorcery wizard '%s' does not support updating\n", object_wizard->wizard->callbacks.name);
        return 0;
    }
 
    if (object_wizard->wizard->callbacks.update(details->sorcery, object_wizard->data, details->obj)) {
        return 0;
    }
 
    return CMP_MATCH;
}

References ast_debug, ast_sorcery_internal_wizard::callbacks, CMP_MATCH, ast_sorcery_object_wizard::data, ast_sorcery_wizard::name, sorcery_details::obj, ast_sorcery_object_wizard::read_only, sorcery_details::sorcery, ast_sorcery_wizard::update, and ast_sorcery_object_wizard::wizard.

Referenced by ast_sorcery_update().

stringfield_handler_fn()

static int stringfield_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 308 of file sorcery.c.

{
    ast_string_field *field = (const char **)(obj + args[0]);
    return !(*buf = ast_strdup(*field)) ? -1 : 0;
}

References args, ast_strdup, and buf.

Referenced by sorcery_field_default_handler().

uint_handler_fn()

static int uint_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 296 of file sorcery.c.

{
    unsigned int *field = (unsigned int *)(obj + args[0]);
    return (ast_asprintf(buf, "%u", *field) < 0) ? -1 : 0;
}

References args, ast_asprintf, and buf.

Referenced by sorcery_field_default_handler().

yesno_handler_fn()

static int yesno_handler_fn ( const void *  obj, const intptr_t *  args, char **  buf  )

static

Definition at line 320 of file sorcery.c.

{
    unsigned int *field = (unsigned int *)(obj + args[0]);
    return !(*buf = ast_strdup(*field ? "yes" : "no")) ? -1 : 0;
}

References args, ast_strdup, and buf.

Referenced by sorcery_field_default_handler().

Variable Documentation

ast_sorcery_update_or_create_on_update_miss

int ast_sorcery_update_or_create_on_update_miss = 0

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().

cli_commands

struct ast_cli_entry cli_commands[]

static

Initial value:

= {
        { .handler =  cli_show_settings , .summary =  "Show global configuration options" ,},
}

Definition at line 397 of file sorcery.c.

                                             {
        AST_CLI_DEFINE(cli_show_settings, "Show global configuration options"),
};

Referenced by ast_sorcery_init(), and sorcery_cleanup().

instances

struct ao2_container* instances

static

Registered sorcery instances.

Definition at line 285 of file sorcery.c.

Referenced by __ast_sorcery_open(), ast_sorcery_init(), ast_sorcery_retrieve_by_module_name(), sorcery_cleanup(), and sorcery_proxy_cb().

observers

struct ao2_container* observers

Registered global observers.

Definition at line 282 of file sorcery.c.

Referenced by __ast_sorcery_open(), __ast_sorcery_wizard_register(), ast_sorcery_global_observer_add(), ast_sorcery_global_observer_remove(), ast_sorcery_init(), ast_sorcery_wizard_unregister(), sorcery_cleanup(), and sorcery_destructor().

taskpool

struct ast_taskpool* taskpool

static

Taskpool for observers.

Definition at line 87 of file sorcery.c.

Referenced by ast_serializer_taskpool_create(), ast_sorcery_init(), sorcery_cleanup(), and sorcery_object_type_alloc().

wizards

struct ao2_container* wizards

static

Registered sorcery wizards.

Definition at line 258 of file sorcery.c.

Referenced by __ast_sorcery_object_type_insert_wizard(), __ast_sorcery_wizard_register(), ast_sorcery_init(), ast_sorcery_wizard_observer_add(), ast_sorcery_wizard_observer_remove(), ast_sorcery_wizard_unregister(), and sorcery_cleanup().