Asterisk - The Open Source Telephony Project GIT-master-25686a5
Data Structures | Macros | Typedefs | Enumerations | Functions
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__)
 Open a new sorcery structure. More...
 
#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)
 
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_typeast_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 sorcery 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_variableast_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_jsonast_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_sorceryast_sorcery_retrieve_by_module_name (const char *module_name)
 Retrieves an existing sorcery instance by module name. More...
 
struct ao2_containerast_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_containerast_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 *interface, 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 455 of file sorcery.h.

◆ ast_sorcery_apply_default

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

Definition at line 476 of file sorcery.h.

◆ ast_sorcery_apply_wizard_mapping

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

Apply additional object wizard mappings.

Parameters
sorceryPointer to a sorcery structure
typeType of object to apply to
nameName of the wizard to use
dataData to be passed to wizard
cachingWizard should cache
Returns
What occurred when applying the mapping
Note
This should be called after applying default mappings

Definition at line 510 of file sorcery.h.

◆ ast_sorcery_insert_wizard_mapping

#define ast_sorcery_insert_wizard_mapping (   sorcery,
  type,
  name,
  data,
  caching,
  position 
)
Value:
(caching), (position))
#define AST_MODULE
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
static struct ast_sorcery * sorcery
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.
Definition: sorcery.c:967

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

Parameters
sorceryPointer to a sorcery structure
typeType of object to apply to
nameName of the wizard to use
dataData to be passed to wizard
cachingWizard should cache
positionOne of ast_sorcery_wizard_position
Returns
What occurred when applying the mapping
Note
This should be called after applying default mappings
Since
13.4.0

Definition at line 562 of file sorcery.h.

◆ ast_sorcery_internal_object_register

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

Register an internal, hidden object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
allocRequired object allocation callback
transformOptional transformation callback
applyOptional object set apply callback
Return values
0success
-1failure

Definition at line 867 of file sorcery.h.

◆ ast_sorcery_object_field_register

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

Register a field within an object.

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
opt_typeOption type
flagsOption type specific flags
Return values
0success
-1failure

Definition at line 955 of file sorcery.h.

◆ ast_sorcery_object_field_register_alias

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

Register a field within an object as an alias.

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
opt_typeOption type
flagsOption type specific flags
Return values
0success
-1failure

Definition at line 971 of file sorcery.h.

◆ ast_sorcery_object_field_register_custom

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

Register a field within an object with custom handlers.

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
config_handlerCustom configuration handler
sorcery_handlerCustom sorcery handler
multiple_handlerCustom multiple handler
flagsOption type specific flags
Return values
0success
-1failure

Definition at line 1005 of file sorcery.h.

◆ ast_sorcery_object_field_register_custom_alias

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

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

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
config_handlerCustom configuration handler
sorcery_handlerCustom sorcery handler
multiple_handlerCustom multiple handler
flagsOption type specific flags
Return values
0success
-1failure

Definition at line 1023 of file sorcery.h.

◆ ast_sorcery_object_field_register_custom_nodoc

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

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

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
config_handlerCustom configuration handler
sorcery_handlerCustom sorcery handler
multiple_handlerCustom multiple handler
flagsOption type specific flags
Return values
0success
-1failure

Definition at line 1041 of file sorcery.h.

◆ ast_sorcery_object_field_register_nodoc

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

Register a field within an object without documentation.

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
opt_typeOption type
flagsOption type specific flags
Return values
0success
-1failure

Definition at line 987 of file sorcery.h.

◆ ast_sorcery_object_register

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

Register an object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
allocRequired object allocation callback
transformOptional transformation callback
applyOptional object set apply callback
Return values
0success
-1failure

Definition at line 837 of file sorcery.h.

◆ ast_sorcery_object_register_no_reload

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

Register an object type that is not reloadable.

Parameters
sorceryPointer to a sorcery structure
typeType of object
allocRequired object allocation callback
transformOptional transformation callback
applyOptional object set apply callback
Return values
0success
-1failure

Definition at line 852 of file sorcery.h.

◆ ast_sorcery_object_type_apply_wizard

#define ast_sorcery_object_type_apply_wizard (   sorcery,
  object_type_name,
  wizard_type_name,
  wizard_args,
  flags,
  wizard,
  wizard_data 
)
Value:
(object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
AST_SORCERY_WIZARD_POSITION_LAST, (wizard), (wizard_data))
@ AST_SORCERY_WIZARD_POSITION_LAST
Definition: sorcery.h:518
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...
Definition: sorcery.c:869

Apply additional object wizard mappings returning wizard information.

Since
13.26.0
16.3.0
Parameters
sorceryPointer to a sorcery structure
object_type_nameName of the object type to apply to
wizard_type_nameName of the wizard type to use
wizard_argsOpaque string to be passed to the wizard May be NULL but see note below
flagsOne or more of enum ast_sorcery_wizard_apply_flags
[out]wizardA variable to receive a pointer to the ast_sorcery_wizard structure. May be NULL if not needed.
[out]wizard_dataA variable to receive a pointer to the wizard's internal data. May be NULL if not needed.
Returns
What occurred when applying the mapping
Note
This should be called after applying default mappings
Although wizard_args is an optional parameter it is highly recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE flag, and you intend to ever remove a wizard mapping, you'll need wizard_args to remove specific instances.

Definition at line 678 of file sorcery.h.

◆ ast_sorcery_object_type_insert_wizard

#define ast_sorcery_object_type_insert_wizard (   sorcery,
  object_type_name,
  wizard_type_name,
  wizard_args,
  flags,
  position,
  wizard,
  wizard_data 
)
Value:
(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
sorceryPointer to a sorcery structure
object_type_nameName of the object type to apply to
wizard_type_nameName of the wizard type to use
wizard_argsOpaque string to be passed to the wizard May be NULL but see note below
flagsOne or more of enum ast_sorcery_wizard_apply_flags
positionAn index to insert to or one of ast_sorcery_wizard_position
[out]wizardA variable to receive a pointer to the ast_sorcery_wizard structure. May be NULL if not needed.
[out]wizard_dataA variable to receive a pointer to the wizard's internal data. May be NULL if not needed.
Returns
What occurred when applying the mapping
Note
This should be called after applying default mappings
Although wizard_args is an optional parameter it is highly recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE flag, and you intend to ever remove a wizard mapping, you'll need wizard_args to remove specific instances.

Definition at line 646 of file sorcery.h.

◆ ast_sorcery_object_type_remove_wizard

#define ast_sorcery_object_type_remove_wizard (   sorcery,
  object_type_name,
  wizard_type_name,
  wizard_args 
)
Value:
AST_MODULE, (wizard_type_name), (wizard_args))
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.
Definition: sorcery.c:820

Remove an object wizard mapping.

Since
13.26.0
16.3.0
Parameters
sorceryPointer to a sorcery structure
object_type_nameName of the object type to remove from
wizard_type_nameThe name of the of the wizard type to remove
wizard_argsOpaque string originally passed to the wizard
Return values
0success
-1failure
Note
If there were multiple instances of the same wizard type added to this object type without using wizard_args, then only the first wizard matching wizard_type will be removed.

Definition at line 724 of file sorcery.h.

◆ ast_sorcery_objectset_create

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

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

Parameters
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
Return values
non-NULLsuccess
NULLif error occurred
Note
The returned ast_variable list must be destroyed using ast_variables_destroy
This function attempts to use a field's sorcery_fields_handler first and if that doesn't exist or fails, a field's sorcery_field_handler is used. The difference is that the former may return multiple list entries for the same field and the latter will only return 1. It's up to the field itself to determine what the appropriate content is.

Definition at line 1137 of file sorcery.h.

◆ ast_sorcery_open

#define ast_sorcery_open ( )    __ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Open a new sorcery structure.

Parameters
moduleThe 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-NULLsuccess
NULLif allocation failed

Definition at line 406 of file sorcery.h.

◆ ast_sorcery_remove_wizard_mapping

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

Remove an object wizard mapping.

Parameters
sorceryPointer to a sorcery structure
typeType of object to remove from
nameThe name of the wizard to remove
Return values
0success
-1failure
Since
13.4.0

Definition at line 757 of file sorcery.h.

◆ ast_sorcery_unref

#define ast_sorcery_unref (   sorcery)     ao2_cleanup(sorcery)

Decrease the reference count of a sorcery structure.

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

Definition at line 1500 of file sorcery.h.

◆ ast_sorcery_wizard_register

#define ast_sorcery_wizard_register (   interface)    __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)

See __ast_sorcery_wizard_register()

Definition at line 383 of file sorcery.h.

◆ MAX_OBJECT_FIELD

#define MAX_OBJECT_FIELD   128

Maximum length of an object field name.

Definition at line 110 of file sorcery.h.

◆ MAX_OBJECT_TYPE

#define MAX_OBJECT_TYPE   64

Maximum size of an object type.

Definition at line 107 of file sorcery.h.

◆ SORCERY_OBJECT

#define SORCERY_OBJECT (   details)
Value:
struct { \
struct ast_sorcery_object_details details; \
} \
Structure which contains details about a sorcery object.
Definition: sorcery.h:350

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
sorcerySorcery structure in use
objThe object itself
Return values
0Success
non-zeroFailure

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
srcThe source object
dstThe destination object
Return values
0success
-1failure

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
originalThe original object
modifiedThe modified object
changesThe changeset
Return values
0success
-1failure

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
objObject to get value from
argsWhere the field is
bufPointer to the buffer that the handler has created which contains the field value
Return values
0success
-1failure

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
objObject to get values from
fieldsPointer to store the list of fields
Return values
0success
-1failure

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
setThe existing object set
Return values
non-NULLnew object set if changed
NULLif no changes present
Note
The returned ast_variable list must be new. You can not return the input set.

Definition at line 169 of file sorcery.h.

Enumeration Type Documentation

◆ ast_sorcery_apply_result

Enumerator
AST_SORCERY_APPLY_FAIL 

Sorcery wizard failed to apply.

AST_SORCERY_APPLY_SUCCESS 

Sorcery wizard applied successfully.

AST_SORCERY_APPLY_DUPLICATE 

Sorcery wizard has already been applied to the object type.

AST_SORCERY_APPLY_DEFAULT_UNNECESSARY 

Default sorcery wizard is unnecessary since a wizard has already been applied to the object type.

AST_SORCERY_APPLY_NO_CONFIGURATION 

No sorcery.conf configuration file was found to apply.

Definition at line 423 of file sorcery.h.

423 {
424 /*! Sorcery wizard failed to apply. */
426 /*! Sorcery wizard applied successfully. */
428 /*! Sorcery wizard has already been applied to the object type. */
430 /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
432 /*! No sorcery.conf configuration file was found to apply. */
434};
@ AST_SORCERY_APPLY_SUCCESS
Definition: sorcery.h:427
@ AST_SORCERY_APPLY_NO_CONFIGURATION
Definition: sorcery.h:433
@ AST_SORCERY_APPLY_FAIL
Definition: sorcery.h:425
@ AST_SORCERY_APPLY_DUPLICATE
Definition: sorcery.h:429
@ AST_SORCERY_APPLY_DEFAULT_UNNECESSARY
Definition: sorcery.h:431

◆ 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.

129 {
130 /*! \brief Try both handlers, string first */
132
133 /*! \brief Try both handlers, list first */
135
136 /*! \brief Use string handler only */
138
139 /*! \brief Use list handler only */
141};
@ AST_HANDLER_PREFER_STRING
Try both handlers, string first.
Definition: sorcery.h:131
@ AST_HANDLER_PREFER_LIST
Try both handlers, list first.
Definition: sorcery.h:134
@ AST_HANDLER_ONLY_LIST
Use list handler only.
Definition: sorcery.h:140
@ AST_HANDLER_ONLY_STRING
Use string handler only.
Definition: sorcery.h:137

◆ 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.

115 {
116 /*! \brief Default retrieval flags */
118
119 /*! \brief Return all matching objects */
121
122 /*! \brief Perform no matching, return all objects */
123 AST_RETRIEVE_FLAG_ALL = (1 << 1),
124};
@ AST_RETRIEVE_FLAG_MULTIPLE
Return all matching objects.
Definition: sorcery.h:120
@ AST_RETRIEVE_FLAG_DEFAULT
Default retrieval flags.
Definition: sorcery.h:117
@ AST_RETRIEVE_FLAG_ALL
Perform no matching, return all objects.
Definition: sorcery.h:123

◆ ast_sorcery_wizard_apply_flags

Wizard Apply Flags.

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

