sorcery.h File Reference

Sorcery Data Access Layer API. More...

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

Include dependency graph for sorcery.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

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

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

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

Functions
enum ast_sorcery_apply_result	__ast_sorcery_apply_config (struct ast_sorcery *sorcery, const char *name, const char *module)
	Apply configured wizard mappings. More...
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. More...
enum ast_sorcery_apply_result	__ast_sorcery_apply_wizard_mapping (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching)
	Apply additional object wizard mappings. More...
enum ast_sorcery_apply_result	__ast_sorcery_insert_wizard_mapping (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching, int position)
	Insert an additional object wizard mapping at a specific position in the wizard list. More...
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. More...
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. More...
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. More...
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. More...
struct ast_sorcery *	__ast_sorcery_open (const char *module, const char *file, int line, const char *func)
	Open a new sorcery structure. More...
int	__ast_sorcery_remove_wizard_mapping (struct ast_sorcery *sorcery, const char *type, const char *module, const char *name)
	Remove an object wizard mapping. More...
int	__ast_sorcery_wizard_register (const struct ast_sorcery_wizard *interface, struct ast_module *module)
	Register a sorcery wizard. More...
void *	ast_sorcery_alloc (const struct ast_sorcery *sorcery, const char *type, const char *id)
	Allocate an object. More...
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. More...
void *	ast_sorcery_copy (const struct ast_sorcery *sorcery, const void *object)
	Create a copy of an object. More...
int	ast_sorcery_create (const struct ast_sorcery *sorcery, void *object)
	Create and potentially persist an object using an available wizard. More...
int	ast_sorcery_delete (const struct ast_sorcery *sorcery, void *object)
	Delete an object. More...
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. More...
void	ast_sorcery_force_reload (const struct ast_sorcery *sorcery)
	Inform any wizards to reload persistent objects, even if no changes determined. More...
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. More...
void *	ast_sorcery_generic_alloc (size_t size, ao2_destructor_fn destructor)
	Allocate a generic sorcery capable object. More...
const char *	ast_sorcery_get_module (const struct ast_sorcery *sorcery)
	Get the module that has opened the provided sorcery instance. More...
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. More...
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. More...
int	ast_sorcery_get_wizard_mapping_count (struct ast_sorcery *sorcery, const char *type)
	Return the number of wizards mapped to an object type. More...
int	ast_sorcery_global_observer_add (const struct ast_sorcery_global_observer *callbacks)
	Add a global observer to sorcery. More...
void	ast_sorcery_global_observer_remove (const struct ast_sorcery_global_observer *callbacks)
	Remove a global observer from sorcery. More...
int	ast_sorcery_init (void)
	Initialize the sorcery API. More...
