Asterisk - The Open Source Telephony Project  21.4.1
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"

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()
 
#define MAX_OBJECT_FIELD   128
 Maximum length of an object field name.
 
#define MAX_OBJECT_TYPE   64
 Maximum size of an object type.
 
#define SORCERY_OBJECT(details)
 Macro which must be used at the beginning of each sorcery capable object. 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.
 

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.
 
int ast_sorcery_object_id_hash (const void *obj, int flags)
 ao2 object hasher based on sorcery id.
 
int ast_sorcery_object_id_sort (const void *obj, const void *arg, int flags)
 ao2 object sorter based on sorcery id.
 
int ast_sorcery_object_set_congestion_levels (struct ast_sorcery *sorcery, const char *type, long low_water, long high_water)
 Set the high and low alert water marks of the sorcery object type. 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

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

Referenced by object_type_registered_observer().

#define ast_sorcery_insert_wizard_mapping (   sorcery,
  type,
  name,
  data,
  caching,
  position 
)
Value:
__ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
(caching), (position))
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.

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

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

Referenced by ast_bucket_init().

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

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

Referenced by ast_bucket_init().

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

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

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

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

Referenced by ast_bucket_init().

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

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

#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))
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

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.

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

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

Referenced by ast_aeap_custom_fields_get(), ast_sorcery_copy(), and ast_sorcery_diff().

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

Referenced by ast_bucket_init().

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

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

Referenced by ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), and bucket_cleanup().

#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

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.

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.

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.

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.

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.

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 181 of file sorcery.h.

Enumeration Type Documentation

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

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 };
Try both handlers, list first.
Definition: sorcery.h:134
Use list handler only.
Definition: sorcery.h:140
Use string handler only.
Definition: sorcery.h:137
Try both handlers, string first.
Definition: sorcery.h:131

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 */
120  AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
121 
122  /*! \brief Perform no matching, return all objects */
123  AST_RETRIEVE_FLAG_ALL = (1 << 1),
124 };
Perform no matching, return all objects.
Definition: sorcery.h:123
Return all matching objects.
Definition: sorcery.h:120
Default retrieval flags.
Definition: sorcery.h:117

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

Function Documentation

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.

References __ast_sorcery_apply_wizard_mapping(), ast_config_destroy(), ast_config_load2(), AST_SORCERY_APPLY_FAIL, AST_SORCERY_APPLY_NO_CONFIGURATION, AST_SORCERY_APPLY_SUCCESS, ast_strdup, ast_variable::name, ast_variable::next, RAII_VAR, and ast_variable::value.

986 {
987  struct ast_flags flags = { 0 };
988  struct ast_config *config = ast_config_load2("sorcery.conf", "sorcery", flags);
989  struct ast_variable *mapping;
990  int res = AST_SORCERY_APPLY_SUCCESS;
991 
992  if (!config) {
994  }
995 
996  if (config == CONFIG_STATUS_FILEINVALID) {
997  return AST_SORCERY_APPLY_FAIL;
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) {
1021  res = AST_SORCERY_APPLY_FAIL;
1022  break;
1023  }
1024  }
1025 
1026  ast_config_destroy(config);
1027 
1028  return res;
1029 }
struct ast_variable * next
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
Structure for variables, used for configurations and for channel variables.
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
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
Structure used to handle boolean flags.
Definition: utils.h:199
void ast_config_destroy(struct ast_config *cfg)
Destroys a config.
Definition: extconf.c:1289
#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
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.

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