Enumerator
AST_SORCERY_WIZARD_APPLY_NONE 

Apply no special behavior

AST_SORCERY_WIZARD_APPLY_CACHING 

This wizard will cache this object type's entries

AST_SORCERY_WIZARD_APPLY_READONLY 

This wizard won't allow Create, Update or Delete operations on this object type

AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE 

This wizard will allow other instances of itself on the same object type

Definition at line 575 of file sorcery.h.

575 {
576 /*! Apply no special behavior */
578 /*! This wizard will cache this object type's entries */
580 /*! This wizard won't allow Create, Update or Delete operations on this object type */
582 /*! This wizard will allow other instances of itself on the same object type */
584};
@ AST_SORCERY_WIZARD_APPLY_NONE
Definition: sorcery.h:577
@ AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
Definition: sorcery.h:583
@ AST_SORCERY_WIZARD_APPLY_READONLY
Definition: sorcery.h:581
@ AST_SORCERY_WIZARD_APPLY_CACHING
Definition: sorcery.h:579

◆ ast_sorcery_wizard_position

Pre-defined locations to insert at.

Enumerator
AST_SORCERY_WIZARD_POSITION_LAST 
AST_SORCERY_WIZARD_POSITION_FIRST 

Definition at line 517 of file sorcery.h.

517 {
520};
@ AST_SORCERY_WIZARD_POSITION_FIRST
Definition: sorcery.h:519

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
sorceryPointer to a sorcery structure
nameName of the category to use within the configuration file, normally the module name
moduleThe 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.

986{
987 struct ast_flags flags = { 0 };
988 struct ast_config *config = ast_config_load2("sorcery.conf", "sorcery", flags);
989 struct ast_variable *mapping;
991
992 if (!config) {
994 }
995
998 }
999
1000 for (mapping = ast_variable_browse(config, name); mapping; mapping = mapping->next) {
1001 RAII_VAR(char *, mapping_name, ast_strdup(mapping->name), ast_free);
1002 RAII_VAR(char *, mapping_value, ast_strdup(mapping->value), ast_free);
1003 char *options = mapping_name;
1004 char *type = strsep(&options, "/");
1005 char *data = mapping_value;
1006 char *wizard = strsep(&data, ",");
1007 unsigned int caching = 0;
1008
1009 /* If no object type or wizard exists just skip, nothing we can do */
1010 if (ast_strlen_zero(type) || ast_strlen_zero(wizard)) {
1011 continue;
1012 }
1013
1014 /* If the wizard is configured as a cache treat it as such */
1015 if (!ast_strlen_zero(options) && strstr(options, "cache")) {
1016 caching = 1;
1017 }
1018
1019 /* Any error immediately causes us to stop */
1020 if (__ast_sorcery_apply_wizard_mapping(sorcery, type, module, wizard, data, caching) == AST_SORCERY_APPLY_FAIL) {
1022 break;
1023 }
1024 }
1025
1027
1028 return res;
1029}
#define ast_free(a)
Definition: astmm.h:180
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
static const char config[]
Definition: chan_ooh323.c:111
char * strsep(char **str, const char *delims)
struct ast_config * ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags)
Load a config file.
Definition: main/config.c:3321
#define CONFIG_STATUS_FILEINVALID
void ast_config_destroy(struct ast_config *cfg)
Destroys a config.
Definition: extconf.c:1289
struct ast_variable * ast_variable_browse(const struct ast_config *config, const char *category_name)
Definition: extconf.c:1215
enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching)
Internal function which creates an object type and adds a wizard mapping.
Definition: sorcery.c:977
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
Structure used to handle boolean flags.
Definition: utils.h:199
unsigned int flags
Definition: utils.h:200
Structure for variables, used for configurations and for channel variables.
struct ast_variable * next
static struct test_options options
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941

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

Referenced by __ast_sorcery_open().

◆ __ast_sorcery_apply_default()

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

Apply default object wizard mappings.

Parameters
sorceryPointer to a sorcery structure
typeType of object to apply to
moduleThe name of the module, typically AST_MODULE
nameName of the wizard to use
dataData 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.

1032{
1034
1035 /* Defaults can not be added if any existing mapping exists */
1036 if (object_type) {
1038 }
1039
1040 return __ast_sorcery_apply_wizard_mapping(sorcery, type, module, name, data, 0);
1041}
#define OBJ_KEY
Definition: astobj2.h:1151
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1736
Structure for registered object type.
Definition: sorcery.c:148
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232

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

◆ __ast_sorcery_apply_wizard_mapping()

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

Apply additional object wizard mappings.

Parameters
sorceryPointer to a sorcery structure
typeType of object to apply to
moduleThe name of the module, typically AST_MODULE
nameName of the wizard to use
dataData to be passed to wizard
cachingWizard 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.

980{
982 data, caching, AST_SORCERY_WIZARD_POSITION_LAST);
983}
enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching, int position)
Internal function which creates an object type and inserts a wizard mapping.
Definition: sorcery.c:967

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

Referenced by __ast_sorcery_apply_config(), and __ast_sorcery_apply_default().

◆ __ast_sorcery_insert_wizard_mapping()

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

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

Parameters
sorceryPointer to a sorcery structure
typeType of object to apply to
moduleThe name of the module, typically AST_MODULE
nameName of the wizard to use
dataData to be passed to wizard
cachingWizard should cache
positionAn 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.

970{
973 position, NULL, NULL);
974}
#define NULL
Definition: resample.c:96
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...
Definition: sorcery.c:869

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

Referenced by __ast_sorcery_apply_wizard_mapping().

◆ __ast_sorcery_object_field_register()

int __ast_sorcery_object_field_register ( struct ast_sorcery sorcery,
const char *  type,
const char *  name,
const char *  default_val,
enum aco_option_type  opt_type,
aco_option_handler  config_handler,
sorcery_field_handler  sorcery_handler,
sorcery_fields_handler  multiple_handler,
unsigned int  flags,
unsigned int  no_doc,
unsigned int  alias,
size_t  argc,
  ... 
)

Register a field within an object.

Parameters
sorceryPointer to a sorcery structure
typeType of object
nameName of the field
default_valDefault value of the field
config_handlerA custom handler for translating the string representation of the fields
sorcery_handlerA custom handler for translating the native representation of the fields
multiple_handlerA custom handler for translating the native representation of the fields
opt_typeOption type
flagsOption type specific flags
no_docField should not be documented
aliasInterpret and apply field value only
argc
Return values
0success
-1failure

Definition at line 1192 of file sorcery.c.

1194{
1196 RAII_VAR(struct ast_sorcery_object_field *, object_field, NULL, ao2_cleanup);
1197 int pos;
1198 va_list args;
1199
1200 if (!strcmp(type, "id") || !object_type || !object_type->type.item_alloc) {
1201 return -1;
1202 }
1203
1204 if (!sorcery_handler) {
1205 sorcery_handler = sorcery_field_default_handler(opt_type);
1206 }
1207
1208 if (!(object_field = ao2_alloc(sizeof(*object_field) + argc * sizeof(object_field->args[0]), NULL))) {
1209 return -1;
1210 }
1211
1212 ast_copy_string(object_field->name, name, sizeof(object_field->name));
1213 object_field->handler = sorcery_handler;
1214 object_field->multiple_handler = multiple_handler;
1215
1216 va_start(args, argc);
1217 for (pos = 0; pos < argc; pos++) {
1218 object_field->args[pos] = va_arg(args, size_t);
1219 }
1220 va_end(args);
1221
1222 if (!alias) {
1223 ao2_link(object_type->fields, object_field);
1224 }
1225
1226 /* TODO: Improve this hack */
1227 if (!argc) {
1228 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc);
1229 } else if (argc == 1) {
1230 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
1231 object_field->args[0]);
1232 } else if (argc == 2) {
1233 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
1234 object_field->args[0], object_field->args[1]);
1235 } else if (argc == 3) {
1236 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
1237 object_field->args[0], object_field->args[1], object_field->args[2]);
1238 } else {
1239 ast_assert(0); /* The hack... she does us no good for this */
1240 }
1241
1242 return 0;
1243}
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:409
@ ACO_EXACT
int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types, const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc,...)
register a config option
static sorcery_field_handler sorcery_field_default_handler(enum aco_option_type type)
Definition: sorcery.c:341
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
Structure for registered object field.
Definition: sorcery.c:205
const char * args
#define ast_assert(a)
Definition: utils.h:739

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

◆ __ast_sorcery_object_register()

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

Register an object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
hiddenAll objects of this type are internal and should not be manipulated by users
reloadableAll objects of this type are reloadable
allocRequired object allocation callback
transformOptional transformation callback
applyOptional 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
0success
-1failure

Definition at line 1080 of file sorcery.c.

1081{
1083
1084 if (!object_type || object_type->type.item_alloc) {
1085 return -1;
1086 }
1087
1088 object_type->type.name = object_type->name;
1089 object_type->type.type = ACO_ITEM;
1090 object_type->type.category = ".?";
1091 object_type->type.item_alloc = alloc;
1092 object_type->type.hidden = hidden;
1093
1094 object_type->reloadable = reloadable;
1095 object_type->transform = transform;
1096 object_type->apply = apply;
1097 object_type->file->types[0] = &object_type->type;
1098 object_type->file->types[1] = NULL;
1099
1100 if (aco_info_init(object_type->info)) {
1101 return -1;
1102 }
1103
1105 return -1;
1106 }
1107
1108 NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, object_type_registered,
1110
1111 return 0;
1112}
int aco_info_init(struct aco_info *info)
Initialize an aco_info structure.
@ ACO_ITEM
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.
Definition: sorcery.c:1160
static int sorcery_extended_fields_handler(const void *obj, struct ast_variable **fields)
Definition: sorcery.c:1048
#define NOTIFY_INSTANCE_OBSERVERS(container, callback,...)
Definition: sorcery.c:79
static int sorcery_extended_config_handler(const struct aco_option *opt, struct ast_variable *var, void *obj)
Definition: sorcery.c:1043
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
struct ao2_container * observers
Observers.
Definition: sorcery.c:235

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

◆ __ast_sorcery_object_type_insert_wizard()

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

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

Since
13.26.0
16.3.0
Parameters
sorceryPointer to a sorcery structure
object_type_nameName of the object type to apply to
moduleThe name of the module, typically AST_MODULE
wizard_type_nameName of the wizard type to use
wizard_argsOpaque string to be passed to the wizard May be NULL but see note below
flagsOne or more of enum ast_sorcery_wizard_apply_flags
positionAn index to insert to or one of ast_sorcery_wizard_position
[out]wizardA variable to receive a pointer to the ast_sorcery_wizard structure. May be NULL if not needed.
[out]wizard_dataA 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.