int	ast_sorcery_instance_observer_add (struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
	Add an observer to a sorcery instance. More...
void	ast_sorcery_instance_observer_remove (struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
	Remove an observer from a sorcery instance. More...
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. More...
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. More...
void	ast_sorcery_load (const struct ast_sorcery *sorcery)
	Inform any wizards to load persistent objects. More...
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. More...
void *	ast_sorcery_lockable_alloc (size_t size, ao2_destructor_fn destructor, void *lockobj)
	Allocate a generic sorcery capable object with locking. More...
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. More...
const struct timeval	ast_sorcery_object_get_created (const void *object)
	Get when the socery object was created. More...
const char *	ast_sorcery_object_get_extended (const void *object, const char *name)
	Get an extended field value from a sorcery object. More...
const char *	ast_sorcery_object_get_id (const void *object)
	Get the unique identifier of a sorcery object. More...
const char *	ast_sorcery_object_get_type (const void *object)
	Get the type of a sorcery object. More...
unsigned int	ast_sorcery_object_has_dynamic_contents (const void *object)
	Get whether an object contains dynamic contents or not. More...
int	ast_sorcery_object_id_compare (void *obj, void *arg, int flags)
	ao2 object comparator based on sorcery id. More...
int	ast_sorcery_object_id_hash (const void *obj, int flags)
	ao2 object hasher based on sorcery id. More...
int	ast_sorcery_object_id_sort (const void *obj, const void *arg, int flags)
	ao2 object sorter based on sorcery id. More...
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. More...
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. More...
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. More...
int	ast_sorcery_object_set_extended (const void *object, const char *name, const char *value)
	Set an extended field value on a sorcery object. More...
void	ast_sorcery_object_set_has_dynamic_contents (const void *object)
	Set the dynamic contents flag on a sorcery object. More...
int	ast_sorcery_object_unregister (struct ast_sorcery *sorcery, const char *type)
	Unregister an object type. More...
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. More...
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. More...
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. More...
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. More...
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. More...
void	ast_sorcery_ref (struct ast_sorcery *sorcery)
	Increase the reference count of a sorcery structure. More...
void	ast_sorcery_reload (const struct ast_sorcery *sorcery)
	Inform any wizards to reload persistent objects. More...
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. More...
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. More...
void *	ast_sorcery_retrieve_by_id (const struct ast_sorcery *sorcery, const char *type, const char *id)
	Retrieve an object using its unique identifier. More...
struct ast_sorcery *	ast_sorcery_retrieve_by_module_name (const char *module)
	Retrieves an existing sorcery instance by module name. More...
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. More...
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. More...
int	ast_sorcery_update (const struct ast_sorcery *sorcery, void *object)
	Update an object. More...
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. More...
void	ast_sorcery_wizard_observer_remove (struct ast_sorcery_wizard *wizard, const struct ast_sorcery_wizard_observer *callbacks)
	Remove an observer from a sorcery wizard. More...
int	ast_sorcery_wizard_unregister (const struct ast_sorcery_wizard *interface)
	Unregister a sorcery wizard. More...

Detailed Description

Sorcery Data Access Layer API.

Author

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

Definition in file sorcery.h.

Macro Definition Documentation

ast_sorcery_apply_config

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

Definition at line 456 of file sorcery.h.

Referenced by AST_TEST_DEFINE(), and load_module().

ast_sorcery_apply_default

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

Definition at line 477 of file sorcery.h.

Referenced by alloc_and_initialize_sorcery(), apply_list_configuration(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_domain_alias(), ast_sip_initialize_sorcery_global(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_sorcery_transport(), ast_sip_initialize_system(), AST_TEST_DEFINE(), load_module(), mwi_sorcery_init(), stir_shaken_certificate_load(), stir_shaken_general_load(), and stir_shaken_store_load().

ast_sorcery_apply_wizard_mapping

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

Apply additional object wizard mappings.

Parameters

sorcery	Pointer to a sorcery structure
type	Type of object to apply to
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 mapping

Note

This should be called after applying default mappings

Definition at line 511 of file sorcery.h.

Referenced by AST_TEST_DEFINE(), object_type_registered_observer(), and sorcery_memory_cache_thrash_create().

ast_sorcery_insert_wizard_mapping

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

Value:

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

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

Parameters

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

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Since

13.4.0

Definition at line 563 of file sorcery.h.

Referenced by AST_TEST_DEFINE(), and test_stir_shaken_create_cert().

ast_sorcery_internal_object_register

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

Register an internal, hidden object type.

Parameters

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

Return values

0	success
-1	failure

Definition at line 868 of file sorcery.h.

Referenced by alloc_and_initialize_sorcery(), ast_res_pjsip_initialize_configuration(), AST_TEST_DEFINE(), and sorcery_memory_cache_thrash_create().

ast_sorcery_object_field_register

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

Register a field within an object.

Parameters

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

Return values

0	success
-1	failure

Definition at line 955 of file sorcery.h.

Referenced by apply_list_configuration(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_domain_alias(), ast_sip_initialize_sorcery_global(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_sorcery_transport(), ast_sip_initialize_system(), load_module(), stir_shaken_certificate_load(), stir_shaken_general_load(), and stir_shaken_store_load().

ast_sorcery_object_field_register_alias

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

Register a field within an object as an alias.

Parameters

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

Return values

0	success
-1	failure

Definition at line 971 of file sorcery.h.

Referenced by ast_res_pjsip_initialize_configuration().

ast_sorcery_object_field_register_custom

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

Register a field within an object with custom handlers.

Parameters

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

Return values

0	success
-1	failure

Definition at line 1005 of file sorcery.h.

Referenced by apply_list_configuration(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_global(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_sorcery_transport(), load_module(), stir_shaken_certificate_load(), stir_shaken_general_load(), and stir_shaken_store_load().

ast_sorcery_object_field_register_custom_alias

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

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

Parameters

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

Return values

0	success
-1	failure

Definition at line 1022 of file sorcery.h.

ast_sorcery_object_field_register_custom_nodoc

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

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

Parameters

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

Return values

0	success
-1	failure

Definition at line 1040 of file sorcery.h.

Referenced by alloc_and_initialize_sorcery(), and AST_TEST_DEFINE().

ast_sorcery_object_field_register_nodoc

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

Register a field within an object without documentation.

Parameters

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

Return values

0	success
-1	failure

Definition at line 987 of file sorcery.h.

Referenced by alloc_and_initialize_sorcery(), AST_TEST_DEFINE(), and mwi_sorcery_init().

ast_sorcery_object_register

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

Register an object type.

Parameters

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

Return values

0	success
-1	failure

Definition at line 838 of file sorcery.h.

Referenced by apply_list_configuration(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_domain_alias(), ast_sip_initialize_sorcery_global(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_sorcery_transport(), load_module(), mwi_sorcery_init(), stir_shaken_certificate_load(), stir_shaken_general_load(), and stir_shaken_store_load().

ast_sorcery_object_register_no_reload

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

Register an object type that is not reloadable.

Parameters

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

Return values

0	success
-1	failure

Definition at line 853 of file sorcery.h.

Referenced by ast_sip_initialize_system().

ast_sorcery_object_type_apply_wizard

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

Value:

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

Apply additional object wizard mappings returning wizard information.

Since

13.26.0

16.3.0

Parameters

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

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

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

Definition at line 679 of file sorcery.h.

Referenced by AST_TEST_DEFINE().

ast_sorcery_object_type_insert_wizard

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

Value:

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

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

Since

13.26.0

16.3.0

Parameters

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

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

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

Definition at line 647 of file sorcery.h.

Referenced by AST_TEST_DEFINE().

ast_sorcery_object_type_remove_wizard

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

Value:

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

Remove an object wizard mapping.

Since

13.26.0

16.3.0

Parameters

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

Return values

0	success
-1	failure

Note

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

Definition at line 725 of file sorcery.h.

Referenced by AST_TEST_DEFINE().

ast_sorcery_objectset_create

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

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

Parameters

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

Return values

non-NULL	success
NULL	if error occurred

Note

The returned ast_variable list must be destroyed using ast_variables_destroy

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

Definition at line 1136 of file sorcery.h.

Referenced by ast_sip_cli_print_sorcery_objectset(), ast_sorcery_copy(), ast_sorcery_diff(), AST_TEST_DEFINE(), can_reuse_registration(), handle_export_primitives(), handle_pjproject_show_log_mappings(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), registration_deleted_observer(), return_sorcery_object(), sorcery_config_fields_cmp(), sorcery_function_read(), sorcery_memory_cached_object_alloc(), sorcery_memory_fields_cmp(), sorcery_realtime_create(), and sorcery_realtime_update().

ast_sorcery_open

#define ast_sorcery_open

(

)

__ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 408 of file sorcery.h.

Referenced by alloc_and_initialize_sorcery(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_system(), AST_TEST_DEFINE(), load_module(), mwi_sorcery_init(), and sorcery_memory_cache_thrash_create().

ast_sorcery_remove_wizard_mapping

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

Remove an object wizard mapping.

Parameters

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

Return values

0	success
-1	failure

Since

13.4.0

Definition at line 758 of file sorcery.h.

Referenced by AST_TEST_DEFINE(), and test_stir_shaken_cleanup_cert().

ast_sorcery_unref

#define ast_sorcery_unref

(

sorcery

)

ao2_cleanup(sorcery)

Decrease the reference count of a sorcery structure.

Parameters

sorcery

Pointer to a sorcery structure

Note

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

Definition at line 1502 of file sorcery.h.

Referenced by alloc_and_initialize_sorcery(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), ast_res_pjsip_destroy_configuration(), ast_res_pjsip_initialize_configuration(), ast_sip_destroy_system(), ast_sip_initialize_system(), AST_TEST_DEFINE(), bucket_cleanup(), deinitialize_sorcery(), load_module(), sorcery_function_read(), sorcery_memory_cache_thrash_destroy(), stale_cache_update_task_data_destructor(), stale_update_task_data_destructor(), and unload_module().

ast_sorcery_wizard_register

#define ast_sorcery_wizard_register

(

interface

)

__ast_sorcery_wizard_register(interface, AST_MODULE_SELF)

See __ast_sorcery_wizard_register()

Definition at line 383 of file sorcery.h.

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

MAX_OBJECT_FIELD

#define MAX_OBJECT_FIELD   128

Maximum length of an object field name.

Definition at line 110 of file sorcery.h.

Referenced by ast_sip_auths_to_str(), ast_sip_get_device_state(), ast_sip_location_create_contact(), callgroup_to_str(), cli_print_body(), contacts_to_str(), ident_to_str(), localnet_to_str(), localnet_to_vl_append(), match_to_str(), match_to_var_list_append(), named_callgroups_to_str(), named_pickupgroups_to_str(), pickupgroup_to_str(), set_var_to_str(), and transport_bind_to_str().

MAX_OBJECT_TYPE

#define MAX_OBJECT_TYPE   64

Maximum size of an object type.

Definition at line 107 of file sorcery.h.

SORCERY_OBJECT

#define SORCERY_OBJECT

(

details

)

Value:

struct {                                           \
   struct ast_sorcery_object_details details; \
}                                                  \

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

Definition at line 356 of file sorcery.h.

Typedef Documentation

sorcery_apply_handler

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

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

Note

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

Parameters

sorcery	Sorcery structure in use
obj	The object itself

Return values

0	Success
non-zero	Failure

Definition at line 194 of file sorcery.h.

sorcery_copy_handler

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

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

Parameters

src	The source object
dst	The destination object

Return values

0	success
-1	failure

Definition at line 205 of file sorcery.h.

sorcery_diff_handler

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

A callback function for generating a changeset between two objects.

Parameters

original	The original object
modified	The modified object
changes	The changeset
0	success
-1	failure

Definition at line 217 of file sorcery.h.

sorcery_field_handler

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

A callback function for translating a value into a string.

Parameters

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

Return values

0	success
-1	failure

Definition at line 158 of file sorcery.h.

sorcery_fields_handler

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

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

Parameters

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

Return values

0	success
-1	failure

Definition at line 169 of file sorcery.h.

sorcery_transform_handler

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

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

Parameters

set	The existing object set

Return values

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

Note

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

Definition at line 181 of file sorcery.h.

Enumeration Type Documentation

ast_sorcery_apply_result

enum ast_sorcery_apply_result

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

Definition at line 424 of file sorcery.h.

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

ast_sorcery_field_handler_flags

enum ast_sorcery_field_handler_flags

Field handler flags.

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

Definition at line 129 of file sorcery.h.

                                     {
   /*! \brief Try both handlers, string first */
   AST_HANDLER_PREFER_STRING,

   /*! \brief Try both handlers, list first */
   AST_HANDLER_PREFER_LIST,

   /*! \brief Use string handler only */
   AST_HANDLER_ONLY_STRING,

   /*! \brief Use list handler only */
   AST_HANDLER_ONLY_LIST,
};

ast_sorcery_retrieve_flags

enum ast_sorcery_retrieve_flags

Retrieval flags.

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

Definition at line 115 of file sorcery.h.

                                {
   /*! \brief Default retrieval flags */
   AST_RETRIEVE_FLAG_DEFAULT = 0,

   /*! \brief Return all matching objects */
   AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),

   /*! \brief Perform no matching, return all objects */
   AST_RETRIEVE_FLAG_ALL = (1 << 1),
};

ast_sorcery_wizard_apply_flags

enum ast_sorcery_wizard_apply_flags

Wizard Apply Flags.

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

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

Definition at line 576 of file sorcery.h.

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

ast_sorcery_wizard_position

enum ast_sorcery_wizard_position

Pre-defined locations to insert at.

Enumerator
AST_SORCERY_WIZARD_POSITION_LAST
AST_SORCERY_WIZARD_POSITION_FIRST

Definition at line 518 of file sorcery.h.

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

Function Documentation

__ast_sorcery_apply_config()

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

Apply configured wizard mappings.

Parameters

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

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

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

Returns

What happened when attempting to apply the config.

Definition at line 985 of file sorcery.c.

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_variable::name, ast_variable::next, RAII_VAR, strsep(), type, and ast_variable::value.

Referenced by __ast_sorcery_open().

{
   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;
}

__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 1031 of file sorcery.c.

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

{
   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);
}

__ast_sorcery_apply_wizard_mapping()

enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping	(	struct ast_sorcery *	sorcery,
		const char *	object_type_name,
		const char *	module,
		const char *	wizard_type_name,
		const char *	wizard_args,
		unsigned int	caching
	)

Apply additional object wizard mappings.

Parameters

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

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

Apply additional object wizard mappings.

Definition at line 977 of file sorcery.c.

References __ast_sorcery_insert_wizard_mapping(), and AST_SORCERY_WIZARD_POSITION_LAST.

Referenced by __ast_sorcery_apply_config(), and __ast_sorcery_apply_default().

{
   return __ast_sorcery_insert_wizard_mapping(sorcery, object_type_name, module, wizard_type_name,
      wizard_args, caching, AST_SORCERY_WIZARD_POSITION_LAST);
}

__ast_sorcery_insert_wizard_mapping()

enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping	(	struct ast_sorcery *	sorcery,
		const char *	object_type_name,
		const char *	module,
		const char *	wizard_type_name,
		const char *	wizard_args,
		unsigned int	caching,
		int	position
	)

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

Parameters

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

Returns

What occurred when applying the mapping

Note

This should be called after applying default mappings

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

Since

13.4.0

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

Definition at line 967 of file sorcery.c.

References __ast_sorcery_object_type_insert_wizard(), AST_SORCERY_WIZARD_APPLY_CACHING, AST_SORCERY_WIZARD_APPLY_NONE, and NULL.

Referenced by __ast_sorcery_apply_wizard_mapping().

{
   return __ast_sorcery_object_type_insert_wizard(sorcery, object_type_name, module, wizard_type_name,
      wizard_args, caching ? AST_SORCERY_WIZARD_APPLY_CACHING : AST_SORCERY_WIZARD_APPLY_NONE,
      position, NULL, NULL);
}

__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

Return values

0	success
-1	failure

Definition at line 1192 of file sorcery.c.

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, NULL, OBJ_KEY, RAII_VAR, sorcery_field_default_handler(), and ast_sorcery::types.

{
   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;
}

__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 1080 of file sorcery.c.

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_extended_config_handler(), sorcery_extended_fields_handler(), ast_sorcery_object_type::transform, and ast_sorcery::types.

{
   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;
}

__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 869 of file sorcery.c.

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, LOG_ERROR, LOG_WARNING, ast_sorcery::module_name, NOTIFY_INSTANCE_OBSERVERS, NULL, OBJ_KEY, ast_sorcery::observers, RAII_VAR, S_OR, sorcery_object_type_alloc(), sorcery_object_wizard_destructor(), ast_sorcery::types, and WIZARD_COMPARE.

Referenced by __ast_sorcery_insert_wizard_mapping().

{
   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;
}

__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 820 of file sorcery.c.

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, ast_sorcery::types, ast_sorcery_object_wizard::wizard, and ast_sorcery_object_wizard::wizard_args.

{
   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;
}

__ast_sorcery_open()

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

Open a new sorcery structure.

Parameters

module

The module name (AST_MODULE)

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

Return values

non-NULL	success
NULL	if allocation failed

Definition at line 601 of file sorcery.c.

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, LOG_ERROR, sorcery_proxy::module_name, ast_sorcery::module_name, NOTIFY_GLOBAL_OBSERVERS, NULL, OBJ_NOLOCK, OBJ_SEARCH_KEY, ast_sorcery::observers, sorcery, sorcery_destructor(), sorcery_proxy_cb(), TYPE_BUCKETS, and ast_sorcery::types.

{
   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;
}

__ast_sorcery_remove_wizard_mapping()

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

Remove an object wizard mapping.

Parameters

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

Return values

0	success
-1	failure

Since

13.4.0

Remove an object wizard mapping.

Definition at line 850 of file sorcery.c.

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

{
   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;
}

__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 432 of file sorcery.c.

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::module, ast_sorcery_wizard::name, NOTIFY_GLOBAL_OBSERVERS, NULL, OBJ_KEY, OBJ_NOLOCK, ast_sorcery_internal_wizard::observers, and sorcery_internal_wizard_destructor().

Referenced by ast_bucket_init().

{
   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(2, "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;
}

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 1744 of file sorcery.c.

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, ast_sorcery_object::type, and ast_sorcery::types.

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(), create_artificial_endpoint(), create_object(), create_resource_list(), global_loaded_observer(), load_module(), mock_retrieve_id(), mock_retrieve_multiple(), 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(), stir_shaken_general_loaded(), subscription_persistence_create(), and test_stir_shaken_create_cert().

{
   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;
}

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 1663 of file sorcery.c.

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

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

{
   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;
}

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 1778 of file sorcery.c.

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, 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(), and register_aor_core().

{
   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;
}

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 2057 of file sorcery.c.

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, sorcery_details::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(), create_resource_list(), load_module(), subscription_persistence_create(), and test_stir_shaken_create_cert().

{
   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;
}

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 2233 of file sorcery.c.

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, sorcery_details::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(), bucket_http_wizard_retrieve_id(), cleanup_resource_list(), mwi_mailbox_delete(), sub_persistence_recreate(), subscription_persistence_recreate(), subscription_persistence_remove(), test_stir_shaken_cleanup_cert(), and unload_module().

{
   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;
}

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 1805 of file sorcery.c.

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, and ast_sorcery::types.

Referenced by AST_TEST_DEFINE(), and transport_apply().

{
   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);
   }
}

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 1425 of file sorcery.c.

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

{
   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);
}

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 1457 of file sorcery.c.

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

Referenced by acl_change_stasis_cb().

{
   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);
}

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 1728 of file sorcery.c.

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(), auth_alloc(), bucket_alloc(), bucket_file_alloc(), contact_alloc(), domain_alias_alloc(), global_alloc(), ip_identify_alloc(), mapping_alloc(), mwi_sorcery_object_alloc(), phoneprov_alloc(), publication_resource_alloc(), resource_list_alloc(), sip_nat_hook_alloc(), sip_outbound_publish_alloc(), sip_outbound_registration_alloc(), sip_transport_alloc(), stir_shaken_certificate_alloc(), stir_shaken_general_alloc(), stir_shaken_store_alloc(), subscription_persistence_alloc(), system_alloc(), test_data_alloc(), and test_sorcery_object_alloc().

{
   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;
}

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 2531 of file sorcery.c.

References ast_sorcery::module_name.

Referenced by sorcery_memory_cache_load().

{
   return sorcery->module_name;
}

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 2489 of file sorcery.c.

References ao2_find, OBJ_SEARCH_KEY, and ast_sorcery::types.

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

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

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 790 of file sorcery.c.

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, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by AST_TEST_DEFINE().

{
   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;
}

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 778 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE().

{
   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);
}

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 498 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE(), and load_module().

{
   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;
}

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 514 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE(), and unload_module().

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

ast_sorcery_init()

int ast_sorcery_init

(

void

)

Initialize the sorcery API.

Return values

0	success
-1	failure

Initialize the sorcery API.

Hashing function for sorcery instances

Definition at line 387 of file sorcery.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_hash, ao2_container_alloc_list, ast_assert, ast_register_cleanup(), ast_threadpool_create(), AST_THREADPOOL_OPTIONS_VERSION, INSTANCE_BUCKETS, NULL, sorcery_cleanup(), ast_threadpool_options::version, and WIZARD_BUCKETS.

Referenced by asterisk_daemon().

{
   struct ast_threadpool_options options = {
      .version = AST_THREADPOOL_OPTIONS_VERSION,
      .auto_increment = 1,
      .max_size = 0,
      .idle_timeout = 60,
      .initial_size = 0,
   };
   ast_assert(wizards == NULL);

   threadpool = ast_threadpool_create("sorcery", NULL, &options);
   if (!threadpool) {
      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;
   }

   ast_register_cleanup(sorcery_cleanup);

   return 0;
}

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 520 of file sorcery.c.

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

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

{
   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;
}

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 537 of file sorcery.c.

References ao2_callback, OBJ_NODATA, OBJ_UNLINK, ast_sorcery::observers, 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(), stir_shaken_general_unload(), and unload_module().

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

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 2509 of file sorcery.c.

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

{
   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;
}

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 2283 of file sorcery.c.

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

{
   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;
}

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 1377 of file sorcery.c.

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

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

{
   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);
}

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 1393 of file sorcery.c.

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

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

{
   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);
}

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 1712 of file sorcery.c.

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

Referenced by aor_alloc().

{
   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;
}

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 1160 of file sorcery.c.

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, sorcery_object_field_destructor(), and ast_sorcery::types.

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

{
#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;
}

ast_sorcery_object_get_created()

const struct timeval ast_sorcery_object_get_created

(

const void *

object

)

Get when the socery object was created.

Since

14.0.0

Parameters

object

Pointer to a sorcery object

Return values

The	time when the object was created

Definition at line 2318 of file sorcery.c.

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

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

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 2330 of file sorcery.c.

References ast_sorcery_object::extended, 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().

{
   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;
}

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

Return values

unique

identifier

Definition at line 2312 of file sorcery.c.

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

Referenced by __print_debug_details(), allocate_subscription_tree(), allow_and_or_replace_unsolicited(), ami_outbound_registration_task(), ami_show_registration_contact_statuses(), anonymous_identify(), aor_deleted_observer(), apply_acls(), ast_bucket_file_json(), ast_bucket_json(), 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(), asterisk_publication_devicestate(), asterisk_publication_devicestate_refresh(), asterisk_publication_devicestate_state_change(), asterisk_publication_mailboxstate(), asterisk_publication_mwi_refresh(), asterisk_publication_mwi_state_change(), auth_apply(), auth_observer(), bucket_file_run_curl(), bucket_file_update_path(), bucket_http_test_wizard_create(), bucket_http_test_wizard_delete(), bucket_http_test_wizard_update(), build_resource_tree(), can_reuse_registration(), cancel_and_unpublish(), chan_pjsip_indicate(), chan_pjsip_new(), change_outgoing_sdp_stream_media_address(), 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_show_subscriptions_detail(), codec_prefs_handler(), common_identify(), connected_line_method_handler(), contact_apply_handler(), contact_function_get_permanent(), create_dialog_uas(), create_out_of_dialog_request(), create_rtp(), create_unsolicited_mwi_subscriptions(), current_state_reusable(), destroy_subscription(), digest_check_auth(), digest_create_request_with_auth(), direct_media_glare_mitigation_handler(), direct_media_method_handler(), domain_alias_apply(), endpt_send_request(), expire_objects_from_cache(), 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(), get_account_id(), get_curl_instance(), handle_export_primitives(), handle_incoming_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_module(), log_caps(), mark_object_as_stale_in_cache(), 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(), on_load_attestation(), permanent_uri_handler(), permanent_uri_sort_fn(), persistent_endpoint_find_or_create(), pjsip_aor_function_read(), publish_request_initial(), publisher_start(), publisher_stop(), pubsub_on_rx_mwi_notify_request(), pubsub_on_rx_publish_request(), pubsub_on_rx_subscribe_request(), qualify_contact_cb(), read_pjsip(), redirect_handler(), refer_incoming_attended_request(), refer_incoming_blind_request(), refer_incoming_invite_request(), refer_incoming_refer_request(), refer_progress_alloc(), register_aor_core(), registrar_contact_delete(), registrar_on_rx_request(), registration_deleted_observer(), registration_state_cmp(), registration_state_hash(), remove_from_cache(), remove_subscription(), 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(), set_outbound_authentication_credentials(), 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_cli_show(), stir_shaken_tab_complete_name(), subscription_established(), subscription_persistence_create(), subscription_persistence_remove(), subscription_tree_destructor(), tos_handler(), transport_apply(), transport_tls_file_handler(), transport_tos_handler(), update_devstate(), users_apply_handler(), and validate_publish_config().

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

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

Return values

type

of object

Definition at line 2324 of file sorcery.c.

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

Referenced by ast_sorcery_diff(), AST_TEST_DEFINE(), 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(), stale_item_update(), and stir_shaken_cli_show().

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

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 2372 of file sorcery.c.

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

Referenced by sorcery_config_internal_load().

{
   const struct ast_sorcery_object_details *details = object;

   return details->object->has_dynamic_contents;
}

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 2459 of file sorcery.c.

References ast_sorcery_object_id_sort(), and CMP_MATCH.

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

{
   int cmp;

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

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 2470 of file sorcery.c.

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

{
   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);
}

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 2435 of file sorcery.c.

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(), cli_aor_get_container(), cli_endpoint_get_container(), cli_get_container(), and sip_options_aor_alloc().

{
   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;
}

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 1114 of file sorcery.c.

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

Referenced by ast_sip_initialize_sorcery_location().

{
   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;
}

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 1128 of file sorcery.c.

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

Referenced by ast_bucket_init(), and AST_TEST_DEFINE().

{
   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;
}

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 1139 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE().

{
   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;
}

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 2344 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE(), and sorcery_extended_config_handler().

{
   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;
}

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 2379 of file sorcery.c.

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

Referenced by ip_identify_apply().

{
   const struct ast_sorcery_object_details *details = object;

   details->object->has_dynamic_contents = 1;
}

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 1061 of file sorcery.c.

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

Referenced by unload_module().

{
   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;
}

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 1632 of file sorcery.c.

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, ast_sorcery_object::type, and ast_sorcery::types.

Referenced by ast_ari_asterisk_update_object(), ast_sorcery_copy(), AST_TEST_DEFINE(), 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().

{
   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;
}

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 1511 of file sorcery.c.

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, tmp(), ast_sorcery_object::type, and ast_sorcery::types.

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

{
   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;
}

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 1565 of file sorcery.c.

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

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

{
   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;
}

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 2386 of file sorcery.c.

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

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

{
   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;
}

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

Return values

0	success
-1	failure

Definition at line 2418 of file sorcery.c.

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

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

{
   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);
}

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 1473 of file sorcery.c.

References ao2_ref.

{
   ao2_ref(sorcery, +1);
}

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 1408 of file sorcery.c.

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

Referenced by ast_res_pjsip_reload_configuration(), AST_TEST_DEFINE(), and reload_module().

{
   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);

}

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 1442 of file sorcery.c.

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

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

{
   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);
}

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 1897 of file sorcery.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_cleanup, ao2_container_alloc_list, ao2_container_count(), ao2_find, AST_RETRIEVE_FLAG_MULTIPLE, AST_VECTOR_CALLBACK, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_object_wizard::caching, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, NULL, OBJ_KEY, RAII_VAR, ast_sorcery_wizard::retrieve_fields, ast_sorcery_wizard::retrieve_multiple, sorcery_cache_create(), ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