1032 {
1033  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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
Structure for registered object type.
Definition: sorcery.c:148
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
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

References __ast_sorcery_insert_wizard_mapping().

Referenced by __ast_sorcery_apply_config(), and __ast_sorcery_apply_default().

980 {
981  return __ast_sorcery_insert_wizard_mapping(sorcery, type, module, name,
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
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.

References __ast_sorcery_object_type_insert_wizard(), AST_SORCERY_WIZARD_APPLY_CACHING, and AST_SORCERY_WIZARD_APPLY_NONE.

Referenced by __ast_sorcery_apply_wizard_mapping().

970 {
971  return __ast_sorcery_object_type_insert_wizard(sorcery, type, module, name,
973  position, NULL, NULL);
974 }
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
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.

References __aco_option_register(), ao2_link, ast_sorcery_object_field::args, ast_copy_string(), ast_sorcery_object_field::handler, ast_sorcery_object_field::multiple_handler, ast_sorcery_object_field::name, OBJ_KEY, RAII_VAR, and ast_sorcery::types.

1194 {
1195  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 OBJ_KEY
Definition: astobj2.h:1151
Structure for registered object type.
Definition: sorcery.c:148
Structure for registered object field.
Definition: sorcery.c:205
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
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
#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
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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.

References aco_info_init(), ast_sorcery_object_type::apply, ast_sorcery_object_fields_register(), ast_sorcery::module_name, OBJ_KEY, ast_sorcery::observers, RAII_VAR, ast_sorcery_object_type::reloadable, ast_sorcery_object_type::transform, and ast_sorcery::types.

1081 {
1082  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 
1104  if (ast_sorcery_object_fields_register(sorcery, type, "^@", sorcery_extended_config_handler, sorcery_extended_fields_handler)) {
1105  return -1;
1106  }
1107 
1108  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, object_type_registered,
1109  sorcery->module_name, sorcery, type);
1110 
1111  return 0;
1112 }
#define OBJ_KEY
Definition: astobj2.h:1151
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
int aco_info_init(struct aco_info *info)
Initialize an aco_info structure.
Structure for registered object type.
Definition: sorcery.c:148
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
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

References ast_sorcery_object_wizard::allow_duplicates, ao2_bump, ao2_link, ast_debug, 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_VECTOR_GET_CMP, AST_VECTOR_INSERT_AT, AST_VECTOR_RW_UNLOCK, AST_VECTOR_RW_WRLOCK, AST_VECTOR_SIZE, ast_sorcery::module_name, OBJ_KEY, ast_sorcery::observers, RAII_VAR, S_OR, sorcery_object_type_alloc(), sorcery_object_wizard_destructor(), and ast_sorcery::types.

Referenced by __ast_sorcery_insert_wizard_mapping().

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) {
884  return AST_SORCERY_APPLY_FAIL;
885  }
886 
887  if (!internal_wizard
888  || internal_wizard->callbacks.module != ast_module_running_ref(internal_wizard->callbacks.module)) {
889  ast_log(LOG_ERROR,
890  "Wizard '%s' could not be applied to object type '%s' as it was not found\n",
891  wizard_type_name, object_type_name);
892  return AST_SORCERY_APPLY_FAIL;
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);
898  return AST_SORCERY_APPLY_FAIL;
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);
927  return AST_SORCERY_APPLY_FAIL;
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);
943  return AST_SORCERY_APPLY_FAIL;
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 
952  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, wizard_mapped,
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 }
char wizard_args[0]
Wizard arguments.
Definition: sorcery.c:120
unsigned int allow_duplicates
Wizard allows others of the same type.
Definition: sorcery.c:117
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
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
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
Structure for registered object type.
Definition: sorcery.c:148
#define ast_debug(level,...)
Log a DEBUG message.
Structure for an internal wizard instance.
Definition: sorcery.c:89
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define AST_VECTOR_RW_WRLOCK(vec)
Obtain write lock on vector.
Definition: vector.h:887
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257
#define AST_VECTOR_GET_CMP(vec, value, cmp)
Get an element from a vector that matches the given comparison.
Definition: vector.h:731
#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
static void sorcery_object_wizard_destructor(void *obj)
Object wizard destructor.
Definition: sorcery.c:762
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
#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
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
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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.

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

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 }
char wizard_args[0]
Wizard arguments.
Definition: sorcery.c:120
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
const char * name
Name of the wizard.
Definition: sorcery.h:278
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
#define AST_VECTOR_REMOVE_ORDERED(vec, idx)
Remove an element from a vector by index while maintaining order.
Definition: vector.h:448
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define AST_VECTOR_RW_WRLOCK(vec)
Obtain write lock on vector.
Definition: vector.h:887
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
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.

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

852 {
853  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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)
862  res = AST_VECTOR_REMOVE_CMP_ORDERED(&object_type->wizards, name, WIZARD_NAME_COMPARE, ao2_cleanup);
863 #undef WIZARD_NAME_COMPARE
864  AST_VECTOR_RW_UNLOCK(&object_type->wizards);
865 
866  return res;
867 }
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
Structure for registered object type.
Definition: sorcery.c:148
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define AST_VECTOR_RW_WRLOCK(vec)
Obtain write lock on vector.
Definition: vector.h:887
#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
#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
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.

References AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_list, ao2_link_flags, ast_sorcery_internal_wizard::callbacks, ast_sorcery_wizard::module, ast_sorcery_wizard::name, OBJ_KEY, OBJ_NOLOCK, and ast_sorcery_internal_wizard::observers.

Referenced by ast_bucket_init().