873{
874 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, object_type_name, OBJ_KEY), ao2_cleanup);
875 RAII_VAR(struct ast_sorcery_internal_wizard *, internal_wizard, ao2_find(wizards, wizard_type_name, OBJ_KEY), ao2_cleanup);
876 RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, NULL, ao2_cleanup);
877 int created = 0;
878
879 object_wizard = ao2_alloc(sizeof(*object_wizard)
880 + (ast_strlen_zero(wizard_args) ? 0 : strlen(wizard_args) + 1),
882
883 if (!object_wizard) {
885 }
886
887 if (!internal_wizard
888 || internal_wizard->callbacks.module != ast_module_running_ref(internal_wizard->callbacks.module)) {
890 "Wizard '%s' could not be applied to object type '%s' as it was not found\n",
891 wizard_type_name, object_type_name);
893 }
894
895 if (!object_type) {
896 if (!(object_type = sorcery_object_type_alloc(object_type_name, module))) {
897 ast_module_unref(internal_wizard->callbacks.module);
899 }
900 created = 1;
901 }
902
903 AST_VECTOR_RW_WRLOCK(&object_type->wizards);
904 if (!created) {
905 struct ast_sorcery_object_wizard *found;
906
907#define WIZARD_COMPARE(a, b) ((a)->wizard == (b))
908 found = AST_VECTOR_GET_CMP(&object_type->wizards, internal_wizard, WIZARD_COMPARE);
909#undef WIZARD_COMPARE
910 if (found
912 ast_debug(1, "Wizard %s already applied to object type %s\n",
913 internal_wizard->callbacks.name, object_type->name);
914 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
915 ast_module_unref(internal_wizard->callbacks.module);
917 }
918 }
919
920 ast_debug(5, "Calling wizard %s open callback on object type %s\n",
921 wizard_type_name, object_type->name);
922 if (internal_wizard->callbacks.open && !(object_wizard->data = internal_wizard->callbacks.open(wizard_args))) {
923 ast_log(LOG_WARNING, "Wizard '%s' failed to open mapping for object type '%s' with data: %s\n",
924 wizard_type_name, object_type->name, S_OR(wizard_args, ""));
925 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
926 ast_module_unref(internal_wizard->callbacks.module);
928 }
929
930 object_wizard->wizard = ao2_bump(internal_wizard);
931 object_wizard->caching = !!(flags & AST_SORCERY_WIZARD_APPLY_CACHING);
932 object_wizard->read_only = !!(flags & AST_SORCERY_WIZARD_APPLY_READONLY);
933 if (wizard_args) {
934 strcpy(object_wizard->wizard_args, wizard_args); /* Safe */
935 }
936
937 if (position == AST_SORCERY_WIZARD_POSITION_LAST) {
938 position = AST_VECTOR_SIZE(&object_type->wizards);
939 }
940
941 if (AST_VECTOR_INSERT_AT(&object_type->wizards, position, object_wizard) != 0) {
942 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
944 }
945 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
946 ao2_bump(object_wizard);
947
948 if (created) {
949 ao2_link(sorcery->types, object_type);
950 }
951
953 sorcery->module_name, sorcery, object_type_name, &internal_wizard->callbacks, wizard_args,
954 object_wizard->data);
955
956 if (wizard) {
957 *wizard = &internal_wizard->callbacks;
958 }
959 if (wizard_data) {
960 *wizard_data = object_wizard->data;
961 }
962
964}
#define ast_log
Definition: astobj2.c:42
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
#define ast_debug(level,...)
Log a DEBUG message.
#define LOG_ERROR
#define LOG_WARNING
#define ast_module_unref(mod)
Release a reference to the module.
Definition: module.h:483
#define ast_module_running_ref(mod)
Hold a reference to the module if it is running.
Definition: module.h:469
#define WIZARD_COMPARE(a, b)
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257
static struct ast_sorcery_object_type * sorcery_object_type_alloc(const char *type, const char *module)
Internal function which allocates an object type structure.
Definition: sorcery.c:700
static void sorcery_object_wizard_destructor(void *obj)
Object wizard destructor.
Definition: sorcery.c:762
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one.
Definition: strings.h:80
Structure for an internal wizard instance.
Definition: sorcery.c:89
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
unsigned int allow_duplicates
Wizard allows others of the same type.
Definition: sorcery.c:117
char wizard_args[0]
Wizard arguments.
Definition: sorcery.c:120
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
#define AST_VECTOR_INSERT_AT(vec, idx, elem)
Insert an element at a specific position in a vector, growing the vector if needed.
Definition: vector.h:338
#define AST_VECTOR_RW_WRLOCK(vec)
Obtain write lock on vector.
Definition: vector.h:887
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define AST_VECTOR_GET_CMP(vec, value, cmp)
Get an element from a vector that matches the given comparison.
Definition: vector.h:731

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

Referenced by __ast_sorcery_insert_wizard_mapping().

◆ __ast_sorcery_object_type_remove_wizard()

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

Remove an object wizard mapping.

Since
13.26.0
16.3.0
Parameters
sorceryPointer to a sorcery structure
object_type_nameName of the object type to remove from
moduleThe name of the module, typically AST_MODULE
wizard_type_nameThe name of the of the wizard type to remove
wizard_argsOpaque string originally passed to the wizard
Return values
0success
-1failure
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.

823{
824 RAII_VAR(struct ast_sorcery_object_type *, object_type,
825 ao2_find(sorcery->types, object_type_name, OBJ_SEARCH_KEY), ao2_cleanup);
826 int res = -1;
827 int i;
828
829 if (!object_type) {
830 return res;
831 }
832
833 AST_VECTOR_RW_WRLOCK(&object_type->wizards);
834 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
835 struct ast_sorcery_object_wizard *wizard = AST_VECTOR_GET(&object_type->wizards, i);
836
837 if (strcmp(wizard->wizard->callbacks.name, wizard_type_name) == 0
838 && strcmp(S_OR(wizard->wizard_args, ""), S_OR(wizard_args, "")) == 0) {
839 ao2_cleanup(AST_VECTOR_REMOVE_ORDERED(&object_type->wizards, i));
840 res = 0;
841 break;
842 }
843 }
844 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
845
846 return res;
847}
@ OBJ_SEARCH_KEY
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
const char * name
Name of the wizard.
Definition: sorcery.h:278
#define AST_VECTOR_REMOVE_ORDERED(vec, idx)
Remove an element from a vector by index while maintaining order.
Definition: vector.h:448
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680

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

◆ __ast_sorcery_open()

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

Definition at line 601 of file sorcery.c.

602{
603 struct sorcery_proxy *proxy;
604 struct ast_sorcery *sorcery;
605
607
610 __PRETTY_FUNCTION__, file, line, func);
611 if (sorcery) {
613
614 return sorcery;
615 }
616
617 proxy = ao2_t_weakproxy_alloc(sizeof(*proxy) + strlen(module_name) + 1, NULL, module_name);
618 if (!proxy) {
619 goto failure_cleanup;
620 }
621 strcpy(proxy->module_name, module_name); /* Safe */
622
624 if (!sorcery) {
625 goto failure_cleanup;
626 }
627
629
630 /* We have exclusive access to proxy and sorcery, no need for locking here. */
631 if (ao2_t_weakproxy_set_object(proxy, sorcery, OBJ_NOLOCK, "weakproxy link")) {
632 goto failure_cleanup;
633 }
634
636 goto failure_cleanup;
637 }
638
640 ast_sorcery_object_type_hash_fn, NULL, ast_sorcery_object_type_cmp_fn);
641 if (!sorcery->types) {
642 goto failure_cleanup;
643 }
644
646 goto failure_cleanup;
647 }
648
650 ast_log(LOG_ERROR, "Error attempting to apply configuration %s to sorcery.\n", module_name);
651 goto failure_cleanup;
652 }
653
655 ao2_ref(proxy, -1);
656
658
660 return sorcery;
661
662failure_cleanup:
663 /* cleanup of sorcery may result in locking instances, so make sure we unlock first. */
666 ao2_cleanup(proxy);
667
668 return NULL;
669}
int ao2_weakproxy_subscribe(void *weakproxy, ao2_weakproxy_notification_cb cb, void *data, int flags)
Request notification when weakproxy points to NULL.
Definition: astobj2.c:934
@ AO2_ALLOC_OPT_LOCK_RWLOCK
Definition: astobj2.h:365
@ AO2_ALLOC_OPT_LOCK_MUTEX
Definition: astobj2.h:363
#define ao2_wrlock(a)
Definition: astobj2.h:719
#define ao2_link_flags(container, obj, flags)
Add an object to a container.
Definition: astobj2.h:1554
#define ao2_t_weakproxy_alloc(data_size, destructor_fn, tag)
Definition: astobj2.h:553
#define ao2_unlock(a)
Definition: astobj2.h:729
void * __ao2_weakproxy_find(struct ao2_container *c, const void *arg, enum search_flags flags, const char *tag, const char *file, int line, const char *func)
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
@ OBJ_NOLOCK
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
void * __ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn, unsigned int options, const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result
Definition: astobj2.c:768
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
#define ao2_t_weakproxy_set_object(weakproxy, obj, flags, tag)
Definition: astobj2.h:582
#define NOTIFY_GLOBAL_OBSERVERS(container, callback,...)
Definition: sorcery.c:76
static void sorcery_destructor(void *obj)
Destructor called when sorcery structure is destroyed.
Definition: sorcery.c:581
static void sorcery_proxy_cb(void *weakproxy, void *data)
Hashing function for sorcery types.
Definition: sorcery.c:596
enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module)
Apply configured wizard mappings.
Definition: sorcery.c:985
static struct ao2_container * instances
Registered sorcery instances.
Definition: sorcery.c:284
struct ao2_container * observers
Registered global observers.
Definition: sorcery.c:281
#define TYPE_BUCKETS
Number of buckets for types (should be prime for performance reasons)
Definition: sorcery.c:54
Full structure for sorcery.
Definition: sorcery.c:230
Proxy object for sorcery.
Definition: sorcery.c:223
char module_name[0]
The name of the module owning this sorcery instance.
Definition: sorcery.c:226

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

◆ __ast_sorcery_remove_wizard_mapping()

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

Remove an object wizard mapping.

Parameters
sorceryPointer to a sorcery structure
typeType of object to remove from
moduleThe name of the module, typically AST_MODULE
nameThe name of the wizard to remove
Return values
0success
-1failure
Since
13.4.0

Remove an object wizard mapping.

Definition at line 850 of file sorcery.c.

852{
854 int res;
855
856 if (!object_type) {
857 return -1;
858 }
859
860 AST_VECTOR_RW_WRLOCK(&object_type->wizards);
861#define WIZARD_NAME_COMPARE(a, b) (strcmp((a)->wizard->callbacks.name, (b)) == 0)
863#undef WIZARD_NAME_COMPARE
864 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
865
866 return res;
867}
#define WIZARD_NAME_COMPARE(a, b)
#define AST_VECTOR_REMOVE_CMP_ORDERED(vec, value, cmp, cleanup)
Remove an element from a vector that matches the given comparison while maintaining order.
Definition: vector.h:540

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

◆ __ast_sorcery_wizard_register()

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

Register a sorcery wizard.

Parameters
interfacePointer to a wizard interface
modulePointer to the module implementing the interface
Return values
0success
-1failure

Definition at line 432 of file sorcery.c.

433{
434 struct ast_sorcery_internal_wizard *wizard;
435 int res = -1;
436
437 ast_assert(!ast_strlen_zero(interface->name));
438
440
441 if ((wizard = ao2_find(wizards, interface->name, OBJ_KEY | OBJ_NOLOCK))) {
442 ast_log(LOG_WARNING, "Attempted to register sorcery wizard '%s' twice\n",
443 interface->name);
444 goto done;
445 }
446
447 if (!(wizard = ao2_alloc(sizeof(*wizard), sorcery_internal_wizard_destructor))) {
448 goto done;
449 }
450
451 wizard->callbacks = *interface;
452 wizard->callbacks.module = module;
453
455 if (!wizard->observers) {
456 goto done;
457 }
458
460 res = 0;
461
462 ast_verb(5, "Sorcery registered wizard '%s'\n", interface->name);
463
464 NOTIFY_GLOBAL_OBSERVERS(observers, wizard_registered,
465 interface->name, interface);
466
467done:
468 ao2_cleanup(wizard);
470
471 return res;
472}
#define ao2_lock(a)
Definition: astobj2.h:717
#define ast_verb(level,...)
static void sorcery_internal_wizard_destructor(void *obj)
Definition: sorcery.c:425
struct ao2_container * observers
Observers.
Definition: sorcery.c:99
struct ast_module * module
Pointer to the Asterisk module this wizard is implemented by.
Definition: sorcery.h:281
int done
Definition: test_amihooks.c:48

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, observers, sorcery_internal_wizard_destructor(), and wizards.

Referenced by ast_bucket_init().

◆ ast_sorcery_alloc()

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

Allocate an object.

Parameters
sorceryPointer to a sorcery structure
typeType of object to allocate
idOptional unique identifier, if none is provided one will be generated
Return values
non-NULLsuccess
NULLfailure

Definition at line 1744 of file sorcery.c.

1745{
1747 struct ast_sorcery_object_details *details;
1748
1749 if (!object_type || !object_type->type.item_alloc ||
1750 !(details = object_type->type.item_alloc(id))) {
1751 return NULL;
1752 }
1753
1754 if (ast_strlen_zero(id)) {
1755 char uuid[AST_UUID_STR_LEN];
1756
1757 ast_uuid_generate_str(uuid, sizeof(uuid));
1758 details->object->id = ast_strdup(uuid);
1759 } else {
1760 details->object->id = ast_strdup(id);
1761 }
1762 if (!details->object->id) {
1763 ao2_ref(details, -1);
1764 return NULL;
1765 }
1766
1767 details->object->created = ast_tvnow();
1768 ast_copy_string(details->object->type, type, sizeof(details->object->type));
1769
1770 if (aco_set_defaults(&object_type->type, id, details)) {
1771 ao2_ref(details, -1);
1772 return NULL;
1773 }
1774
1775 return details;
1776}
int aco_set_defaults(struct aco_type *type, const char *category, void *obj)
Set all default options of obj.
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
struct timeval created
Time that the object was created.
Definition: sorcery.c:141
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
char * id
Unique identifier of this object.
Definition: sorcery.c:129
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159
#define AST_UUID_STR_LEN
Definition: uuid.h:27
char * ast_uuid_generate_str(char *buf, size_t size)
Generate a UUID string.
Definition: uuid.c:141