Referenced by acl_on_rx_msg(), ami_show_registration_contact_statuses(), ami_show_resource_lists(), 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(), 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(), format_ami_endpoint_identify(), get_all_contacts(), get_publishes_and_update_state(), get_registrations(), get_system_cfg(), global_loaded_observer(), handle_export_primitives(), load_all_endpoints(), load_users(), memory_cache_populate(), process_nat(), registration_loaded_observer(), sip_options_aor_observer_modified_task(), sip_options_synchronize_task(), stale_cache_update(), stir_shaken_certificate_get_all(), stir_shaken_certificate_get_by_caller_id_number(), stir_shaken_general_get(), stir_shaken_store_get_all(), and subscription_persistence_load().

{
   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, 0, NULL, NULL);
      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) {
      AST_VECTOR_CALLBACK(&object_type->wizards, sorcery_cache_create, NULL, object, 0);
   }
   AST_VECTOR_RW_UNLOCK(&object_type->wizards);

   return object;
}

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 1853 of file sorcery.c.

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_object_wizard::caching, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, ast_sorcery_object_type::name, NULL, OBJ_SEARCH_KEY, ast_sorcery_wizard::retrieve_id, sorcery, sorcery_details::sorcery, sorcery_cache_create(), ast_sorcery::types, ast_sorcery_object_wizard::wizard, and ast_sorcery_object_type::wizards.