433 {
434  struct ast_sorcery_internal_wizard *wizard;
435  int res = -1;
436 
437  ast_assert(!ast_strlen_zero(interface->name));
438 
439  ao2_lock(wizards);
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 
467 done:
468  ao2_cleanup(wizard);
469  ao2_unlock(wizards);
470 
471  return res;
472 }
struct ao2_container * observers
Registered global observers.
Definition: sorcery.c:281
#define OBJ_KEY
Definition: astobj2.h:1151
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
#define ao2_link_flags(container, obj, flags)
Add an object to a container.
Definition: astobj2.h:1554
struct ast_module * module
Pointer to the Asterisk module this wizard is implemented by.
Definition: sorcery.h:281
const char * name
Name of the wizard.
Definition: sorcery.h:278
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
Structure for an internal wizard instance.
Definition: sorcery.c:89
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257
struct ao2_container * observers
Observers.
Definition: sorcery.c:99
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.

References aco_set_defaults(), ao2_ref, ast_copy_string(), ast_strdup, ast_tvnow(), ast_uuid_generate_str(), ast_sorcery_object::created, ast_sorcery_object::id, OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, ast_sorcery_object::type, and ast_sorcery::types.

Referenced by ast_ari_asterisk_update_object(), ast_bucket_alloc(), ast_bucket_file_alloc(), ast_mwi_mailbox_alloc(), ast_sorcery_copy(), create_object(), mock_retrieve_id(), and sorcery_astdb_retrieve_fields_common().

1745 {
1746  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 }
char * id
Unique identifier of this object.
Definition: sorcery.c:129
#define OBJ_KEY
Definition: astobj2.h:1151
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
Structure for registered object type.
Definition: sorcery.c:148
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct timeval created
Time that the object was created.
Definition: sorcery.c:141
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
int aco_set_defaults(struct aco_type *type, const char *category, void *obj)
Set all default options of obj.
char * ast_uuid_generate_str(char *buf, size_t size)
Generate a UUID string.
Definition: uuid.c:141
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
#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
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

Referenced by ast_sorcery_diff(), and sorcery_is_criteria_met().

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 }
struct ast_variable * next
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
Structure for variables, used for configurations and for channel variables.
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
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.

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

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

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);
1782  struct ast_sorcery_object_details *copy = ast_sorcery_alloc(sorcery, details->object->type, details->object->id);
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) {
1798  ao2_cleanup(copy);
1799  copy = NULL;
1800  }
1801 
1802  return copy;
1803 }
char * id
Unique identifier of this object.
Definition: sorcery.c:129
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
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 OBJ_KEY
Definition: astobj2.h:1151
Structure for variables, used for configurations and for channel variables.
static int copy(char *infile, char *outfile)
Utility function to copy a file.
Structure for registered object type.
Definition: sorcery.c:148
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define ast_sorcery_objectset_create(sorcery, object)
Create an object set (KVP list) for an object.
Definition: sorcery.h:1137
void * ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id)
Allocate an object.
Definition: sorcery.c:1744
#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
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

Referenced by ast_ari_asterisk_update_object(), ast_bucket_create(), ast_bucket_file_create(), and ast_mwi_mailbox_update().

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 }
const struct ast_sorcery * sorcery
Pointer to the sorcery instance.
Definition: sorcery.c:1833
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
Structure used when calling create, update, or delete.
Definition: sorcery.c:1831
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
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
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
Structure used for observer invocations.
Definition: sorcery.c:196
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
struct ast_taskprocessor * serializer
Serializer for observers.
Definition: sorcery.c:183
Structure for registered object type.
Definition: sorcery.c:148
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
struct ast_sorcery_object_wizards wizards
Wizard instances.
Definition: sorcery.c:165
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
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.
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
struct ast_sorcery_object_type * object_type
Pointer to the object type.
Definition: sorcery.c:198
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
static int sorcery_observers_notify_create(void *data)
Internal callback function which notifies observers that an object has been created.
Definition: sorcery.c:2052
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

Referenced by ast_ari_asterisk_delete_object(), ast_bucket_delete(), and ast_bucket_file_delete().

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 }
const struct ast_sorcery * sorcery
Pointer to the sorcery instance.
Definition: sorcery.c:1833
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
Structure used when calling create, update, or delete.
Definition: sorcery.c:1831
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
Structure used for observer invocations.
Definition: sorcery.c:196
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
struct ast_taskprocessor * serializer
Serializer for observers.
Definition: sorcery.c:183
Structure for registered object type.
Definition: sorcery.c:148
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
struct ast_sorcery_object_wizards wizards
Wizard instances.
Definition: sorcery.c:165
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
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
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.
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
struct ast_sorcery_object_type * object_type
Pointer to the object type.
Definition: sorcery.c:198
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
static int sorcery_observers_notify_delete(void *data)
Internal callback function which notifies observers that an object has been deleted.
Definition: sorcery.c:2213
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ast_sorcery_changeset_create(), ast_sorcery_object_get_type(), ast_sorcery_objectset_create, ast_variables_destroy(), OBJ_KEY, RAII_VAR, and ast_sorcery::types.