References aco_set_defaults(), ao2_cleanup, ao2_find, ao2_ref, ast_copy_string(), ast_strdup, ast_strlen_zero(), ast_tvnow(), ast_uuid_generate_str(), AST_UUID_STR_LEN, ast_sorcery_object::created, ast_sorcery_object::id, NULL, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, sorcery, type, ast_sorcery_object::type, 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_effective_profile(), create_object(), default_profile_create(), global_loaded_observer(), load_module(), mock_retrieve_id(), permanent_uri_handler(), sip_cli_print_global(), sip_cli_print_system(), sorcery_astdb_retrieve_fields_common(), sorcery_astdb_retrieve_id(), sorcery_astdb_retrieve_prefix(), sorcery_astdb_retrieve_regex(), sorcery_config_internal_load(), sorcery_memory_cache_thrash_update(), sorcery_realtime_retrieve_fields(), sorcery_realtime_retrieve_multiple(), sorcery_test_retrieve_id(), and subscription_persistence_create().

◆ ast_sorcery_changeset_create()

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

Create a changeset given two object sets.

Parameters
originalOriginal object set
modifiedModified object set
changesPointer to hold any changes between the object sets
Return values
0success
-1failure
Note
The returned ast_variable list must be destroyed using ast_variables_destroy

Definition at line 1663 of file sorcery.c.

1664{
1665 const struct ast_variable *field;
1666 int res = 0;
1667
1668 *changes = NULL;
1669
1670 /* Unless the ast_variable list changes when examined... it can't differ from itself */
1671 if (original == modified) {
1672 return 0;
1673 }
1674
1675 for (field = modified; field; field = field->next) {
1676 const char *old_value = ast_variable_find_in_list(original, field->name);
1677
1678 if (!old_value || strcmp(old_value, field->value)) {
1679 struct ast_variable *tmp;
1680
1681 if (!(tmp = ast_variable_new(field->name, field->value, ""))) {
1682 res = -1;
1683 break;
1684 }
1685
1686 tmp->next = *changes;
1687 *changes = tmp;
1688 }
1689 }
1690
1691 /* If an error occurred do not return a partial changeset */
1692 if (res) {
1693 ast_variables_destroy(*changes);
1694 *changes = NULL;
1695 }
1696
1697 return res;
1698}
static int tmp()
Definition: bt_open.c:389
const char * ast_variable_find_in_list(const struct ast_variable *list, const char *variable)
Gets the value of a variable from a variable list by name.
Definition: main/config.c:919
#define ast_variable_new(name, value, filename)
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262

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

◆ ast_sorcery_copy()

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

Create a copy of an object.

Parameters
sorceryPointer to a sorcery structure
objectExisting object
Return values
non-NULLsuccess
NULLfailure

Definition at line 1778 of file sorcery.c.

1779{
1780 const struct ast_sorcery_object_details *details = object;
1781 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
1783 RAII_VAR(struct ast_variable *, objectset, NULL, ast_variables_destroy);
1784 int res = 0;
1785
1786 if (!copy) {
1787 return NULL;
1788 } else if (object_type->copy) {
1789 res = object_type->copy(object, copy);
1790 } else if ((objectset = ast_sorcery_objectset_create(sorcery, object))) {
1791 res = ast_sorcery_objectset_apply(sorcery, copy, objectset);
1792 } else {
1793 /* No native copy available and could not create an objectset, this copy has failed */
1794 res = -1;
1795 }
1796
1797 if (res) {
1799 copy = NULL;
1800 }
1801
1802 return copy;
1803}
static int copy(char *infile, char *outfile)
Utility function to copy a file.
void * ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id)
Allocate an object.
Definition: sorcery.c:1744
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.
Definition: sorcery.c:1632
#define ast_sorcery_objectset_create(sorcery, object)
Create an object set (KVP list) for an object.
Definition: sorcery.h:1137

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

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

◆ 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
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
Return values
0success
-1failure

Definition at line 2062 of file sorcery.c.

2063{
2064 const struct ast_sorcery_object_details *details = object;
2065 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
2066 struct ast_sorcery_object_wizard *object_wizard = NULL;
2067 struct ast_sorcery_object_wizard *found_wizard;
2068 int i;
2069 struct sorcery_details sdetails = {
2070 .sorcery = sorcery,
2071 .obj = object,
2072 };
2073
2074 if (!object_type) {
2075 return -1;
2076 }
2077
2078 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
2079 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2080 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2081 if (!found_wizard->caching
2082 && sorcery_wizard_create(found_wizard, &sdetails) == CMP_MATCH) {
2083 object_wizard = found_wizard;
2084 }
2085 }
2086
2087 if (object_wizard) {
2088 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2089 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2090 if (found_wizard->caching) {
2091 sorcery_wizard_create(found_wizard, &sdetails);
2092 }
2093 }
2094
2095 if (ao2_container_count(object_type->observers)) {
2096 struct sorcery_observer_invocation *invocation;
2097
2098 invocation = sorcery_observer_invocation_alloc(object_type, object);
2099 if (invocation
2101 invocation)) {
2102 ao2_cleanup(invocation);
2103 }
2104 }
2105 }
2106
2108
2109 return object_wizard ? 0 : -1;
2110}
@ CMP_MATCH
Definition: astobj2.h:1027
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
static int sorcery_observers_notify_create(void *data)
Internal callback function which notifies observers that an object has been created.
Definition: sorcery.c:2052
static int sorcery_wizard_create(const struct ast_sorcery_object_wizard *object_wizard, const struct sorcery_details *details)
Internal function which returns if the wizard has created the object.
Definition: sorcery.c:2025
static struct sorcery_observer_invocation * sorcery_observer_invocation_alloc(struct ast_sorcery_object_type *object_type, void *object)
Allocator function for observer invocation.
Definition: sorcery.c:1292
struct ast_sorcery_object_wizards wizards
Wizard instances.
Definition: sorcery.c:165
struct ast_taskprocessor * serializer
Serializer for observers.
Definition: sorcery.c:183
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
Structure used when calling create, update, or delete.
Definition: sorcery.c:1831
const struct ast_sorcery * sorcery
Pointer to the sorcery instance.
Definition: sorcery.c:1833
Structure used for observer invocations.
Definition: sorcery.c:196
struct ast_sorcery_object_type * object_type
Pointer to the object type.
Definition: sorcery.c:198
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int(*task_exe)(void *datap), void *datap) attribute_warn_unused_result
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877

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

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

◆ ast_sorcery_delete()

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

Delete an object.

Parameters
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
Return values
0success
-1failure

Definition at line 2238 of file sorcery.c.

2239{
2240 const struct ast_sorcery_object_details *details = object;
2241 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
2242 struct ast_sorcery_object_wizard *object_wizard = NULL;
2243 struct ast_sorcery_object_wizard *found_wizard;
2244 int i;
2245 struct sorcery_details sdetails = {
2246 .sorcery = sorcery,
2247 .obj = object,
2248 };
2249
2250 if (!object_type) {
2251 return -1;
2252 }
2253
2254 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
2255 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2256 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2257 if (!found_wizard->caching
2258 && sorcery_wizard_delete(found_wizard, &sdetails) == CMP_MATCH) {
2259 object_wizard = found_wizard;
2260 }
2261 }
2262
2263 if (object_wizard) {
2264 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2265 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2266 if (found_wizard->caching) {
2267 sorcery_wizard_delete(found_wizard, &sdetails);
2268 }
2269 }
2270
2271 if (ao2_container_count(object_type->observers)) {
2272 struct sorcery_observer_invocation *invocation;
2273
2274 invocation = sorcery_observer_invocation_alloc(object_type, object);
2275 if (invocation
2277 invocation)) {
2278 ao2_cleanup(invocation);
2279 }
2280 }
2281 }
2282
2284
2285 return object_wizard ? 0 : -1;
2286}
static int sorcery_observers_notify_delete(void *data)
Internal callback function which notifies observers that an object has been deleted.
Definition: sorcery.c:2213
static int sorcery_wizard_delete(const struct ast_sorcery_object_wizard *object_wizard, const struct sorcery_details *details)
Internal function which returns if a wizard has deleted the object.
Definition: sorcery.c:2224

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

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

◆ ast_sorcery_diff()

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

Create a changeset of two objects.

Parameters
sorceryPointer to a sorcery structure
originalOriginal object
modifiedModified object
changesPointer which will be populated with changes if any exist
Return values
0success
-1failure
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.

1806{
1808
1809 *changes = NULL;
1810
1811 if (strcmp(ast_sorcery_object_get_type(original), ast_sorcery_object_get_type(modified))) {
1812 return -1;
1813 }
1814
1815 if (original == modified) {
1816 return 0;
1817 } else if (!object_type->diff) {
1818 RAII_VAR(struct ast_variable *, objectset1, NULL, ast_variables_destroy);
1819 RAII_VAR(struct ast_variable *, objectset2, NULL, ast_variables_destroy);
1820
1821 objectset1 = ast_sorcery_objectset_create(sorcery, original);
1822 objectset2 = ast_sorcery_objectset_create(sorcery, modified);
1823
1824 return ast_sorcery_changeset_create(objectset1, objectset2, changes);
1825 } else {
1826 return object_type->diff(original, modified, changes);
1827 }
1828}
const char * ast_sorcery_object_get_type(const void *object)
Get the type of a sorcery object.
Definition: sorcery.c:2329
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.
Definition: sorcery.c:1663

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

Referenced by AST_TEST_DEFINE(), and transport_apply().

◆ ast_sorcery_force_reload()

void ast_sorcery_force_reload ( const struct ast_sorcery sorcery)

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

Parameters
sorceryPointer to a sorcery structure
Since
13.32.0
16.9.0
17.3.0

Definition at line 1425 of file sorcery.c.

1426{
1427 struct sorcery_load_details details = {
1428 .sorcery = sorcery,
1429 .reload = 1,
1430 .force = 1,
1431 };
1432
1433 NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
1435
1437
1440}
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container,...
Definition: astobj2.h:1693
@ OBJ_NODATA
Definition: astobj2.h:1044
static int sorcery_object_load(void *obj, void *arg, int flags)
Definition: sorcery.c:1336
Structure for passing load/reload details.
Definition: sorcery.c:242
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244

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

◆ ast_sorcery_force_reload_object()

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

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

Parameters
sorceryPointer to a sorcery structure
typeName of the object type to reload
Since
13.32.0
16.9.0
17.3.0

Definition at line 1457 of file sorcery.c.

1458{
1460 struct sorcery_load_details details = {
1461 .sorcery = sorcery,
1462 .reload = 1,
1463 .force = 1,
1464 };
1465
1466 if (!object_type) {
1467 return;
1468 }
1469
1470 sorcery_object_load(object_type, &details, 0);
1471}

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

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

◆ ast_sorcery_generic_alloc()

void * ast_sorcery_generic_alloc ( size_t  size,
ao2_destructor_fn  destructor 
)

Allocate a generic sorcery capable object.

Parameters
sizeSize of the object
destructorOptional destructor function
Return values
non-NULLsuccess
NULLfailure
Note
The returned object does not support AO2 locking.

Definition at line 1728 of file sorcery.c.