Referenced by ami_show_endpoint(), ami_sip_qualify(), anonymous_identify(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), ast_bucket_file_retrieve(), ast_bucket_retrieve(), 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_set_tpselector_from_transport_name(), AST_TEST_DEFINE(), 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_show_qualify_endpoint(), common_identify(), contact_observer_updated(), create_rtp(), find_aor(), find_aor_name(), find_endpoint(), format_ami_endpoint_transport(), get_log_mappings(), get_write_timeout(), handle_atsign(), handle_single_token(), handle_slash(), line_identify(), load_endpoint(), mwi_contact_changed(), mwi_contact_deleted(), mwi_subscription_shutdown(), on_rx_process_symmetric_transport(), pjsip_acf_dial_contacts_read(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), process_nat(), 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(), stir_shaken_certificate_get(), stir_shaken_store_get(), sub_persistence_recreate(), transfer(), and wait_for_cache_update().

{
   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;
}

ast_sorcery_retrieve_by_module_name()

struct ast_sorcery* ast_sorcery_retrieve_by_module_name

(

const char *

module_name

)

Retrieves an existing sorcery instance by module name.

Parameters

module

The module name

Return values

non-NULL	success
NULL	if no instance was found

Note

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

Retrieves an existing sorcery instance by module name.

Definition at line 672 of file sorcery.c.