1806 {
1807  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, ast_sorcery_object_get_type(original), OBJ_KEY), ao2_cleanup);
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 }
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for variables, used for configurations and for channel variables.
const char * ast_sorcery_object_get_type(const void *object)
Get the type of a sorcery object.
Definition: sorcery.c:2329
Structure for registered object type.
Definition: sorcery.c:148
sorcery_diff_handler diff
Optional object diff callback.
Definition: sorcery.c:162
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define ast_sorcery_objectset_create(sorcery, object)
Create an object set (KVP list) for an object.
Definition: sorcery.h:1137
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
#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
struct ast_sorcery_object_type * object_type
Pointer to the object type.
Definition: sorcery.c:198
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.

References ao2_callback, ast_sorcery::module_name, OBJ_NODATA, ast_sorcery::observers, sorcery_load_details::sorcery, and ast_sorcery::types.

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,
1434  sorcery->module_name, sorcery, 1);
1435 
1436  ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
1437 
1438  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loaded,
1439  sorcery->module_name, sorcery, 1);
1440 }
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
struct ao2_container * observers
Observers.
Definition: sorcery.c:235
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244
Structure for passing load/reload details.
Definition: sorcery.c:242
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
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.

References OBJ_KEY, RAII_VAR, sorcery_load_details::sorcery, and ast_sorcery::types.

1458 {
1459  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 }
#define OBJ_KEY
Definition: astobj2.h:1151
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244
const char * type
Type of object being loaded.
Definition: sorcery.c:247
Structure for registered object type.
Definition: sorcery.c:148
Structure for passing load/reload details.
Definition: sorcery.c:242
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ast_sorcery_object::destructor, and ast_sorcery_object_details::object.

Referenced by bucket_alloc(), bucket_file_alloc(), mwi_sorcery_object_alloc(), phoneprov_alloc(), test_data_alloc(), and test_sorcery_object_alloc().

1729 {
1730  void *object = ao2_alloc_options(size + sizeof(struct ast_sorcery_object),
1731  sorcery_object_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK);
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_destructor_fn destructor
Optional object destructor.
Definition: sorcery.c:135
Structure for internal sorcery object information.
Definition: sorcery.c:127
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ast_sorcery::module_name.

2537 {
2538  return sorcery->module_name;
2539 }
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
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.

References OBJ_SEARCH_KEY, and ast_sorcery::types.

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

2496 {
2497  return ao2_find(sorcery->types, type, OBJ_SEARCH_KEY);
2498 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
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.

References ao2_bump, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_sorcery_internal_wizard::callbacks, ast_sorcery_object_wizard::data, OBJ_KEY, RAII_VAR, ast_sorcery::types, and ast_sorcery_object_wizard::wizard.

792 {
793  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 }
#define OBJ_KEY
Definition: astobj2.h:1151
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
void * data
Unique data for the wizard.
Definition: sorcery.c:108
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
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.

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

780 {
781  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
782 
783  if (!object_type) {
784  return -1;
785  }
786 
787  return AST_VECTOR_SIZE(&object_type->wizards);
788 }
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for registered object type.
Definition: sorcery.c:148
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
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.

References ao2_link, and ao2_ref.

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 ao2_container * observers
Registered global observers.
Definition: sorcery.c:281
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
A global observer wrapper.
Definition: sorcery.c:266
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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.

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

516 {
518 }
static int sorcery_generic_observer_remove(void *obj, void *arg, int flags)
Internal callback function for removing a generic observer.
Definition: sorcery.c:491
struct ao2_container * observers
Registered global observers.
Definition: sorcery.c:281
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
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.

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

388 {
389  struct ast_threadpool_options options = {
390  .version = AST_THREADPOOL_OPTIONS_VERSION,
391  .auto_increment = 1,
392  .max_size = 0,
393  .idle_timeout = 60,
394  .initial_size = 0,
395  };
396  ast_assert(wizards == NULL);
397 
398  threadpool = ast_threadpool_create("sorcery", NULL, &options);
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 }
struct ao2_container * observers
Registered global observers.
Definition: sorcery.c:281
static struct ao2_container * instances
Registered sorcery instances.
Definition: sorcery.c:284
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
static struct ast_threadpool * threadpool
Thread pool for observers.
Definition: sorcery.c:86
#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
static void sorcery_cleanup(void)
Hashing and comparison functions for sorcery wizards.
Definition: sorcery.c:369
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257
#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
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.

References ao2_link, ao2_ref, and ast_sorcery::observers.

Referenced by instance_created_observer(), and pjsip_outbound_registration_metrics_init().

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;
531  ao2_link(sorcery->observers, cb);
532  ao2_ref(cb, -1);
533 
534  return 0;
535 }
struct ao2_container * observers
Observers.
Definition: sorcery.c:235
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
An instance observer wrapper.
Definition: sorcery.c:271
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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, OBJ_NODATA, OBJ_UNLINK, ast_sorcery::observers, and sorcery_generic_observer_remove().

Referenced by instance_destroying_observer(), and pjsip_outbound_registration_metrics_init().

539 {
541 }
static int sorcery_generic_observer_remove(void *obj, void *arg, int flags)
Internal callback function for removing a generic observer.
Definition: sorcery.c:491
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
struct ao2_container * observers
Observers.
Definition: sorcery.c:235
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.

References ao2_callback, ast_sorcery_object_type::fields, and OBJ_SEARCH_KEY.

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

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 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
Structure for registered object field.
Definition: sorcery.c:205
struct ao2_container * fields
Object fields.
Definition: sorcery.c:168
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.

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

Referenced by ast_bucket_file_is_stale(), and ast_bucket_is_stale().

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,
2308  ast_sorcery_object_get_id(object),
2309  res ? "stale" : "not stale");
2310  }
2311  }
2312  AST_VECTOR_RW_UNLOCK(&object_type->wizards);
2313 
2314  return res;
2315 }
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
const char * ast_sorcery_object_get_id(const void *object)
Get the unique identifier of a sorcery object.
Definition: sorcery.c:2317
const char * name
Name of the wizard.
Definition: sorcery.h:278
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
#define ast_debug(level,...)
Log a DEBUG message.
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
void * data
Unique data for the wizard.
Definition: sorcery.c:108
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
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
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ao2_callback, ast_sorcery::module_name, OBJ_NODATA, ast_sorcery::observers, sorcery_load_details::sorcery, and ast_sorcery::types.