1729{
1730 void *object = ao2_alloc_options(size + sizeof(struct ast_sorcery_object),
1732 struct ast_sorcery_object_details *details = object;
1733
1734 if (!object) {
1735 return NULL;
1736 }
1737
1738 details->object = object + size;
1739 details->object->destructor = destructor;
1740
1741 return object;
1742}
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
#define ao2_alloc_options(data_size, destructor_fn, options)
Definition: astobj2.h:404
static void sorcery_object_destructor(void *object)
Definition: sorcery.c:1700
Structure for internal sorcery object information.
Definition: sorcery.c:127
ao2_destructor_fn destructor
Optional object destructor.
Definition: sorcery.c:135

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

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

◆ ast_sorcery_get_module()

const char * ast_sorcery_get_module ( const struct ast_sorcery sorcery)

Get the module that has opened the provided sorcery instance.

Parameters
sorceryThe sorcery instance
Returns
The module

Definition at line 2536 of file sorcery.c.

2537{
2538 return sorcery->module_name;
2539}

References ast_sorcery::module_name, and sorcery.

Referenced by sorcery_memory_cache_load().

◆ ast_sorcery_get_object_type()

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

Get the sorcery object type given a type name.

Parameters
sorceryThe sorcery from which to retrieve the object type
typeThe type name

Definition at line 2494 of file sorcery.c.

2496{
2498}

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

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

◆ ast_sorcery_get_wizard_mapping()

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

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

Parameters
sorceryPointer to a sorcery structure
typeType of object
indexIndex of the wizard
wizardA pointer to receive the wizard pointer
dataA pointer to receive the data pointer
Return values
0success
-1failure
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.

792{
794 struct ast_sorcery_object_wizard *owizard;
795
796 if (!object_type) {
797 return -1;
798 }
799
800 if (index < 0 || index >= AST_VECTOR_SIZE(&object_type->wizards)) {
801 return -1;
802 }
803
804 owizard = AST_VECTOR_GET(&object_type->wizards, index);
805
806 if (wizard != NULL) {
807 *wizard = &(owizard->wizard->callbacks);
808 ao2_bump(owizard->wizard);
809 } else {
810 return -1;
811 }
812
813 if (data != NULL) {
814 *data = owizard->data;
815 }
816
817 return 0;
818}
void * data
Unique data for the wizard.
Definition: sorcery.c:108

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

Referenced by AST_TEST_DEFINE().

◆ ast_sorcery_get_wizard_mapping_count()

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

Return the number of wizards mapped to an object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
Returns
Number of wizards or -1 for error
Since
13.4.0

Definition at line 778 of file sorcery.c.

780{
782
783 if (!object_type) {
784 return -1;
785 }
786
787 return AST_VECTOR_SIZE(&object_type->wizards);
788}

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

Referenced by AST_TEST_DEFINE().

◆ ast_sorcery_global_observer_add()

int ast_sorcery_global_observer_add ( const struct ast_sorcery_global_observer callbacks)

Add a global observer to sorcery.

Parameters
callbacksImplementation of the global observer interface
Return values
0success
-1failure
Note
You must be ready to accept observer invocations before this function is called

Definition at line 498 of file sorcery.c.

499{
500 struct sorcery_global_observer *cb;
501
502 cb = ao2_alloc(sizeof(*cb), NULL);
503 if (!cb) {
504 return -1;
505 }
506
507 cb->callbacks = callbacks;
508 ao2_link(observers, cb);
509 ao2_ref(cb, -1);
510
511 return 0;
512}
struct @468 callbacks
A global observer wrapper.
Definition: sorcery.c:266
const struct ast_sorcery_global_observer * callbacks
Definition: sorcery.c:267

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

Referenced by AST_TEST_DEFINE(), and load_module().

◆ ast_sorcery_global_observer_remove()

void ast_sorcery_global_observer_remove ( const struct ast_sorcery_global_observer callbacks)

Remove a global observer from sorcery.

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

Parameters
callbacksImplementation of the global observer interface

Definition at line 514 of file sorcery.c.

516{
518}
@ OBJ_UNLINK
Definition: astobj2.h:1039
static int sorcery_generic_observer_remove(void *obj, void *arg, int flags)
Internal callback function for removing a generic observer.
Definition: sorcery.c:491

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

Referenced by AST_TEST_DEFINE(), and unload_module().

◆ ast_sorcery_init()

int ast_sorcery_init ( void  )

Initialize the sorcery API.

Return values
0success
-1failure

Initialize the sorcery API.

Hashing function for sorcery instances

Definition at line 387 of file sorcery.c.

388{
391 .auto_increment = 1,
392 .max_size = 0,
393 .idle_timeout = 60,
394 .initial_size = 0,
395 };
397
399 if (!threadpool) {
400 return -1;
401 }
402
404 ast_sorcery_internal_wizard_hash_fn, NULL, ast_sorcery_internal_wizard_cmp_fn);
405 if (!wizards) {
406 return -1;
407 }
408
410 if (!observers) {
411 return -1;
412 }
413
415 sorcery_proxy_hash_fn, NULL, sorcery_proxy_cmp_fn);
416 if (!instances) {
417 return -1;
418 }
419
421
422 return 0;
423}
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
#define INSTANCE_BUCKETS
Number of buckets for instances (should be prime for performance reasons)
Definition: sorcery.c:57
#define WIZARD_BUCKETS
Number of buckets for wizards (should be prime for performance reasons)
Definition: sorcery.c:51
static struct ast_threadpool * threadpool
Thread pool for observers.
Definition: sorcery.c:86
static void sorcery_cleanup(void)
Hashing and comparison functions for sorcery wizards.
Definition: sorcery.c:369
struct ast_threadpool * ast_threadpool_create(const char *name, struct ast_threadpool_listener *listener, const struct ast_threadpool_options *options)
Create a new threadpool.
Definition: threadpool.c:916
#define AST_THREADPOOL_OPTIONS_VERSION
Definition: threadpool.h:71

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, instances, NULL, observers, options, sorcery_cleanup(), threadpool, WIZARD_BUCKETS, and wizards.

Referenced by asterisk_daemon().

◆ ast_sorcery_instance_observer_add()

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

Add an observer to a sorcery instance.

Parameters
sorceryPointer to a sorcery structure
callbacksImplementation 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
0success
-1failure
Note
You must be ready to accept observer invocations before this function is called

Definition at line 520 of file sorcery.c.

522{
523 struct sorcery_instance_observer *cb;
524
525 cb = ao2_alloc(sizeof(*cb), NULL);
526 if (!cb) {
527 return -1;
528 }
529
530 cb->callbacks = callbacks;
532 ao2_ref(cb, -1);
533
534 return 0;
535}
An instance observer wrapper.
Definition: sorcery.c:271
const struct ast_sorcery_instance_observer * callbacks
Definition: sorcery.c:272

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

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

◆ ast_sorcery_instance_observer_remove()

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

Remove an observer from a sorcery instance.

Parameters
sorceryPointer to a sorcery structure
callbacksImplementation of the instance observer interface

Definition at line 537 of file sorcery.c.

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

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

◆ ast_sorcery_is_object_field_registered()

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

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

Parameters
object_typeThe object type to check against
field_nameThe name of the field to check
Return values
0The field is not registered for this sorcery type
1The field is registered for this sorcery type

Definition at line 2514 of file sorcery.c.

2516{
2517 struct ast_sorcery_object_field *object_field;
2518 int res = 1;
2519
2520 ast_assert(object_type != NULL);
2521
2522 object_field = ao2_find(object_type->fields, field_name, OBJ_SEARCH_KEY);
2523
2524 if (!object_field) {
2525 object_field = ao2_callback(object_type->fields, 0, is_registered_cb, (char *)field_name);
2526 }
2527
2528 if (!object_field) {
2529 res = 0;
2530 }
2531
2532 ao2_cleanup(object_field);
2533 return res;
2534}
static int is_registered_cb(void *obj, void *arg, int flags)
Definition: sorcery.c:2500
struct ao2_container * fields
Object fields.
Definition: sorcery.c:168

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

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

◆ ast_sorcery_is_stale()

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

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

Since
14.0.0

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

Return values
0the object is not stale
1the object is stale

Definition at line 2288 of file sorcery.c.

2289{
2290 const struct ast_sorcery_object_details *details = object;
2291 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
2292 struct ast_sorcery_object_wizard *found_wizard;
2293 int res = 0;
2294 int i;
2295
2296 if (!object_type) {
2297 return -1;
2298 }
2299
2300 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
2301 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2302 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2303
2304 if (found_wizard->wizard->callbacks.is_stale) {
2305 res |= found_wizard->wizard->callbacks.is_stale(sorcery, found_wizard->data, object);
2306 ast_debug(5, "After calling wizard '%s', object '%s' is %s\n",
2307 found_wizard->wizard->callbacks.name,
2309 res ? "stale" : "not stale");
2310 }
2311 }
2312 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
2313
2314 return res;
2315}
const char * ast_sorcery_object_get_id(const void *object)
Get the unique identifier of a sorcery object.
Definition: sorcery.c:2317
int(* is_stale)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for whether or not the wizard believes the object is stale.
Definition: sorcery.h:325

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

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

◆ ast_sorcery_load()

void ast_sorcery_load ( const struct ast_sorcery sorcery)

Inform any wizards to load persistent objects.

Parameters
sorceryPointer to a sorcery structure

Definition at line 1377 of file sorcery.c.

1378{
1379 struct sorcery_load_details details = {
1380 .sorcery = sorcery,
1381 .reload = 0,
1382 };
1383
1384 NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
1386
1388
1391}

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

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

◆ ast_sorcery_load_object()

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

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

Parameters
sorceryPointer to a sorcery structure
typeName of the object type to load

Definition at line 1393 of file sorcery.c.

1394{
1396 struct sorcery_load_details details = {
1397 .sorcery = sorcery,
1398 .reload = 0,
1399 };
1400
1401 if (!object_type) {
1402 return;
1403 }
1404
1405 sorcery_object_load(object_type, &details, 0);
1406}

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

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

◆ ast_sorcery_lockable_alloc()

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

Allocate a generic sorcery capable object with locking.

Since
14.1.0

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

Parameters
sizeSize of the object
destructorOptional destructor function
lockobjAn AO2 object that will provide locking.
Return values
non-NULLsuccess
NULLfailure

Definition at line 1712 of file sorcery.c.

1713{
1714 void *object = ao2_alloc_with_lockobj(size + sizeof(struct ast_sorcery_object),
1715 sorcery_object_destructor, lockobj, "");
1716 struct ast_sorcery_object_details *details = object;
1717
1718 if (!object) {
1719 return NULL;
1720 }
1721
1722 details->object = object + size;
1723 details->object->destructor = destructor;
1724
1725 return object;
1726}
#define ao2_alloc_with_lockobj(data_size, destructor_fn, lockobj, tag)
Allocate and initialize an object with separate locking.
Definition: astobj2.h:431

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

Referenced by aor_alloc().

◆ ast_sorcery_object_fields_register()

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

Register a regex for multiple fields within an object.

Parameters
sorceryPointer to a sorcery structure
typeType of object
regexA regular expression pattern for the fields
config_handlerA custom handler for translating the string representation of the fields
sorcery_handlerA custom handler for translating the native representation of the fields
Return values
0success
-1failure

Definition at line 1160 of file sorcery.c.