References ao2_weakproxy_find, 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().

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

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 1984 of file sorcery.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_cleanup, ao2_container_alloc_list, ao2_container_count(), ao2_find, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_object_wizard::caching, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, NULL, OBJ_KEY, RAII_VAR, ast_sorcery_wizard::retrieve_prefix, 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().

{
   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, 0, NULL, NULL);
   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;
}

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 1949 of file sorcery.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_cleanup, ao2_container_alloc_list, ao2_container_count(), ao2_find, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, ast_sorcery_object_wizard::caching, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, NULL, OBJ_KEY, RAII_VAR, ast_sorcery_wizard::retrieve_regex, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

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

{
   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, 0, NULL, NULL);
   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;
}

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 2145 of file sorcery.c.

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, sorcery_details::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(), sorcery_memory_cache_thrash_update(), and subscription_persistence_update().

{
   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;
}

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

sorcery	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 543 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE().

{
   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;
}

ast_sorcery_wizard_observer_remove()

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

Remove an observer from a sorcery wizard.

Parameters

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

Definition at line 568 of file sorcery.c.

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

Referenced by AST_TEST_DEFINE().

{
   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);
   }
}

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 474 of file sorcery.c.

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

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

{
   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(2, "Sorcery unregistered wizard '%s'\n", interface->name);
      return 0;
   } else {
      return -1;
   }
}