1378 {
1379  struct sorcery_load_details details = {
1380  .sorcery = sorcery,
1381  .reload = 0,
1382  };
1383 
1384  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
1385  sorcery->module_name, sorcery, 0);
1386 
1387  ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
1388 
1389  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loaded,
1390  sorcery->module_name, sorcery, 0);
1391 }
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
struct ao2_container * observers
Observers.
Definition: sorcery.c:235
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244
Structure for passing load/reload details.
Definition: sorcery.c:242
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
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.

References OBJ_KEY, RAII_VAR, sorcery_load_details::sorcery, and ast_sorcery::types.

1394 {
1395  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 }
#define OBJ_KEY
Definition: astobj2.h:1151
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244
const char * type
Type of object being loaded.
Definition: sorcery.c:247
Structure for registered object type.
Definition: sorcery.c:148
Structure for passing load/reload details.
Definition: sorcery.c:242
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

References ao2_alloc_with_lockobj, ast_sorcery_object::destructor, and ast_sorcery_object_details::object.

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
ao2_destructor_fn destructor
Optional object destructor.
Definition: sorcery.c:135
Structure for internal sorcery object information.
Definition: sorcery.c:127
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References __aco_option_register(), ao2_link, ast_alloca, ast_calloc, ast_copy_string(), ast_sorcery_object_field::multiple_handler, ast_sorcery_object_field::name, ast_sorcery_object_field::name_regex, OBJ_KEY, OPT_CUSTOM_T, RAII_VAR, and ast_sorcery::types.

Referenced by __ast_sorcery_object_register().

