96 #ifndef _ASTERISK_SORCERY_H
97 #define _ASTERISK_SORCERY_H
99 #if defined(__cplusplus) || defined(c_plusplus)
107 #define MAX_OBJECT_TYPE 64
110 #define MAX_OBJECT_FIELD 128
249 const char *wizard_args,
void *wizard_data);
253 const char *object_type);
257 const char *object_type,
int reloaded);
261 const char *object_type,
int reloaded);
268 const char *object_type,
int reloaded);
272 const char *object_type,
int reloaded);
284 void *(*open)(
const char *data);
296 void *(*retrieve_id)(
const struct ast_sorcery *sorcery,
void *data,
const char *type,
const char *id);
307 const size_t prefix_len);
319 int (*
delete)(
const struct ast_sorcery *sorcery,
void *data,
void *object);
356 #define SORCERY_OBJECT(details) \
358 struct ast_sorcery_object_details details; \
383 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)
406 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)
407 struct ast_sorcery *__ast_sorcery_open(
const char *module,
const char *file,
int line,
const char *func);
453 const char *name,
const char *module);
455 #define ast_sorcery_apply_config(sorcery, name) \
456 __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
474 const char *type,
const char *module,
const char *name,
const char *data);
476 #define ast_sorcery_apply_default(sorcery, type, name, data) \
477 __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
495 const char *type,
const char *module,
const char *name,
const char *data,
unsigned int caching);
510 #define ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching) \
511 __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));
518 AST_SORCERY_WIZARD_POSITION_LAST = -1,
519 AST_SORCERY_WIZARD_POSITION_FIRST = 0,
543 const char *type,
const char *module,
const char *name,
const char *data,
544 unsigned int caching,
int position);
562 #define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \
563 __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
564 (caching), (position))
615 const char *object_type_name,
const char *module,
const char *wizard_type_name,
646 #define ast_sorcery_object_type_insert_wizard(sorcery, \
647 object_type_name, wizard_type_name, wizard_args, flags, \
648 position, wizard, wizard_data) \
649 __ast_sorcery_object_type_insert_wizard((sorcery), \
650 (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
651 position, (wizard), (wizard_data))
678 #define ast_sorcery_object_type_apply_wizard(sorcery, \
679 object_type_name, wizard_type_name, wizard_args, flags, \
680 wizard, wizard_data) \
681 __ast_sorcery_object_type_insert_wizard((sorcery), \
682 (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
683 AST_SORCERY_WIZARD_POSITION_LAST, (wizard), (wizard_data))
704 const char *object_type_name,
const char *module,
const char *wizard_type_name,
705 const char *wizard_args);
724 #define ast_sorcery_object_type_remove_wizard(sorcery, object_type_name, \
725 wizard_type_name, wizard_args) \
726 __ast_sorcery_object_type_remove_wizard((sorcery), (object_type_name), \
727 AST_MODULE, (wizard_type_name), (wizard_args))
743 const char *type,
const char *module,
const char *name);
757 #define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
758 __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
837 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
838 __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
852 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
853 __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
867 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
868 __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
937 const char *name,
const char *default_val,
enum aco_option_type opt_type,
940 unsigned int alias,
size_t argc, ...);
955 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
956 __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
971 #define ast_sorcery_object_field_register_alias(sorcery, type, name, default_val, opt_type, flags, ...) \
972 __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
987 #define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
988 __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
1005 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1006 __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__);
1023 #define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1024 __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__);
1041 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1042 __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__);
1137 #define ast_sorcery_objectset_create(sorcery, object) \
1138 ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
1500 #define ast_sorcery_unref(sorcery) \
1501 ao2_cleanup(sorcery)
1615 const char *field_name);
1626 #if defined(__cplusplus) || defined(c_plusplus)
int(* aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj)
A callback function for handling a particular option.
Try both handlers, list first.
int(* sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf)
A callback function for translating a value into a string.
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.
int(* update)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for updating an object.
unsigned int ast_sorcery_object_has_dynamic_contents(const void *object)
Get whether an object contains dynamic contents or not.
ast_sorcery_field_handler_flags
Field handler flags.
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...
void(* deleted)(const void *object)
Callback for when an object is deleted.
int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object)
Determine if a sorcery object is stale with respect to its backing datastore.
void ast_sorcery_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 determin...
int ast_sorcery_instance_observer_add(struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
Add an observer to a sorcery instance.
void(* instance_created)(const char *name, struct ast_sorcery *sorcery)
Callback after an instance is created.
Interface for the global sorcery observer.
void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *interface, const struct ast_sorcery_wizard_observer *callbacks)
Remove an observer from a sorcery wizard.
int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module)
Register a sorcery wizard.
int(* sorcery_fields_handler)(const void *obj, struct ast_variable **fields)
A callback function for translating multiple values into an ast_variable list.
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.
char * module_name
Pointer to module_name in the associated sorcery_proxy.
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.
Structure for variables, used for configurations and for channel variables.
void(* created)(const void *object)
Callback for when an object is created.
Universally unique identifier support.
Perform no matching, return all objects.
int ast_sorcery_object_id_compare(void *obj, void *arg, int flags)
ao2 object comparator based on sorcery id.
void * ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj)
Allocate a generic sorcery capable object with locking.
int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler, sorcery_fields_handler sorcery_handler)
Register a regex for multiple fields within an object.
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.
Full structure for sorcery.
void(* wizard_registered)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback after an wizard is registered.
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.
static int copy(char *infile, char *outfile)
Utility function to copy a file.
Return all matching objects.
struct ao2_container * ast_sorcery_retrieve_by_prefix(const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len)
Retrieve multiple objects whose id begins with the specified prefix.
struct ast_module * module
Pointer to the Asterisk module this wizard is implemented by.
int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery, const char *type)
Return the number of wizards mapped to an object type.
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.
const char * name
Name of the wizard.
int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks)
Add a global observer to sorcery.
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.
int(* create)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for creating an object.
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.
ast_sorcery_retrieve_flags
Retrieval flags.
int ast_sorcery_init(void)
Initialize the sorcery API.
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.
void(* instance_loaded)(const char *name, const struct ast_sorcery *sorcery, int reloaded)
Callback after instance is loaded/reloaded.
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.
const char * ast_sorcery_object_get_type(const void *object)
Get the type of a sorcery object.
void(* close)(void *data)
Callback for closing a wizard.
void * ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id)
Retrieve an object using its unique identifier.
const char * ast_sorcery_get_module(const struct ast_sorcery *sorcery)
Get the module that has opened the provided sorcery instance.
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.
void(* wizard_mapped)(const char *name, struct ast_sorcery *sorcery, const char *object_type, struct ast_sorcery_wizard *wizard, const char *wizard_args, void *wizard_data)
Callback after a wizard is mapped to an object_type.
ast_sorcery_wizard_position
Pre-defined locations to insert at.
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.
void(* wizard_loaded)(const char *name, const struct ast_sorcery_wizard *wizard, const char *object_type, int reloaded)
Callback after a wizard is loaded/reloaded for any type.
void(* object_type_registered)(const char *name, struct ast_sorcery *sorcery, const char *object_type)
Callback after any object_type is registered.
void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks)
Remove a global observer from sorcery.
const struct timeval ast_sorcery_object_get_created(const void *object)
Get when the sorcery object was created.
const char * ast_sorcery_object_get_extended(const void *object, const char *name)
Get an extended field value from a sorcery object.
int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object)
Create and potentially persist an object using an available wizard.
ast_sorcery_wizard_apply_flags
Wizard Apply Flags.
void *(* aco_type_item_alloc)(const char *category)
Allocate a configurable ao2 object.
Structure for registered object type.
int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type)
Unregister an object type.
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.
Interface for the sorcery instance observer.
int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags)
ao2 object sorter based on sorcery id.
const char * ast_sorcery_object_get_id(const void *object)
Get the unique identifier of a sorcery object.
Structure for internal sorcery object information.
int(* sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes)
A callback function for generating a changeset between two objects.
struct aco_type type
Type details.
void(* instance_destroying)(const char *name, struct ast_sorcery *sorcery)
Callback before an instance is destroyed.
aco_option_type
The option types.
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.
void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
Remove an observer from a sorcery instance.
int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks)
Add an observer to a specific object type.
Configuration option-handling.
int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object)
Delete an object.
Structure which contains details about a sorcery object.
int(* sorcery_copy_handler)(const void *src, void *dst)
A callback function for copying the contents of one object to another.
void ast_sorcery_force_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects, even if no changes determined.
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.
int ast_sorcery_wizard_observer_add(struct ast_sorcery_wizard *wizard, const struct ast_sorcery_wizard_observer *callbacks)
Add an observer to a sorcery wizard.
void(* force_reload)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for forcing a reload to occur, even if wizard has determined no changes...
int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface)
Unregister a sorcery wizard.
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.
Interface for a sorcery object type observer.
struct ast_sorcery * ast_sorcery_retrieve_by_module_name(const char *module_name)
Retrieves an existing sorcery instance by module name.
void(* ao2_destructor_fn)(void *vdoomed)
Typedef for an object destructor.
void(* wizard_loading)(const char *name, const struct ast_sorcery_wizard *wizard, const char *object_type, int reloaded)
Callback before a wizard is loaded/reloaded for any type.
void * ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id)
Allocate an object.
enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module)
Apply configured wizard mappings.
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.
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.
struct ast_variable *(* sorcery_transform_handler)(struct ast_variable *set)
A callback function for performing a transformation on an object set.
void(* loaded)(const char *object_type)
Callback for when an object type is loaded/reloaded.
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.
Interface for a sorcery wizard.
void ast_sorcery_load(const struct ast_sorcery *sorcery)
Inform any wizards to load persistent objects.
void ast_sorcery_object_set_has_dynamic_contents(const void *object)
Set the dynamic contents flag on a sorcery object.
void ast_sorcery_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects.
void(* object_type_loaded)(const char *name, const struct ast_sorcery *sorcery, const char *object_type, int reloaded)
Callback after any object_type is loaded/reloaded.
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.
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.
Interface for the sorcery wizard observer.
void * ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object)
Create a copy of an object.
int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value)
Set an extended field value on a sorcery object.
int ast_sorcery_object_id_hash(const void *obj, int flags)
ao2 object hasher based on sorcery id.
Try both handlers, string first.
void(* load)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for loading persistent objects.
Abstract JSON element (object, array, string, int, ...).
struct ast_json * ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object)
Create an object set in JSON format for an object.
int(* is_stale)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for whether or not the wizard believes the object is stale.
void(* reload)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for reloading persistent objects.
void ast_sorcery_ref(struct ast_sorcery *sorcery)
Increase the reference count of a sorcery structure.
void * ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor)
Allocate a generic sorcery capable object.
int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name)
Remove an object wizard mapping.
int __ast_sorcery_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.
void(* instance_loading)(const char *name, const struct ast_sorcery *sorcery, int reloaded)
Callback before instance is loaded/reloaded.
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.
void(* wizard_unregistering)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback before a wizard is unregistered.
void(* updated)(const void *object)
Callback for when an object is updated.
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.
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.
void(* object_type_loading)(const char *name, const struct ast_sorcery *sorcery, const char *object_type, int reloaded)
Callback before any object_type is loaded/reloaded.
int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object)
Update an object.
struct ast_sorcery_object * object
Pointer to internal sorcery object information.