1161{
1162#define MAX_REGEX_ERROR_LEN 128
1164 RAII_VAR(struct ast_sorcery_object_field *, object_field, NULL, ao2_cleanup);
1165 int rc;
1166
1167 if (!object_type || !object_type->type.item_alloc || !config_handler
1168 || !(object_field = ao2_alloc(sizeof(*object_field), sorcery_object_field_destructor))) {
1169 return -1;
1170 }
1171
1172 ast_copy_string(object_field->name, regex, sizeof(object_field->name));
1173 object_field->multiple_handler = sorcery_handler;
1174
1175 if (!(object_field->name_regex = ast_calloc(1, sizeof(regex_t)))) {
1176 return -1;
1177 }
1178
1179 if ((rc = regcomp(object_field->name_regex, regex, REG_EXTENDED | REG_NOSUB))) {
1180 char *regerr = ast_alloca(MAX_REGEX_ERROR_LEN);
1181 regerror(rc, object_field->name_regex, regerr, MAX_REGEX_ERROR_LEN);
1182 ast_log(LOG_ERROR, "Regular expression '%s' failed to compile: %s\n", regex, regerr);
1183 return -1;
1184 }
1185
1186 ao2_link(object_type->fields, object_field);
1187 __aco_option_register(object_type->info, regex, ACO_REGEX, object_type->file->types, "", OPT_CUSTOM_T, config_handler, 0, 1, 0);
1188
1189 return 0;
1190}
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: astmm.h:288
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
@ ACO_REGEX
@ OPT_CUSTOM_T
Type for a custom (user-defined) option handler.
static int regex(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
#define MAX_REGEX_ERROR_LEN
static void sorcery_object_field_destructor(void *obj)
Definition: sorcery.c:1150

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

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

◆ ast_sorcery_object_get_created()

const struct timeval ast_sorcery_object_get_created ( const void *  object)

Get when the sorcery object was created.

Since
14.0.0
Parameters
objectPointer to a sorcery object
Returns
The time when the object was created

Definition at line 2323 of file sorcery.c.

2324{
2325 const struct ast_sorcery_object_details *details = object;
2326 return details->object->created;
2327}

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

◆ ast_sorcery_object_get_extended()

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

Get an extended field value from a sorcery object.

Parameters
objectPointer to a sorcery object
nameName of the extended field value
Return values
non-NULLif found
NULLif 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 2335 of file sorcery.c.

2336{
2337 const struct ast_sorcery_object_details *details = object;
2338 struct ast_variable *field;
2339
2340 for (field = details->object->extended; field; field = field->next) {
2341 if (!strcmp(field->name + 1, name)) {
2342 return field->value;
2343 }
2344 }
2345
2346 return NULL;
2347}
struct ast_variable * extended
Extended object fields.
Definition: sorcery.c:138

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

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

◆ ast_sorcery_object_get_id()

const char * ast_sorcery_object_get_id ( const void *  object)

Get the unique identifier of a sorcery object.

Parameters
objectPointer to a sorcery object
Returns
unique identifier

Definition at line 2317 of file sorcery.c.

2318{
2319 const struct ast_sorcery_object_details *details = object;
2320 return details->object->id;
2321}

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

Referenced by __print_debug_details(), aeap_cli_show(), aeap_tab_complete_name(), allocate_subscription_tree(), allow_and_or_replace_unsolicited(), ami_outbound_registration_task(), ami_show_registration_contact_statuses(), anonymous_identify(), aor_deleted_observer(), apply_acls(), ast_bucket_file_json(), ast_bucket_json(), ast_geoloc_eprofile_create_from_profile(), ast_mwi_mailbox_get_id(), ast_mwi_mailbox_update(), ast_res_pjsip_find_or_create_contact_status(), ast_res_pjsip_initialize_configuration(), ast_sip_create_dialog_uac(), ast_sip_create_subscription(), ast_sip_for_each_contact(), ast_sip_format_contact_ami(), ast_sip_get_contact_status(), ast_sip_get_device_state(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_transport(), ast_sip_location_create_contact(), ast_sip_location_retrieve_aor_contacts_nolock_filtered(), ast_sip_session_alloc(), ast_sip_session_create_outgoing(), ast_sip_session_get_name(), ast_sip_set_tpselector_from_transport(), ast_sip_subscription_destroy(), ast_sorcery_is_stale(), ast_sorcery_object_id_hash(), ast_sorcery_object_id_sort(), AST_TEST_DEFINE(), asterisk_publication_devicestate(), asterisk_publication_devicestate_refresh(), asterisk_publication_devicestate_state_change(), asterisk_publication_mailboxstate(), asterisk_publication_mwi_refresh(), asterisk_publication_mwi_state_change(), attestation_apply(), auth_apply(), auth_observer(), bucket_file_run_curl(), bucket_http_test_wizard_create(), bucket_http_test_wizard_delete(), bucket_http_test_wizard_update(), build_resource_tree(), can_reuse_registration(), cancel_and_unpublish(), 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(), client_config_apply(), codec_prefs_handler(), common_identify(), config_object_cli_show(), config_object_tab_complete_name(), connected_line_method_handler(), contact_apply_handler(), contact_function_get_permanent(), create_dialog_uas(), create_effective_profile(), create_out_of_dialog_request(), create_outgoing_sdp_stream(), create_rtp(), create_unsolicited_mwi_subscriptions(), current_state_reusable(), destroy_subscription(), digest_check_auth(), digest_create_request_with_auth(), direct_media_glare_mitigation_handler(), direct_media_method_handler(), domain_alias_apply(), endpt_send_request(), eprofile_apply(), expire_objects_from_cache(), file_extension_from_url_path(), find_internal_state_by_transport(), find_or_create_temporary_state(), find_registrar_aor(), format_ami_aor_handler(), format_ami_auth_handler(), format_ami_endpoint_identify(), format_ami_endpoint_transport(), from_user_handler(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_location_apply_handler(), geoloc_profile_apply_handler(), get_account_id(), get_curl_instance(), get_resource_display_name(), handle_export_primitives(), handle_incoming_request(), handle_outgoing_request(), handle_slash(), has_mwi_subscription(), header_identify_match_check(), ident_handler(), internal_state_alloc(), ip_identify_apply(), ip_identify_match_check(), ip_identify_match_handler(), line_identify(), load_engine(), load_module(), log_caps(), mark_object_as_stale_in_cache(), matches_engine(), media_cache_handle_show_item(), media_cache_item_del_from_astdb(), media_cache_item_sync_to_astdb(), media_cache_prnt_summary(), memory_cache_stale_update_object(), msg_send(), mwi_contact_changed(), mwi_observe_delete(), mwi_post_event(), mwi_subscription_alloc(), mwi_validate_for_aor(), new_subscribe(), permanent_uri_handler(), permanent_uri_sort_fn(), persistent_endpoint_find_or_create(), pjsip_aor_function_read(), profile_apply(), publish_request_initial(), publisher_start(), publisher_stop(), pubsub_on_rx_mwi_notify_request(), pubsub_on_rx_publish_request(), pubsub_on_rx_refresh(), pubsub_on_rx_subscribe_request(), qualify_contact_cb(), read_pjsip(), redirect_handler(), refer_client_on_evsub_state(), refer_incoming_attended_request(), refer_incoming_blind_request(), refer_incoming_invite_request(), refer_incoming_refer_request(), refer_progress_alloc(), refer_send(), registrar_contact_delete(), registrar_on_rx_request(), registration_deleted_observer(), registration_state_cmp(), registration_state_hash(), remove_from_cache(), remove_subscription(), request_identify_match_check(), resource_list_apply_handler(), rfc3326_add_reason_header(), rx_data_to_ast_msg(), session_destructor(), session_inv_on_redirected(), session_inv_on_tsx_state_changed(), session_outgoing_nat_hook(), 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_handler(), subscription_established(), subscription_persistence_create(), subscription_persistence_remove(), subscription_tree_destructor(), t38_initialize_session(), tn_apply(), tos_handler(), transport_apply(), transport_tls_file_handler(), transport_tos_handler(), unload_engine(), update_devstate(), users_apply_handler(), validate_publish_config(), and verification_apply().

◆ ast_sorcery_object_get_type()

const char * ast_sorcery_object_get_type ( const void *  object)

Get the type of a sorcery object.

Parameters
objectPointer to a sorcery object
Returns
type of object

Definition at line 2329 of file sorcery.c.

2330{
2331 const struct ast_sorcery_object_details *details = object;
2332 return details->object->type;
2333}

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

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

◆ ast_sorcery_object_has_dynamic_contents()

unsigned int ast_sorcery_object_has_dynamic_contents ( const void *  object)

Get whether an object contains dynamic contents or not.

Parameters
objectPointer to a sorcery object
Since
19
18.3.0
16.17.0

Definition at line 2377 of file sorcery.c.

2378{
2379 const struct ast_sorcery_object_details *details = object;
2380
2381 return details->object->has_dynamic_contents;
2382}
unsigned int has_dynamic_contents
Whether this object has dynamic contents or not.
Definition: sorcery.c:144

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

Referenced by sorcery_config_internal_load().

◆ ast_sorcery_object_id_compare()

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

ao2 object comparator based on sorcery id.

Definition at line 2464 of file sorcery.c.

2465{
2466 int cmp;
2467
2468 cmp = ast_sorcery_object_id_sort(obj, arg, flags);
2469 if (cmp) {
2470 return 0;
2471 }
2472 return CMP_MATCH;
2473}
int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags)
ao2 object sorter based on sorcery id.
Definition: sorcery.c:2440

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

◆ ast_sorcery_object_id_hash()

int ast_sorcery_object_id_hash ( const void *  obj,
int  flags 
)

ao2 object hasher based on sorcery id.

Definition at line 2475 of file sorcery.c.

2476{
2477 const char *key;
2478
2479 switch (flags & OBJ_SEARCH_MASK) {
2480 case OBJ_SEARCH_KEY:
2481 key = obj;
2482 break;
2483 case OBJ_SEARCH_OBJECT:
2484 key = ast_sorcery_object_get_id(obj);
2485 break;
2486 default:
2487 /* Hash can only work on something with a full key. */
2488 ast_assert(0);
2489 return 0;
2490 }
2491 return ast_str_hash(key);
2492}
@ OBJ_SEARCH_OBJECT
The arg parameter is an object of the same type.
Definition: astobj2.h:1087
@ OBJ_SEARCH_MASK
Search option field mask.
Definition: astobj2.h:1072
static force_inline int attribute_pure ast_str_hash(const char *str)
Compute a hash value on a string.
Definition: strings.h:1259

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

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

◆ ast_sorcery_object_id_sort()

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

ao2 object sorter based on sorcery id.

Definition at line 2440 of file sorcery.c.

2441{
2442 const void *object_left = obj;
2443 const void *object_right = arg;
2444 const char *right_key = arg;
2445 int cmp;
2446
2447 switch (flags & OBJ_SEARCH_MASK) {
2448 case OBJ_SEARCH_OBJECT:
2449 right_key = ast_sorcery_object_get_id(object_right);
2450 /* Fall through */
2451 case OBJ_SEARCH_KEY:
2452 cmp = strcmp(ast_sorcery_object_get_id(object_left), right_key);
2453 break;
2455 cmp = strncmp(ast_sorcery_object_get_id(object_left), right_key, strlen(right_key));
2456 break;
2457 default:
2458 cmp = 0;
2459 break;
2460 }
2461 return cmp;
2462}
@ OBJ_SEARCH_PARTIAL_KEY
The arg parameter is a partial search key similar to OBJ_SEARCH_KEY.
Definition: astobj2.h:1116

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(), geoloc_config_list_locations(), geoloc_config_list_profiles(), geoloc_config_show_profiles(), and sip_options_aor_alloc().

◆ ast_sorcery_object_set_congestion_levels()

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

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

Since
13.10.0
Parameters
sorceryPointer to a sorcery structure
typeType of object
low_waterNew queue low water mark. (-1 to set as 90% of high_water)
high_waterNew queue high water mark.
Return values
0on success.
-1on error (water marks not changed).

Definition at line 1114 of file sorcery.c.

1115{
1116 struct ast_sorcery_object_type *object_type;
1117 int res = -1;
1118
1119 object_type = ao2_find(sorcery->types, type, OBJ_SEARCH_KEY);
1120 if (object_type) {
1122 low_water, high_water);
1123 ao2_ref(object_type, -1);
1124 }
1125 return res;
1126}
int ast_taskprocessor_alert_set_levels(struct ast_taskprocessor *tps, long low_water, long high_water)
Set the high and low alert water marks of the given taskprocessor queue.

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

Referenced by ast_sip_initialize_sorcery_location().

◆ ast_sorcery_object_set_copy_handler()

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

Set the copy handler for an object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
copyCopy handler

Definition at line 1128 of file sorcery.c.

1129{
1131
1132 if (!object_type) {
1133 return;
1134 }
1135
1136 object_type->copy = copy;
1137}

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

Referenced by ast_bucket_init(), and AST_TEST_DEFINE().

◆ ast_sorcery_object_set_diff_handler()

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

Set the diff handler for an object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
diffDiff handler

Definition at line 1139 of file sorcery.c.

1140{
1142
1143 if (!object_type) {
1144 return;
1145 }
1146
1147 object_type->diff = diff;
1148}

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

Referenced by AST_TEST_DEFINE().

◆ ast_sorcery_object_set_extended()

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

Set an extended field value on a sorcery object.

Parameters
objectPointer to a sorcery object
nameName of the extended field
valueValue of the extended field
Return values
0success
-1failure
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 2349 of file sorcery.c.

2350{
2352 struct ast_variable *extended = ast_variable_new(name, value, ""), *previous = NULL;
2353 const struct ast_sorcery_object_details *details = object;
2354
2355 if (!extended) {
2356 return -1;
2357 }
2358
2359 for (field = details->object->extended; field; previous = field, field = field->next) {
2360 if (!strcmp(field->name, name)) {
2361 if (previous) {
2362 previous->next = field->next;
2363 } else {
2364 details->object->extended = field->next;
2365 }
2366 field->next = NULL;
2367 break;
2368 }
2369 }
2370
2371 extended->next = details->object->extended;
2372 details->object->extended = extended;
2373
2374 return 0;
2375}
int value
Definition: syslog.c:37

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

Referenced by AST_TEST_DEFINE(), and sorcery_extended_config_handler().

◆ ast_sorcery_object_set_has_dynamic_contents()

void ast_sorcery_object_set_has_dynamic_contents ( const void *  object)

Set the dynamic contents flag on a sorcery object.

Parameters
objectPointer to a sorcery object
Since
19
18.3.0
16.17.0

Definition at line 2384 of file sorcery.c.

2385{
2386 const struct ast_sorcery_object_details *details = object;
2387
2388 details->object->has_dynamic_contents = 1;
2389}

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

Referenced by ip_identify_apply(), and transport_tls_file_handler().

◆ ast_sorcery_object_unregister()

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

Unregister an object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object
Return values
0success
-1failure

Definition at line 1061 of file sorcery.c.

1062{
1063 struct ast_sorcery_object_type *object_type;
1064 int res = -1;
1065
1067 object_type = ao2_find(sorcery->types, type, OBJ_SEARCH_KEY | OBJ_NOLOCK);
1068 if (object_type && object_type->type.type == ACO_ITEM) {
1069 ao2_unlink_flags(sorcery->types, object_type, OBJ_NOLOCK);
1070 res = 0;
1071 }
1073
1074 /* XXX may need to add an instance unregister observer callback on success. */
1075
1076 ao2_cleanup(object_type);
1077 return res;
1078}
#define ao2_unlink_flags(container, obj, flags)
Remove an object from a container.
Definition: astobj2.h:1600
enum aco_type_t type
struct aco_type type
Type details.
Definition: sorcery.c:177

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

Referenced by geoloc_config_unload(), and unload_module().

◆ ast_sorcery_objectset_apply()

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

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

Parameters
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
objectsetObject set itself
Return values
0success
-1failure
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.

1633{
1634 const struct ast_sorcery_object_details *details = object;
1635 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
1636 RAII_VAR(struct ast_variable *, transformed, NULL, ast_variables_destroy);
1637 struct ast_variable *field;
1638 int res = 0;
1639
1640 if (!object_type) {
1641 return -1;
1642 }
1643
1644 if (object_type->transform && (transformed = object_type->transform(objectset))) {
1645 field = transformed;
1646 } else {
1647 field = objectset;
1648 }
1649
1650 for (; field; field = field->next) {
1651 if ((res = aco_process_var(&object_type->type, details->object->id, field, object))) {
1652 break;
1653 }
1654 }
1655
1656 if (!res && object_type->apply) {
1657 res = object_type->apply(sorcery, object);
1658 }
1659
1660 return res;
1661}
int aco_process_var(struct aco_type *type, const char *cat, struct ast_variable *var, void *obj)
Parse a single ast_variable and apply it to an object.

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

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

◆ ast_sorcery_objectset_create2()

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

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

Parameters
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
flagsFlags indicating which handler to use and in what order.
Return values
non-NULLsuccess
NULLif error occurred
Note
The returned ast_variable list must be destroyed using ast_variables_destroy

Definition at line 1511 of file sorcery.c.

1513{
1514 const struct ast_sorcery_object_details *details = object;
1515 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
1516 struct ao2_iterator i;
1517 struct ast_sorcery_object_field *object_field;
1518 struct ast_variable *head = NULL;
1519 struct ast_variable *tail = NULL;
1520
1521 if (!object_type) {
1522 return NULL;
1523 }
1524
1525 i = ao2_iterator_init(object_type->fields, 0);
1526
1527 for (; (object_field = ao2_iterator_next(&i)); ao2_ref(object_field, -1)) {
1528 struct ast_variable *tmp;
1529
1530 switch (flags) {
1532 if ((tmp = get_multiple_fields_as_var_list(object, object_field)) ||
1533 (tmp = get_single_field_as_var_list(object, object_field))) {
1534 break;
1535 }
1536 continue;
1538 if ((tmp = get_single_field_as_var_list(object, object_field)) ||
1539 (tmp = get_multiple_fields_as_var_list(object, object_field))) {
1540 break;
1541 }
1542 continue;
1544 if ((tmp = get_multiple_fields_as_var_list(object, object_field))) {
1545 break;
1546 }
1547 continue;
1549 if ((tmp = get_single_field_as_var_list(object, object_field))) {
1550 break;
1551 }
1552 continue;
1553 default:
1554 continue;
1555 }
1556
1557 tail = ast_variable_list_append_hint(&head, tail, tmp);
1558 }
1559
1561
1562 return head;
1563}
#define ao2_iterator_next(iter)
Definition: astobj2.h:1911
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
struct ast_variable * ast_variable_list_append_hint(struct ast_variable **head, struct ast_variable *search_hint, struct ast_variable *new_var)
Appends a variable list to the end of another list.
Definition: main/config.c:646
static struct ast_variable * get_single_field_as_var_list(const void *object, struct ast_sorcery_object_field *object_field)
Definition: sorcery.c:1478
static struct ast_variable * get_multiple_fields_as_var_list(const void *object, struct ast_sorcery_object_field *object_field)
Definition: sorcery.c:1495
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821

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

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

◆ ast_sorcery_objectset_json_create()

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

Create an object set in JSON format for an object.

Parameters
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
Return values
non-NULLsuccess
NULLif error occurred
Note
The returned ast_json object must be unreferenced using ast_json_unref

Definition at line 1565 of file sorcery.c.

1566{
1567 const struct ast_sorcery_object_details *details = object;
1568 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
1569 struct ao2_iterator i;
1570 struct ast_sorcery_object_field *object_field;
1571 struct ast_json *json = ast_json_object_create();
1572 int res = 0;
1573
1574 if (!object_type || !json) {
1575 ast_json_unref(json);
1576 return NULL;
1577 }
1578
1579 i = ao2_iterator_init(object_type->fields, 0);
1580
1581 for (; !res && (object_field = ao2_iterator_next(&i)); ao2_ref(object_field, -1)) {
1582 if (object_field->multiple_handler) {
1583 struct ast_variable *tmp = NULL;
1584 struct ast_variable *field;
1585
1586 if ((res = object_field->multiple_handler(object, &tmp))) {
1588 ao2_ref(object_field, -1);
1589 break;
1590 }
1591
1592 for (field = tmp; field; field = field->next) {
1593 struct ast_json *value = ast_json_string_create(field->value);
1594
1595 if (!value || ast_json_object_set(json, field->name, value)) {
1596 res = -1;
1597 break;
1598 }
1599 }
1600
1602 } else if (object_field->handler) {
1603 char *buf = NULL;
1604 struct ast_json *value = NULL;
1605
1606 if (object_field->handler(object, object_field->args, &buf)
1608 || ast_json_object_set(json, object_field->name, value)) {
1609 ast_free(buf);
1610 ast_debug(5, "Skipping field '%s' for object type '%s'\n",
1611 object_field->name, object_type->name);
1612 continue;
1613 }
1614
1615 ast_free(buf);
1616 } else {
1617 continue;
1618 }
1619 }
1620
1622
1623 /* If any error occurs we destroy the JSON object so a partial objectset is not returned */
1624 if (res) {
1625 ast_json_unref(json);
1626 json = NULL;
1627 }
1628
1629 return json;
1630}
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
struct ast_json * ast_json_string_create(const char *value)
Construct a JSON string from value.
Definition: json.c:278
void ast_json_unref(struct ast_json *value)
Decrease refcount on value. If refcount reaches zero, value is freed.
Definition: json.c:73
struct ast_json * ast_json_object_create(void)
Create a new JSON object.
Definition: json.c:399
int ast_json_object_set(struct ast_json *object, const char *key, struct ast_json *value)
Set a field in a JSON object.
Definition: json.c:414
Abstract JSON element (object, array, string, int, ...).

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

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

◆ ast_sorcery_observer_add()

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

Add an observer to a specific object type.

Parameters
sorceryPointer to a sorcery structure
typeType of object that should be observed
callbacksImplementation of the observer interface
Return values
0success
-1failure
Note
You must be ready to accept observer invocations before this function is called

Definition at line 2391 of file sorcery.c.

2392{
2395 int res;
2396
2397 if (!object_type || !callbacks) {
2398 return -1;
2399 }
2400
2401 if (!(observer = ao2_alloc(sizeof(*observer), NULL))) {
2402 return -1;
2403 }
2404
2405 observer->callbacks = callbacks;
2406 res = 0;
2407 if (!ao2_link(object_type->observers, observer)) {
2408 res = -1;
2409 }
2410 ao2_ref(observer, -1);
2411
2412 return res;
2413}
struct ast_sorcery_instance_observer observer
Structure for registered object type observer.
Definition: sorcery.c:190

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

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

◆ 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
sorceryPointer to a sorcery structure
typeType of object that should no longer be observed
callbacksImplementation of the observer interface

Definition at line 2423 of file sorcery.c.

2424{
2425 RAII_VAR(struct ast_sorcery_object_type *, object_type, NULL, ao2_cleanup);
2426 struct ast_sorcery_observer *cbs = (struct ast_sorcery_observer *) callbacks;/* Remove const for traversal. */
2427
2428 if (!sorcery) {
2429 return;
2430 }
2431 object_type = ao2_find(sorcery->types, type, OBJ_KEY);
2432 if (!object_type) {
2433 return;
2434 }
2435
2436 ao2_callback(object_type->observers, OBJ_NODATA | OBJ_UNLINK,
2438}
static int sorcery_observer_remove(void *obj, void *arg, int flags)
Internal callback function for removing an observer.
Definition: sorcery.c:2416
Interface for a sorcery object type observer.
Definition: sorcery.h:332

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

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

◆ ast_sorcery_ref()

void ast_sorcery_ref ( struct ast_sorcery sorcery)

Increase the reference count of a sorcery structure.

Parameters
sorceryPointer to a sorcery structure

Definition at line 1473 of file sorcery.c.

1474{
1475 ao2_ref(sorcery, +1);
1476}

References ao2_ref, and sorcery.

Referenced by geoloc_get_sorcery().

◆ ast_sorcery_reload()

void ast_sorcery_reload ( const struct ast_sorcery sorcery)

Inform any wizards to reload persistent objects.

Parameters
sorceryPointer to a sorcery structure

Definition at line 1408 of file sorcery.c.

1409{
1410 struct sorcery_load_details details = {
1411 .sorcery = sorcery,
1412 .reload = 1,
1413 };
1414
1415 NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
1417
1419
1422
1423}

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

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

◆ ast_sorcery_reload_object()

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

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

Parameters
sorceryPointer to a sorcery structure
typeName of the object type to reload

Definition at line 1442 of file sorcery.c.

1443{
1445 struct sorcery_load_details details = {
1446 .sorcery = sorcery,
1447 .reload = 1,
1448 };
1449
1450 if (!object_type) {
1451 return;
1452 }
1453
1454 sorcery_object_load(object_type, &details, 0);
1455}

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

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

◆ ast_sorcery_retrieve_by_fields()

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

Retrieve an object or multiple objects using specific fields.

Since
13.9.0
Parameters
sorceryPointer to a sorcery structure
typeType of object to retrieve
flagsFlags to control behavior
fieldsOptional object fields and values to match against
Return values
non-NULLif found
NULLif 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.

1898{
1900 void *object = NULL;
1901 int i;
1902 unsigned int cached = 0;
1903
1904 if (!object_type) {
1905 return NULL;
1906 }
1907
1908 /* If returning multiple objects create a container to store them in */
1909 if ((flags & AST_RETRIEVE_FLAG_MULTIPLE)) {
1911 if (!object) {
1912 return NULL;
1913 }
1914 }
1915
1916 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
1917 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
1919 AST_VECTOR_GET(&object_type->wizards, i);
1920
1921 if ((flags & AST_RETRIEVE_FLAG_MULTIPLE)) {
1922 if (wizard->wizard->callbacks.retrieve_multiple) {
1923 wizard->wizard->callbacks.retrieve_multiple(sorcery, wizard->data, object_type->name, object, fields);
1924 }
1925 } else if (fields && wizard->wizard->callbacks.retrieve_fields) {
1926 if (wizard->wizard->callbacks.retrieve_fields) {
1927 object = wizard->wizard->callbacks.retrieve_fields(sorcery, wizard->data, object_type->name, fields);
1928 }
1929 }
1930
1931 if (((flags & AST_RETRIEVE_FLAG_MULTIPLE) && (!ao2_container_count(object) || !wizard->caching)) || !object) {
1932 continue;
1933 }
1934
1935 cached = wizard->caching;
1936
1937 break;
1938 }
1939
1940 /* If we are returning a single object and it came from a non-cache source create it in any caches */
1941 if (!(flags & AST_RETRIEVE_FLAG_MULTIPLE) && !cached && object) {
1942 struct sorcery_details sdetails = {
1943 .sorcery = sorcery,
1944 .obj = object,
1945 };
1946
1947 AST_VECTOR_CALLBACK(&object_type->wizards, sorcery_cache_create, NULL, &sdetails, 0);
1948 }
1949 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
1950
1951 return object;
1952}
static int sorcery_cache_create(void *obj, void *arg, int flags)
Internal function used to create an object in caching wizards.
Definition: sorcery.c:1839
void(* retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields)
Optional callback for retrieving multiple objects using some optional field criteria.
Definition: sorcery.h:313
void *(* retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields)
Optional callback for retrieving an object using fields.
Definition: sorcery.h:310
#define AST_VECTOR_CALLBACK(vec, callback, default_value,...)
Execute a callback on every element in a vector returning the first matched.
Definition: vector.h:765

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_internal_wizard::callbacks, NULL, OBJ_KEY, RAII_VAR, ast_sorcery_wizard::retrieve_fields, ast_sorcery_wizard::retrieve_multiple, sorcery_details::sorcery, sorcery, sorcery_cache_create(), type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

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

◆ ast_sorcery_retrieve_by_id()

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

Retrieve an object using its unique identifier.

Parameters
sorceryPointer to a sorcery structure
typeType of object to retrieve
idUnique object identifier
Return values
non-NULLif found
NULLif not found

Definition at line 1853 of file sorcery.c.

1854{
1855 struct ast_sorcery_object_type *object_type;
1856 void *object = NULL;
1857 int i;
1858 unsigned int cached = 0;
1859
1860 if (ast_strlen_zero(id)) {
1861 return NULL;
1862 }
1863
1864 object_type = ao2_find(sorcery->types, type, OBJ_SEARCH_KEY);
1865 if (!object_type) {
1866 return NULL;
1867 }
1868
1869 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
1870 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
1872 AST_VECTOR_GET(&object_type->wizards, i);
1873
1874 if (wizard->wizard->callbacks.retrieve_id &&
1875 !(object = wizard->wizard->callbacks.retrieve_id(sorcery, wizard->data, object_type->name, id))) {
1876 continue;
1877 }
1878
1879 cached = wizard->caching;
1880 break;
1881 }
1882
1883 if (!cached && object) {
1884 struct sorcery_details sdetails = {
1885 .sorcery = sorcery,
1886 .obj = object,
1887 };
1888
1889 AST_VECTOR_CALLBACK(&object_type->wizards, sorcery_cache_create, NULL, &sdetails, 0);
1890 }
1891 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
1892
1893 ao2_ref(object_type, -1);
1894 return object;
1895}
char name[MAX_OBJECT_TYPE]
Unique name of the object type.
Definition: sorcery.c:150
void *(* retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id)
Callback for retrieving an object using an id.
Definition: sorcery.h:296

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