1161 {
1162 #define MAX_REGEX_ERROR_LEN 128
1163  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 OBJ_KEY
Definition: astobj2.h:1151
Type for a custom (user-defined) option handler.
Structure for registered object type.
Definition: sorcery.c:148
Structure for registered object field.
Definition: sorcery.c:205
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
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: astmm.h:288
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
#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
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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.

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

2324 {
2325  const struct ast_sorcery_object_details *details = object;
2326  return details->object->created;
2327 }
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct timeval created
Time that the object was created.
Definition: sorcery.c:141
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

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 * next
Structure for variables, used for configurations and for channel variables.
struct ast_variable * extended
Extended object fields.
Definition: sorcery.c:138
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

Referenced by ast_bucket_file_json(), ast_bucket_json(), ast_mwi_mailbox_get_id(), ast_mwi_mailbox_update(), ast_sorcery_is_stale(), ast_sorcery_object_id_hash(), ast_sorcery_object_id_sort(), chan_pjsip_indicate(), chan_pjsip_new(), change_outgoing_sdp_stream_media_address(), create_outgoing_sdp_stream(), create_rtp(), sorcery_memory_cmp(), sorcery_memory_hash(), t38_initialize_session(), and users_apply_handler().

2318 {
2319  const struct ast_sorcery_object_details *details = object;
2320  return details->object->id;
2321 }
char * id
Unique identifier of this object.
Definition: sorcery.c:129
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

Referenced by ast_sorcery_diff().

2330 {
2331  const struct ast_sorcery_object_details *details = object;
2332  return details->object->type;
2333 }
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

2378 {
2379  const struct ast_sorcery_object_details *details = object;
2380 
2381  return details->object->has_dynamic_contents;
2382 }
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
unsigned int has_dynamic_contents
Whether this object has dynamic contents or not.
Definition: sorcery.c:144
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

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 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
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.
struct ast_taskprocessor * serializer
Serializer for observers.
Definition: sorcery.c:183
Structure for registered object type.
Definition: sorcery.c:148
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct aco_type type
Type details.
Definition: sorcery.c:177
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
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.

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

Referenced by ast_bucket_init().

1129 {
1130  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
1131 
1132  if (!object_type) {
1133  return;
1134  }
1135 
1136  object_type->copy = copy;
1137 }
#define OBJ_KEY
Definition: astobj2.h:1151
static int copy(char *infile, char *outfile)
Utility function to copy a file.
Structure for registered object type.
Definition: sorcery.c:148
struct aco_type type
Type details.
Definition: sorcery.c:177
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

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

1140 {
1141  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
1142 
1143  if (!object_type) {
1144  return;
1145  }
1146 
1147  object_type->diff = diff;
1148 }
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for registered object type.
Definition: sorcery.c:148
sorcery_diff_handler diff
Optional object diff callback.
Definition: sorcery.c:162
struct aco_type type
Type details.
Definition: sorcery.c:177
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

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

2350 {
2351  RAII_VAR(struct ast_variable *, field, NULL, ast_variables_destroy);
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 }
struct ast_variable * next
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
Structure for variables, used for configurations and for channel variables.
struct ast_variable * extended
Extended object fields.
Definition: sorcery.c:138
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
#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
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

2385 {
2386  const struct ast_sorcery_object_details *details = object;
2387 
2388  details->object->has_dynamic_contents = 1;
2389 }
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
unsigned int has_dynamic_contents
Whether this object has dynamic contents or not.
Definition: sorcery.c:144
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ao2_unlink_flags, OBJ_NOLOCK, OBJ_SEARCH_KEY, ast_sorcery_object_type::type, aco_type::type, and ast_sorcery::types.

1062 {
1063  struct ast_sorcery_object_type *object_type;
1064  int res = -1;
1065 
1066  ao2_wrlock(sorcery->types);
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  }
1072  ao2_unlock(sorcery->types);
1073 
1074  /* XXX may need to add an instance unregister observer callback on success. */
1075 
1076  ao2_cleanup(object_type);
1077  return res;
1078 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
Assume that the ao2_container is already locked.
Definition: astobj2.h:1063
enum aco_type_t type
Structure for registered object type.
Definition: sorcery.c:148
struct aco_type type
Type details.
Definition: sorcery.c:177
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#define ao2_unlink_flags(container, obj, flags)
Remove an object from a container.
Definition: astobj2.h:1600
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.

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

Referenced by ast_ari_asterisk_update_object(), ast_sorcery_copy(), create_object(), and sorcery_astdb_retrieve_fields_common().

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 }
struct ast_variable * next
char * id
Unique identifier of this object.
Definition: sorcery.c:129
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for variables, used for configurations and for channel variables.
Structure for registered object type.
Definition: sorcery.c:148
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
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.
#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
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_ref, AST_HANDLER_ONLY_LIST, AST_HANDLER_ONLY_STRING, AST_HANDLER_PREFER_LIST, AST_HANDLER_PREFER_STRING, ast_variable_list_append_hint(), OBJ_KEY, ast_sorcery_object_details::object, RAII_VAR, ast_sorcery_object::type, and ast_sorcery::types.

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;
1543  case AST_HANDLER_ONLY_LIST:
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 }
Try both handlers, list first.
Definition: sorcery.h:134
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for variables, used for configurations and for channel variables.
Use list handler only.
Definition: sorcery.h:140
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
Structure for registered object type.
Definition: sorcery.c:148
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Structure for registered object field.
Definition: sorcery.c:205
Use string handler only.
Definition: sorcery.h:137
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
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821
Try both handlers, string first.
Definition: sorcery.h:131
#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
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

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

Referenced by ast_bucket_file_json(), and ast_bucket_json().

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))) {
1587  ast_variables_destroy(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 
1601  ast_variables_destroy(tmp);
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)
1607  || !(value = ast_json_string_create(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 }
struct ast_variable * next
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
void ast_json_unref(struct ast_json *value)
Decrease refcount on value. If refcount reaches zero, value is freed.
Definition: json.c:73
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for variables, used for configurations and for channel variables.
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
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
Structure for registered object type.
Definition: sorcery.c:148
struct ast_json * ast_json_string_create(const char *value)
Construct a JSON string from value.
Definition: json.c:278
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Structure for registered object field.
Definition: sorcery.c:205
#define ast_debug(level,...)
Log a DEBUG message.
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
struct ast_json * ast_json_object_create(void)
Create a new JSON object.
Definition: json.c:399
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821
Abstract JSON element (object, array, string, int, ...).
#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
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ao2_link, ao2_ref, ast_sorcery_object_type_observer::callbacks, OBJ_KEY, observer, RAII_VAR, and ast_sorcery::types.

Referenced by ast_bucket_file_observer_add(), ast_bucket_observer_add(), and pjsip_outbound_registration_metrics_init().

2392 {
2393  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 }
#define OBJ_KEY
Definition: astobj2.h:1151
Structure for registered object type observer.
Definition: sorcery.c:190
Structure for registered object type.
Definition: sorcery.c:148
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
static struct sorcery_test_observer observer
Global scope observer structure for testing.
Definition: test_sorcery.c:181
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
const struct ast_sorcery_observer * callbacks
Pointer to the observer implementation.
Definition: sorcery.c:192
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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.

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

Referenced by ast_bucket_file_observer_remove(), ast_bucket_observer_remove(), and pjsip_outbound_registration_metrics_init().

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 }
#define OBJ_KEY
Definition: astobj2.h:1151
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
static int sorcery_observer_remove(void *obj, void *arg, int flags)
Internal callback function for removing an observer.
Definition: sorcery.c:2416
Structure for registered object type.
Definition: sorcery.c:148
Interface for a sorcery object type observer.
Definition: sorcery.h:332
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

References ao2_ref.

1474 {
1475  ao2_ref(sorcery, +1);
1476 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.

References ao2_callback, ast_sorcery::module_name, OBJ_NODATA, ast_sorcery::observers, sorcery_load_details::sorcery, and ast_sorcery::types.

1409 {
1410  struct sorcery_load_details details = {
1411  .sorcery = sorcery,
1412  .reload = 1,
1413  };
1414 
1415  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loading,
1416  sorcery->module_name, sorcery, 1);
1417 
1418  ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
1419 
1420  NOTIFY_INSTANCE_OBSERVERS(sorcery->observers, instance_loaded,
1421  sorcery->module_name, sorcery, 1);
1422 
1423 }
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
struct ao2_container * observers
Observers.
Definition: sorcery.c:235
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244
Structure for passing load/reload details.
Definition: sorcery.c:242
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
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.

References OBJ_KEY, RAII_VAR, sorcery_load_details::sorcery, and ast_sorcery::types.

Referenced by load_users().

1443 {
1444  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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 }
#define OBJ_KEY
Definition: astobj2.h:1151
const struct ast_sorcery * sorcery
Sorcery structure in use.
Definition: sorcery.c:244
const char * type
Type of object being loaded.
Definition: sorcery.c:247
Structure for registered object type.
Definition: sorcery.c:148
Structure for passing load/reload details.
Definition: sorcery.c:242
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
#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
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.

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

Referenced by ast_aeap_client_configs_get(), ast_mwi_mailbox_get_all(), and load_users().

1898 {
1899  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
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)) {
1910  object = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, 0, NULL, NULL);
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 }
const struct ast_sorcery * sorcery
Pointer to the sorcery instance.
Definition: sorcery.c:1833
Structure used when calling create, update, or delete.
Definition: sorcery.c:1831
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
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
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
Return all matching objects.
Definition: sorcery.h:120
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
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
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
const char * type
Type of object being loaded.
Definition: sorcery.c:247
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
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
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
void * data
Unique data for the wizard.
Definition: sorcery.c:108
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
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.

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

Referenced by ast_ari_asterisk_delete_object(), ast_ari_asterisk_get_object(), ast_ari_asterisk_update_object(), ast_bucket_file_retrieve(), ast_bucket_retrieve(), ast_mwi_mailbox_get(), ast_mwi_mailbox_update(), chan_pjsip_devicestate(), create_rtp(), pjsip_acf_dial_contacts_read(), and t38_initialize_session().

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 }
const struct ast_sorcery * sorcery
Pointer to the sorcery instance.
Definition: sorcery.c:1833
Structure used when calling create, update, or delete.
Definition: sorcery.c:1831
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
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct aco_type type
Type details.
Definition: sorcery.c:177
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
struct ast_sorcery_object_wizards wizards
Wizard instances.
Definition: sorcery.c:165
void * data
Unique data for the wizard.
Definition: sorcery.c:108
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
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
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
char name[MAX_OBJECT_TYPE]
Unique name of the object type.
Definition: sorcery.c:150
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.