Referenced by add_security_headers(), ami_show_endpoint(), ami_sip_qualify(), anonymous_identify(), as_get_cfg(), as_is_config_loaded(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), ast_bucket_file_retrieve(), ast_bucket_retrieve(), ast_geoloc_datastore_create_from_profile_name(), ast_geoloc_eprofile_refresh_location(), ast_geoloc_get_location(), ast_geoloc_get_profile(), ast_mwi_mailbox_get(), ast_mwi_mailbox_update(), ast_sip_default_outbound_endpoint(), ast_sip_for_each_auth(), ast_sip_location_retrieve_aor(), ast_sip_location_retrieve_contact(), ast_sip_retrieve_auths(), ast_sip_retrieve_auths_vector(), ast_sip_rewrite_uri_to_local(), ast_sip_set_tpselector_from_transport_name(), AST_TEST_DEFINE(), 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(), client_config_get(), common_identify(), contact_observer_updated(), create_effective_profile(), create_rtp(), eprofile_get_cfg(), find_aor_name(), find_endpoint(), format_ami_endpoint_transport(), geoloc_profile_apply_handler(), get_log_mappings(), get_write_timeout(), handle_atsign(), handle_registration_response(), handle_single_token(), handle_slash(), line_identify(), load_endpoint(), mwi_contact_changed(), mwi_contact_deleted(), mwi_subscription_shutdown(), on_rx_process_symmetric_transport(), pjsip_acf_dial_contacts_read(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), process_nat(), profile_get_cfg(), publish_request_initial(), push_notify(), request(), retrieve_resource_list(), send_unsolicited_mwi_notify(), sip_options_contact_add_management_task(), sip_options_qualify_contact(), sorcery_function_read(), sorcery_memory_cache_thrash_retrieve(), stale_item_update(), sub_persistence_recreate(), t38_initialize_session(), tn_get_cfg(), tn_get_etn(), transfer(), vs_get_cfg(), and vs_is_config_loaded().