References ao2_weakproxy_find, and OBJ_SEARCH_KEY.

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

673 {
674  return ao2_weakproxy_find(instances, module_name, OBJ_SEARCH_KEY, "");
675 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
static struct ao2_container * instances
Registered sorcery instances.
Definition: sorcery.c:284
#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
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.

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

1990 {
1991  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
1992  struct ao2_container *objects;
1993  int i;
1994 
1995  if (!object_type) {
1996  return NULL;
1997  }
1998 
1999  objects = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, 0, NULL, NULL);
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 }
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
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
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
void * data
Unique data for the wizard.
Definition: sorcery.c:108
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
Generic container type.
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
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.

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

Referenced by ast_mwi_mailbox_get_by_regex().

1955 {
1956  RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
1957  struct ao2_container *objects;
1958  int i;
1959 
1960  if (!object_type) {
1961  return NULL;
1962  }
1963 
1964  objects = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_NOLOCK, 0, NULL, NULL);
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 }
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
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
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
struct ast_sorcery_internal_wizard * wizard
Wizard interface itself.
Definition: sorcery.c:105
Structure for registered object type.
Definition: sorcery.c:148
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
void * data
Unique data for the wizard.
Definition: sorcery.c:108
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
Generic container type.
#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
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
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.

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

Referenced by ast_ari_asterisk_update_object(), ast_bucket_file_update(), and ast_mwi_mailbox_update().

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 }
const struct ast_sorcery * sorcery
Pointer to the sorcery instance.
Definition: sorcery.c:1833
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
Structure used when calling create, update, or delete.
Definition: sorcery.c:1831
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
#define OBJ_KEY
Definition: astobj2.h:1151
#define AST_VECTOR_RW_UNLOCK(vec)
Unlock vector.
Definition: vector.h:897
#define AST_VECTOR_RW_RDLOCK(vec)
Obtain read lock on vector.
Definition: vector.h:877
Structure used for observer invocations.
Definition: sorcery.c:196
unsigned int caching
Wizard is acting as an object cache.
Definition: sorcery.c:111
struct ast_taskprocessor * serializer
Serializer for observers.
Definition: sorcery.c:183
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
Structure for registered object type.
Definition: sorcery.c:148
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ao2_container * types
Container for known object types.
Definition: sorcery.c:232
struct ast_sorcery_object_wizards wizards
Wizard instances.
Definition: sorcery.c:165
static int sorcery_observers_notify_update(void *data)
Internal callback function which notifies observers that an object has been updated.
Definition: sorcery.c:2125
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
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.
Structure for a wizard instance which operates on objects.
Definition: sorcery.c:103
#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
struct ast_sorcery_object_type * object_type
Pointer to the object type.
Definition: sorcery.c:198
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
char type[MAX_OBJECT_TYPE]
Type of object.
Definition: sorcery.c:132
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
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.

References ao2_link, ao2_ref, ast_sorcery_wizard::name, OBJ_SEARCH_KEY, and RAII_VAR.

545 {
546  RAII_VAR(struct ast_sorcery_internal_wizard *, wizard,
547  interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL,
548  ao2_cleanup);
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 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Structure for an internal wizard instance.
Definition: sorcery.c:89
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257
A wizard observer wrapper.
Definition: sorcery.c:276
#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
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
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.

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

570 {
571  RAII_VAR(struct ast_sorcery_internal_wizard *, wizard,
572  interface ? ao2_find(wizards, interface->name, OBJ_SEARCH_KEY) : NULL,
573  ao2_cleanup);
574 
575  if (wizard) {
576  ao2_callback(wizard->observers, OBJ_NODATA | OBJ_UNLINK, sorcery_generic_observer_remove, (void *)callbacks);
577  }
578 }
static int sorcery_generic_observer_remove(void *obj, void *arg, int flags)
Internal callback function for removing a generic observer.
Definition: sorcery.c:491
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
const char * name
Name of the wizard.
Definition: sorcery.h:278
Structure for an internal wizard instance.
Definition: sorcery.c:89
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257
#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
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.

References ao2_ref, ao2_unlink, ast_sorcery_internal_wizard::callbacks, and ast_sorcery_wizard::name.

Referenced by bucket_cleanup().

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 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
struct ao2_container * observers
Registered global observers.
Definition: sorcery.c:281
const char * name
Name of the wizard.
Definition: sorcery.h:278
struct ast_sorcery_wizard callbacks
Wizard interface itself.
Definition: sorcery.c:96
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
Structure for an internal wizard instance.
Definition: sorcery.c:89
#define ao2_unlink(container, obj)
Remove an object from a container.
Definition: astobj2.h:1578
static struct ao2_container * wizards
Registered sorcery wizards.
Definition: sorcery.c:257