◆ ast_sorcery_retrieve_by_module_name()

struct ast_sorcery * ast_sorcery_retrieve_by_module_name ( const char *  module_name)

Retrieves an existing sorcery instance by module name.

Parameters
module_nameThe module name
Return values
non-NULLsuccess
NULLif 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.

673{
674 return ao2_weakproxy_find(instances, module_name, OBJ_SEARCH_KEY, "");
675}
#define ao2_weakproxy_find(c, arg, flags, tag)
Perform an ao2_find on a container with ao2_weakproxy objects, returning the real object.
Definition: astobj2.h:1748

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

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

◆ ast_sorcery_retrieve_by_prefix()

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

Retrieve multiple objects whose id begins with the specified prefix.

Since
13.19.0
Parameters
sorceryPointer to a sorcery structure
typeType of object to retrieve
prefixObject id prefix
prefix_lenThe length of prefix in bytes
Return values
non-NULLif error occurs
NULLsuccess
Note
The prefix is matched in a case sensitive manner.

Definition at line 1989 of file sorcery.c.

1990{
1992 struct ao2_container *objects;
1993 int i;
1994
1995 if (!object_type) {
1996 return NULL;
1997 }
1998
2000 if (!objects) {
2001 return NULL;
2002 }
2003
2004 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
2005 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2007 AST_VECTOR_GET(&object_type->wizards, i);
2008
2009 if (!wizard->wizard->callbacks.retrieve_prefix) {
2010 continue;
2011 }
2012
2013 wizard->wizard->callbacks.retrieve_prefix(sorcery, wizard->data, object_type->name, objects, prefix, prefix_len);
2014
2015 if (wizard->caching && ao2_container_count(objects)) {
2016 break;
2017 }
2018 }
2019 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
2020
2021 return objects;
2022}
static char prefix[MAX_PREFIX]
Definition: http.c:144
Generic container type.
void(* retrieve_prefix)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *prefix, const size_t prefix_len)
Optional callback for retrieving multiple objects by matching their id with a prefix.
Definition: sorcery.h:302

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_internal_wizard::callbacks, NULL, OBJ_KEY, prefix, RAII_VAR, ast_sorcery_wizard::retrieve_prefix, sorcery, type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

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

◆ ast_sorcery_retrieve_by_regex()

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

Retrieve multiple objects using a regular expression on their id.

Parameters
sorceryPointer to a sorcery structure
typeType of object to retrieve
regexRegular expression
Return values
non-NULLif error occurs
NULLsuccess
Note
The provided regex is treated as extended case sensitive.

Definition at line 1954 of file sorcery.c.

1955{
1957 struct ao2_container *objects;
1958 int i;
1959
1960 if (!object_type) {
1961 return NULL;
1962 }
1963
1965 if (!objects) {
1966 return NULL;
1967 }
1968
1969 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
1970 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
1972 AST_VECTOR_GET(&object_type->wizards, i);
1973
1974 if (!wizard->wizard->callbacks.retrieve_regex) {
1975 continue;
1976 }
1977
1978 wizard->wizard->callbacks.retrieve_regex(sorcery, wizard->data, object_type->name, objects, regex);
1979
1980 if (wizard->caching && ao2_container_count(objects)) {
1981 break;
1982 }
1983 }
1984 AST_VECTOR_RW_UNLOCK(&object_type->wizards);
1985
1986 return objects;
1987}
void(* retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex)
Callback for retrieving multiple objects using a regex on their id.
Definition: sorcery.h:299

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_internal_wizard::callbacks, NULL, OBJ_KEY, RAII_VAR, regex(), ast_sorcery_wizard::retrieve_regex, sorcery, type, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

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

◆ ast_sorcery_update()

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

Update an object.

Parameters
sorceryPointer to a sorcery structure
objectPointer to a sorcery object
Return values
0success
-1failure

Definition at line 2150 of file sorcery.c.

2151{
2152 const struct ast_sorcery_object_details *details = object;
2153 RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->object->type, OBJ_KEY), ao2_cleanup);
2154 struct ast_sorcery_object_wizard *object_wizard = NULL;
2155 struct ast_sorcery_object_wizard *found_wizard;
2156 int i;
2157 struct sorcery_details sdetails = {
2158 .sorcery = sorcery,
2159 .obj = object,
2160 };
2161
2162 if (!object_type) {
2163 return -1;
2164 }
2165
2166 AST_VECTOR_RW_RDLOCK(&object_type->wizards);
2167 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2168 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2169 if (!found_wizard->caching
2170 && sorcery_wizard_update(found_wizard, &sdetails) == CMP_MATCH) {
2171 object_wizard = found_wizard;
2172 }
2173 }
2174
2175 if (object_wizard) {
2176 for (i = 0; i < AST_VECTOR_SIZE(&object_type->wizards); i++) {
2177 found_wizard = AST_VECTOR_GET(&object_type->wizards, i);
2178 if (found_wizard->caching) {
2179 sorcery_wizard_update(found_wizard, &sdetails);
2180 }
2181 }
2182
2183 if (ao2_container_count(object_type->observers)) {
2184 struct sorcery_observer_invocation *invocation;
2185
2186 invocation = sorcery_observer_invocation_alloc(object_type, object);
2187 if (invocation
2189 invocation)) {
2190 ao2_cleanup(invocation);
2191 }
2192 }
2193 }
2194
2196
2197 return object_wizard ? 0 : -1;
2198}
static int sorcery_wizard_update(const struct ast_sorcery_object_wizard *object_wizard, const struct sorcery_details *details)
Internal function which returns if a wizard has updated the object.
Definition: sorcery.c:2136
static int sorcery_observers_notify_update(void *data)
Internal callback function which notifies observers that an object has been updated.
Definition: sorcery.c:2125

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

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

◆ ast_sorcery_wizard_observer_add()

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

Add an observer to a sorcery wizard.

Parameters
wizardPointer to a previously registered wizard structure
callbacksImplementation 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
0success
-1failure
Note
You must be ready to accept observer invocations before this function is called

Definition at line 543 of file sorcery.c.

545{
546 RAII_VAR(struct ast_sorcery_internal_wizard *, wizard,
547 interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL,
549
550 if (wizard) {
551 struct sorcery_wizard_observer *cb;
552
553 cb = ao2_alloc(sizeof(*cb), NULL);
554 if (!cb) {
555 return -1;
556 }
557
558 cb->callbacks = callbacks;
559 ao2_link(wizard->observers, cb);
560 ao2_ref(cb, -1);
561
562 return 0;
563 }
564
565 return -1;
566}
A wizard observer wrapper.
Definition: sorcery.c:276
const struct ast_sorcery_wizard_observer * callbacks
Definition: sorcery.c:277

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

Referenced by AST_TEST_DEFINE().

◆ ast_sorcery_wizard_observer_remove()

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

Remove an observer from a sorcery wizard.

Parameters
interfacePointer to a sorcery structure
callbacksImplementation of the wizard observer interface

Definition at line 568 of file sorcery.c.

570{
571 RAII_VAR(struct ast_sorcery_internal_wizard *, wizard,
572 interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL,
574
575 if (wizard) {
577 }
578}

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

Referenced by AST_TEST_DEFINE().

◆ ast_sorcery_wizard_unregister()

int ast_sorcery_wizard_unregister ( const struct ast_sorcery_wizard interface)

Unregister a sorcery wizard.

Parameters
interfacePointer to the wizard interface
Return values
0success
-1failure

Definition at line 474 of file sorcery.c.

475{
476 struct ast_sorcery_internal_wizard *wizard =
477 interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL;
478
479 if (wizard) {
480 NOTIFY_GLOBAL_OBSERVERS(observers, wizard_unregistering, wizard->callbacks.name, &wizard->callbacks);
481 ao2_unlink(wizards, wizard);
482 ao2_ref(wizard, -1);
483 ast_verb(5, "Sorcery unregistered wizard '%s'\n", interface->name);
484 return 0;
485 } else {
486 return -1;
487 }
488}
if(!yyg->yy_init)
Definition: ast_expr2f.c:854
#define ao2_unlink(container, obj)
Remove an object from a container.
Definition: astobj2.h:1578

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

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