Asterisk - The Open Source Telephony Project  GIT-master-a24979a
sorcery.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012 - 2013, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief Sorcery Data Access Layer API
21  * \author Joshua Colp <jcolp@digium.com>
22  * \ref AstSorcery
23  */
24 
25 /*!
26  * \page AstSorcery Data Access Layer API
27  *
28  * Sorcery is a unifying data access layer which utilizes the configuration framework,
29  * realtime, and astdb to allow object creation, retrieval, updating, and deletion.
30  *
31  * \par Initialization
32  *
33  * Usage of sorcery is accomplished by first opening a sorcery structure. This structure holds
34  * all information about the object types, object fields, and object mappings. All API functions
35  * require the sorcery structure to operate. When sorcery is no longer needed the structure can
36  * be unreferenced using \ref ast_sorcery_unref
37  *
38  * Once opened the sorcery structure must have object mappings applied to it. This maps the
39  * object types to their respective wizards (object storage modules). If the developer would like
40  * to allow the user to configure this using the sorcery.conf configuration file the
41  * \ref ast_sorcery_apply_config API call can be used to read in the configuration file and apply the
42  * mappings. \ref ast_sorcery_open will automatically call \ref ast_sorcery_apply_config to allow
43  * for configuration of objects using the same category name as the module that is opening the
44  * sorcery instance. Direct calls to \ref ast_sorcery_apply_config should only be performed if a
45  * module wishes to allow for additional configuration sections in sorcery.conf to be used.
46  * If the storage of the object types are such that a default wizard can be used this can
47  * be applied using the \ref ast_sorcery_apply_default API call. Note that the default mappings will not
48  * override configured mappings. They are only used in the case where no configured mapping exists.
49  *
50  * Configuring object mappings implicitly creates a basic version of an object type. The object type
51  * must be fully registered, however, using the \ref ast_sorcery_object_register API call before any
52  * objects of the type can be allocated, created, or retrieved.
53  *
54  * Once the object type itself has been fully registered the individual fields within the object must
55  * be registered using the \ref ast_sorcery_object_field_register API call. Note that not all fields *need*
56  * be registered. Only fields that should be accessible using the sorcery API have to be registered.
57  *
58  * \par Creating Objects
59  *
60  * Before an object can be created within the sorcery API it must first be allocated using the
61  * \ref ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific
62  * details, and applies default values to the object. A unique identifier can optionally be specified
63  * when allocating an object. If it is not provided one will be automatically generated. Allocating
64  * an object does not create it within any object storage mechanisms that are configured for the
65  * object type. Creation must explicitly be done using the \ref ast_sorcery_create API call. This API call
66  * passes the object to each configured object storage mechanism for the object type until one
67  * successfully persists the object.
68  *
69  * \par Retrieving Objects
70  *
71  * To retrieve a single object using its unique identifier the \ref ast_sorcery_retrieve_by_id API call
72  * can be used.
73  *
74  * To retrieve potentially multiple objects using specific fields the \ref ast_sorcery_retrieve_by_fields
75  * API call can be used. The behavior of this API call is controlled using different flags. If the
76  * AST_RETRIEVE_FLAG_MULTIPLE flag is used a container will be returned which contains all matching objects.
77  * To retrieve all objects the AST_RETRIEVE_FLAG_ALL flag can be specified. Note that when specifying this flag
78  * you do not need to pass any fields.
79  *
80  * Both API calls return shared objects. Modification of the object can not occur until it has been copied.
81  *
82  * \par Updating Objects
83  *
84  * As retrieved objects may be shared the first step to updating the object with new details is creating a
85  * copy using the \ref ast_sorcery_copy API call. This will return a new object which is specific to the caller.
86  * Any field within the object may be modified as needed. Once changes are done the changes can be committed
87  * using the \ref ast_sorcery_update API call. Note that as the copied object is specific to the caller it must
88  * be unreferenced after use.
89  *
90  * \par Deleting Objects
91  *
92  * To delete an object simply call the \ref ast_sorcery_delete API call with an object retrieved using the
93  * ast_sorcery_retrieve_by_* API calls or a copy returned from \ref ast_sorcery_copy.
94  */
95 
96 #ifndef _ASTERISK_SORCERY_H
97 #define _ASTERISK_SORCERY_H
98 
99 #if defined(__cplusplus) || defined(c_plusplus)
100 extern "C" {
101 #endif
102 
103 #include "asterisk/config_options.h"
104 #include "asterisk/uuid.h"
105 
106 /*! \brief Maximum size of an object type */
107 #define MAX_OBJECT_TYPE 64
108 
109 /*! \brief Maximum length of an object field name */
110 #define MAX_OBJECT_FIELD 128
111 
112 /*!
113  * \brief Retrieval flags
114  */
116  /*! \brief Default retrieval flags */
118 
119  /*! \brief Return all matching objects */
121 
122  /*! \brief Perform no matching, return all objects */
124 };
125 
126 /*!
127  * \brief Field handler flags
128  */
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 };
142 
143 
144 /*! \brief Forward declaration for the sorcery main structure and wizard structure */
145 struct ast_sorcery;
146 struct ast_sorcery_wizard;
147 
148 /*!
149  * \brief A callback function for translating a value into a string
150  *
151  * \param obj Object to get value from
152  * \param args Where the field is
153  * \param buf Pointer to the buffer that the handler has created which contains the field value
154  *
155  * \retval 0 success
156  * \retval -1 failure
157  */
158 typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
159 
160 /*!
161  * \brief A callback function for translating multiple values into an ast_variable list
162  *
163  * \param obj Object to get values from
164  * \param fields Pointer to store the list of fields
165  *
166  * \retval 0 success
167  * \retval -1 failure
168  */
169 typedef int (*sorcery_fields_handler)(const void *obj, struct ast_variable **fields);
170 
171 /*!
172  * \brief A callback function for performing a transformation on an object set
173  *
174  * \param set The existing object set
175  *
176  * \retval non-NULL new object set if changed
177  * \retval NULL if no changes present
178  *
179  * \note The returned ast_variable list must be *new*. You can not return the input set.
180  */
181 typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
182 
183 /*!
184  * \brief A callback function for when an object set is successfully applied to an object
185  *
186  * \note On a failure return, the state of the object is left undefined. It is a bad
187  * idea to try to use this object.
188  *
189  * \param sorcery Sorcery structure in use
190  * \param obj The object itself
191  * \retval 0 Success
192  * \retval non-zero Failure
193  */
194 typedef int (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
195 
196 /*!
197  * \brief A callback function for copying the contents of one object to another
198  *
199  * \param src The source object
200  * \param dst The destination object
201  *
202  * \retval 0 success
203  * \retval -1 failure
204  */
205 typedef int (*sorcery_copy_handler)(const void *src, void *dst);
206 
207 /*!
208  * \brief A callback function for generating a changeset between two objects
209  *
210  * \param original The original object
211  * \param modified The modified object
212  * \param changes The changeset
213  *
214  * \retval 0 success
215  * \retval -1 failure
216  */
217 typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
218 
219 /*! \brief Interface for the global sorcery observer */
221  /*! \brief Callback after an instance is created */
222  void (*instance_created)(const char *name, struct ast_sorcery *sorcery);
223 
224  /*! \brief Callback after an wizard is registered */
225  void (*wizard_registered)(const char *name,
226  const struct ast_sorcery_wizard *wizard);
227 
228  /*! \brief Callback before an instance is destroyed */
229  void (*instance_destroying)(const char *name, struct ast_sorcery *sorcery);
230 
231  /*! \brief Callback before a wizard is unregistered */
232  void (*wizard_unregistering)(const char *name,
233  const struct ast_sorcery_wizard *wizard);
234 };
235 
236 /*! \brief Interface for the sorcery instance observer */
238  /*! \brief Callback before instance is loaded/reloaded */
239  void (*instance_loading)(const char *name, const struct ast_sorcery *sorcery,
240  int reloaded);
241 
242  /*! \brief Callback after instance is loaded/reloaded */
243  void (*instance_loaded)(const char *name, const struct ast_sorcery *sorcery,
244  int reloaded);
245 
246  /*! \brief Callback after a wizard is mapped to an object_type */
247  void (*wizard_mapped)(const char *name, struct ast_sorcery *sorcery,
248  const char *object_type, struct ast_sorcery_wizard *wizard,
249  const char *wizard_args, void *wizard_data);
250 
251  /*! \brief Callback after any object_type is registered */
252  void (*object_type_registered)(const char *name, struct ast_sorcery *sorcery,
253  const char *object_type);
254 
255  /*! \brief Callback before any object_type is loaded/reloaded */
256  void (*object_type_loading)(const char *name, const struct ast_sorcery *sorcery,
257  const char *object_type, int reloaded);
258 
259  /*! \brief Callback after any object_type is loaded/reloaded */
260  void (*object_type_loaded)(const char *name, const struct ast_sorcery *sorcery,
261  const char *object_type, int reloaded);
262 };
263 
264 /*! \brief Interface for the sorcery wizard observer */
266  /*! \brief Callback before a wizard is loaded/reloaded for any type */
267  void (*wizard_loading)(const char *name, const struct ast_sorcery_wizard *wizard,
268  const char *object_type, int reloaded);
269 
270  /*! \brief Callback after a wizard is loaded/reloaded for any type */
271  void (*wizard_loaded)(const char *name, const struct ast_sorcery_wizard *wizard,
272  const char *object_type, int reloaded);
273 };
274 
275 /*! \brief Interface for a sorcery wizard */
277  /*! \brief Name of the wizard */
278  const char *name;
279 
280  /*! \brief Pointer to the Asterisk module this wizard is implemented by */
282 
283  /*! \brief Callback for opening a wizard */
284  void *(*open)(const char *data);
285 
286  /*! \brief Optional callback for loading persistent objects */
287  void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
288 
289  /*! \brief Optional callback for reloading persistent objects */
290  void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
291 
292  /*! \brief Callback for creating an object */
293  int (*create)(const struct ast_sorcery *sorcery, void *data, void *object);
294 
295  /*! \brief Callback for retrieving an object using an id */
296  void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
297 
298  /*! \brief Callback for retrieving multiple objects using a regex on their id */
299  void (*retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
300 
301  /*! \brief Optional callback for retrieving multiple objects by matching their id with a prefix */
302  void (*retrieve_prefix)(const struct ast_sorcery *sorcery,
303  void *data,
304  const char *type,
305  struct ao2_container *objects,
306  const char *prefix,
307  const size_t prefix_len);
308 
309  /*! \brief Optional callback for retrieving an object using fields */
310  void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
311 
312  /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
313  void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
314 
315  /*! \brief Callback for updating an object */
316  int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
317 
318  /*! \brief Callback for deleting an object */
319  int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
320 
321  /*! \brief Callback for closing a wizard */
322  void (*close)(void *data);
323 
324  /*! \brief Callback for whether or not the wizard believes the object is stale */
325  int (*is_stale)(const struct ast_sorcery *sorcery, void *data, void *object);
326 
327  /*! \brief Optional callback for forcing a reload to occur, even if wizard has determined no changes */
328  void (*force_reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
329 };
330 
331 /*! \brief Interface for a sorcery object type observer */
333  /*! \brief Callback for when an object is created */
334  void (*created)(const void *object);
335 
336  /*! \brief Callback for when an object is updated */
337  void (*updated)(const void *object);
338 
339  /*! \brief Callback for when an object is deleted */
340  void (*deleted)(const void *object);
341 
342  /*! \brief Callback for when an object type is loaded/reloaded */
343  void (*loaded)(const char *object_type);
344 };
345 
346 /*! \brief Opaque structure for internal sorcery object */
347 struct ast_sorcery_object;
348 
349 /*! \brief Structure which contains details about a sorcery object */
351  /*! \brief Pointer to internal sorcery object information */
353 };
354 
355 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
356 #define SORCERY_OBJECT(details) \
357 struct { \
358  struct ast_sorcery_object_details details; \
359 } \
360 
361 /*!
362  * \brief Initialize the sorcery API
363  *
364  * \retval 0 success
365  * \retval -1 failure
366  */
367 int ast_sorcery_init(void);
368 
369 /*!
370  * \brief Register a sorcery wizard
371  *
372  * \param interface Pointer to a wizard interface
373  * \param module Pointer to the module implementing the interface
374  *
375  * \retval 0 success
376  * \retval -1 failure
377  */
378 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
379 
380 /*!
381  * \brief See \ref __ast_sorcery_wizard_register()
382  */
383 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)
384 
385 /*!
386  * \brief Unregister a sorcery wizard
387  *
388  * \param interface Pointer to the wizard interface
389  *
390  * \retval 0 success
391  * \retval -1 failure
392  */
393 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
394 
395 /*!
396  * \brief Open a new sorcery structure
397  *
398  * \param module The module name (AST_MODULE)
399  *
400  * When called, this will automatically also call __ast_sorcery_apply_config()
401  * with the module name as the configuration section.
402  *
403  * \retval non-NULL success
404  * \retval NULL if allocation failed
405  */
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);
408 
409 /*!
410  * \brief Retrieves an existing sorcery instance by module name
411  *
412  * \param module_name The module name
413  *
414  * \retval non-NULL success
415  * \retval NULL if no instance was found
416  *
417  * \note The returned instance has its reference count incremented. The caller
418  * must decrement the count when they're finished with it.
419  *
420  */
422 
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 };
435 
436 /*!
437  * \brief Apply configured wizard mappings
438  *
439  * \param sorcery Pointer to a sorcery structure
440  * \param name Name of the category to use within the configuration file, normally the module name
441  * \param module The module name (AST_MODULE)
442  *
443  * This function is called automatically by __ast_sorcery_open() using the module name as the
444  * configuration category. The only reason you should call this function is if your module
445  * wishes to apply configuration from additional sections of sorcery.conf.
446  *
447  * If a configuration section attempts to apply the same sorcery wizard to an object type
448  * more than once, the wizard will only be applied one time.
449  *
450  * \return What happened when attempting to apply the config.
451  */
453  const char *name, const char *module);
454 
455 #define ast_sorcery_apply_config(sorcery, name) \
456  __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
457 
458 /*!
459  * \brief Apply default object wizard mappings
460  *
461  * \param sorcery Pointer to a sorcery structure
462  * \param type Type of object to apply to
463  * \param module The name of the module, typically AST_MODULE
464  * \param name Name of the wizard to use
465  * \param data Data to be passed to wizard
466  *
467  * \return What occurred when applying the default
468  *
469  * \note This should be called *after* applying configuration sourced mappings
470  *
471  * \note Only a single default can exist per object type
472  */
474  const char *type, const char *module, const char *name, const char *data);
475 
476 #define ast_sorcery_apply_default(sorcery, type, name, data) \
477  __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
478 
479 
480 /*!
481  * \brief Apply additional object wizard mappings
482  *
483  * \param sorcery Pointer to a sorcery structure
484  * \param type Type of object to apply to
485  * \param module The name of the module, typically AST_MODULE
486  * \param name Name of the wizard to use
487  * \param data Data to be passed to wizard
488  * \param caching Wizard should cache
489  *
490  * \return What occurred when applying the mapping
491  *
492  * \note This should be called *after* applying default mappings
493  */
495  const char *type, const char *module, const char *name, const char *data, unsigned int caching);
496 
497 /*!
498  * \brief Apply additional object wizard mappings
499  *
500  * \param sorcery Pointer to a sorcery structure
501  * \param type Type of object to apply to
502  * \param name Name of the wizard to use
503  * \param data Data to be passed to wizard
504  * \param caching Wizard should cache
505  *
506  * \return What occurred when applying the mapping
507  *
508  * \note This should be called *after* applying default mappings
509  */
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));
512 
513 
514 /*!
515  * \brief Pre-defined locations to insert at
516  */
520 };
521 
522 /*!
523  * \brief Insert an additional object wizard mapping at a specific position
524  * in the wizard list
525  *
526  * \param sorcery Pointer to a sorcery structure
527  * \param type Type of object to apply to
528  * \param module The name of the module, typically AST_MODULE
529  * \param name Name of the wizard to use
530  * \param data Data to be passed to wizard
531  * \param caching Wizard should cache
532  * \param position An index to insert to or one of ast_sorcery_wizard_position
533  *
534  * \return What occurred when applying the mapping
535  *
536  * \note This should be called *after* applying default mappings
537  * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count
538  * and iterating over them using ast_sorcery_get_wizard_mapping.
539  *
540  * \since 13.4.0
541  */
543  const char *type, const char *module, const char *name, const char *data,
544  unsigned int caching, int position);
545 
546 /*!
547  * \brief Insert an additional object wizard mapping at a specific position
548  * in the wizard list
549  *
550  * \param sorcery Pointer to a sorcery structure
551  * \param type Type of object to apply to
552  * \param name Name of the wizard to use
553  * \param data Data to be passed to wizard
554  * \param caching Wizard should cache
555  * \param position One of ast_sorcery_wizard_position
556  *
557  * \return What occurred when applying the mapping
558  *
559  * \note This should be called *after* applying default mappings
560  * \since 13.4.0
561  */
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))
565 
566 /*!
567  * \brief Wizard Apply Flags
568  *
569  * These flags apply only to a wizard/object-type combination.
570  * The same wizard may be applied to a different object-type with
571  * different flags and behavior. If ALLOW_DUPLICATE is set
572  * the wizard could even be applied to the same object-type
573  * with different flags.
574  */
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 };
585 
586 /*!
587  * \brief Insert an additional object wizard mapping at a specific position
588  * in the wizard list returning wizard information
589  * \since 13.26.0
590  * \since 16.3.0
591  *
592  * \param sorcery Pointer to a sorcery structure
593  * \param object_type_name Name of the object type to apply to
594  * \param module The name of the module, typically AST_MODULE
595  * \param wizard_type_name Name of the wizard type to use
596  * \param wizard_args Opaque string to be passed to the wizard
597  * May be NULL but see note below
598  * \param flags One or more of enum ast_sorcery_wizard_apply_flags
599  * \param position An index to insert to or one of ast_sorcery_wizard_position
600  * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
601  * May be NULL if not needed.
602  * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
603  * May be NULL if not needed.
604  *
605  * \return What occurred when applying the mapping
606  *
607  * \note This should be called *after* applying default mappings
608  *
609  * \note Although \p wizard_args is an optional parameter it is highly
610  * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
611  * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
612  * to remove specific instances of a wizard type.
613  */
615  const char *object_type_name, const char *module, const char *wizard_type_name,
616  const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position,
617  struct ast_sorcery_wizard **wizard, void **wizard_data);
618 
619 /*!
620  * \brief Insert an additional object wizard mapping at a specific position
621  * in the wizard list returning wizard information
622  * \since 13.26.0
623  * \since 16.3.0
624  *
625  * \param sorcery Pointer to a sorcery structure
626  * \param object_type_name Name of the object type to apply to
627  * \param wizard_type_name Name of the wizard type to use
628  * \param wizard_args Opaque string to be passed to the wizard
629  * May be NULL but see note below
630  * \param flags One or more of enum ast_sorcery_wizard_apply_flags
631  * \param position An index to insert to or one of ast_sorcery_wizard_position
632  * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
633  * May be NULL if not needed.
634  * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
635  * May be NULL if not needed.
636  *
637  * \return What occurred when applying the mapping
638  *
639  * \note This should be called *after* applying default mappings
640  *
641  * \note Although \p wizard_args is an optional parameter it is highly
642  * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
643  * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
644  * to remove specific instances.
645  */
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))
652 
653 /*!
654  * \brief Apply additional object wizard mappings returning wizard information
655  * \since 13.26.0
656  * \since 16.3.0
657  *
658  * \param sorcery Pointer to a sorcery structure
659  * \param object_type_name Name of the object type to apply to
660  * \param wizard_type_name Name of the wizard type to use
661  * \param wizard_args Opaque string to be passed to the wizard
662  * May be NULL but see note below
663  * \param flags One or more of enum ast_sorcery_wizard_apply_flags
664  * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
665  * May be NULL if not needed.
666  * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
667  * May be NULL if not needed.
668  *
669  * \return What occurred when applying the mapping
670  *
671  * \note This should be called *after* applying default mappings
672  *
673  * \note Although \p wizard_args is an optional parameter it is highly
674  * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
675  * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
676  * to remove specific instances.
677  */
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))
684 
685 /*!
686  * \brief Remove an object wizard mapping
687  * \since 13.26.0
688  * \since 16.3.0
689  *
690  * \param sorcery Pointer to a sorcery structure
691  * \param object_type_name Name of the object type to remove from
692  * \param module The name of the module, typically AST_MODULE
693  * \param wizard_type_name The name of the of the wizard type to remove
694  * \param wizard_args Opaque string originally passed to the wizard
695  *
696  * \retval 0 success
697  * \retval -1 failure
698  *
699  * \note If there were multiple instances of the same wizard type
700  * added to this object type without using \p wizard_args, then
701  * only the first wizard matching wizard_type will be removed.
702  */
704  const char *object_type_name, const char *module, const char *wizard_type_name,
705  const char *wizard_args);
706 
707 /*!
708  * \brief Remove an object wizard mapping
709  * \since 13.26.0
710  * \since 16.3.0
711  *
712  * \param sorcery Pointer to a sorcery structure
713  * \param object_type_name Name of the object type to remove from
714  * \param wizard_type_name The name of the of the wizard type to remove
715  * \param wizard_args Opaque string originally passed to the wizard
716  *
717  * \retval 0 success
718  * \retval -1 failure
719  *
720  * \note If there were multiple instances of the same wizard type
721  * added to this object type without using \p wizard_args, then
722  * only the first wizard matching wizard_type will be removed.
723  */
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))
728 
729 /*!
730  * \brief Remove an object wizard mapping
731  *
732  * \param sorcery Pointer to a sorcery structure
733  * \param type Type of object to remove from
734  * \param module The name of the module, typically AST_MODULE
735  * \param name The name of the wizard to remove
736  *
737  * \retval 0 success
738  * \retval -1 failure
739  *
740  * \since 13.4.0
741  */
743  const char *type, const char *module, const char *name);
744 
745 /*!
746  * \brief Remove an object wizard mapping
747  *
748  * \param sorcery Pointer to a sorcery structure
749  * \param type Type of object to remove from
750  * \param name The name of the wizard to remove
751  *
752  * \retval 0 success
753  * \retval -1 failure
754  *
755  * \since 13.4.0
756  */
757 #define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
758  __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
759 
760 /*!
761  * \brief Return the number of wizards mapped to an object type
762  *
763  * \param sorcery Pointer to a sorcery structure
764  * \param type Type of object
765  *
766  * \return Number of wizards or -1 for error
767  * \since 13.4.0
768  */
770  const char *type);
771 
772 /*!
773  * \brief By index, return a wizard mapped to an object type
774  *
775  * \param sorcery Pointer to a sorcery structure
776  * \param type Type of object
777  * \param index Index of the wizard
778  * \param wizard A pointer to receive the wizard pointer
779  * \param data A pointer to receive the data pointer
780  *
781  * \retval 0 success
782  * \retval -1 failure
783  *
784  * \warning The wizard will have its reference count bumped so you must
785  * call ao2_cleanup when you're done with it.
786  *
787  * \note The wizard and data returned are valid only for this object type
788  * and only while the wizard is applied to the object type.
789  *
790  * \since 13.4.0
791  */
793  const char *type, int index, struct ast_sorcery_wizard **wizard, void **data);
794 
795 /*!
796  * \brief Unregister an object type
797  *
798  * \param sorcery Pointer to a sorcery structure
799  * \param type Type of object
800  *
801  * \retval 0 success
802  * \retval -1 failure
803  */
804 int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type);
805 
806 /*!
807  * \brief Register an object type
808  *
809  * \param sorcery Pointer to a sorcery structure
810  * \param type Type of object
811  * \param hidden All objects of this type are internal and should not be manipulated by users
812  * \param reloadable All objects of this type are reloadable
813  * \param alloc Required object allocation callback
814  * \param transform Optional transformation callback
815  * \param apply Optional object set apply callback
816  *
817  * \note In general, this function should not be used directly. One of the various
818  * macro'd versions should be used instead.
819  *
820  * \retval 0 success
821  * \retval -1 failure
822  */
823 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);
824 
825 /*!
826  * \brief Register an object type
827  *
828  * \param sorcery Pointer to a sorcery structure
829  * \param type Type of object
830  * \param alloc Required object allocation callback
831  * \param transform Optional transformation callback
832  * \param apply Optional object set apply callback
833  *
834  * \retval 0 success
835  * \retval -1 failure
836  */
837 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
838  __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
839 
840 /*!
841  * \brief Register an object type that is not reloadable
842  *
843  * \param sorcery Pointer to a sorcery structure
844  * \param type Type of object
845  * \param alloc Required object allocation callback
846  * \param transform Optional transformation callback
847  * \param apply Optional object set apply callback
848  *
849  * \retval 0 success
850  * \retval -1 failure
851  */
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))
854 
855 /*!
856  * \brief Register an internal, hidden object type
857  *
858  * \param sorcery Pointer to a sorcery structure
859  * \param type Type of object
860  * \param alloc Required object allocation callback
861  * \param transform Optional transformation callback
862  * \param apply Optional object set apply callback
863  *
864  * \retval 0 success
865  * \retval -1 failure
866  */
867 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
868  __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
869 
870 /*!
871  * \brief Set the high and low alert water marks of the sorcery object type.
872  * \since 13.10.0
873  *
874  * \param sorcery Pointer to a sorcery structure
875  * \param type Type of object
876  * \param low_water New queue low water mark. (-1 to set as 90% of high_water)
877  * \param high_water New queue high water mark.
878  *
879  * \retval 0 on success.
880  * \retval -1 on error (water marks not changed).
881  */
882 int ast_sorcery_object_set_congestion_levels(struct ast_sorcery *sorcery, const char *type, long low_water, long high_water);
883 
884 /*!
885  * \brief Set the copy handler for an object type
886  *
887  * \param sorcery Pointer to a sorcery structure
888  * \param type Type of object
889  * \param copy Copy handler
890  */
892 
893 /*!
894  * \brief Set the diff handler for an object type
895  *
896  * \param sorcery Pointer to a sorcery structure
897  * \param type Type of object
898  * \param diff Diff handler
899  */
901 
902 /*!
903  * \brief Register a regex for multiple fields within an object
904  *
905  * \param sorcery Pointer to a sorcery structure
906  * \param type Type of object
907  * \param regex A regular expression pattern for the fields
908  * \param config_handler A custom handler for translating the string representation of the fields
909  * \param sorcery_handler A custom handler for translating the native representation of the fields
910  *
911  * \retval 0 success
912  * \retval -1 failure
913  */
914 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
915  sorcery_fields_handler sorcery_handler);
916 
917 /*!
918  * \brief Register a field within an object
919  *
920  * \param sorcery Pointer to a sorcery structure
921  * \param type Type of object
922  * \param name Name of the field
923  * \param default_val Default value of the field
924  * \param config_handler A custom handler for translating the string representation of the fields
925  * \param sorcery_handler A custom handler for translating the native representation of the fields
926  * \param multiple_handler A custom handler for translating the native representation of the fields
927  * \param opt_type Option type
928  * \param flags Option type specific flags
929  * \param no_doc Field should not be documented
930  * \param alias Interpret and apply field value only
931  * \param argc
932  *
933  * \retval 0 success
934  * \retval -1 failure
935  */
937  const char *name, const char *default_val, enum aco_option_type opt_type,
938  aco_option_handler config_handler, sorcery_field_handler sorcery_handler,
939  sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc,
940  unsigned int alias, size_t argc, ...);
941 
942 /*!
943  * \brief Register a field within an object
944  *
945  * \param sorcery Pointer to a sorcery structure
946  * \param type Type of object
947  * \param name Name of the field
948  * \param default_val Default value of the field
949  * \param opt_type Option type
950  * \param flags Option type specific flags
951  *
952  * \retval 0 success
953  * \retval -1 failure
954  */
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__)
957 
958 /*!
959  * \brief Register a field within an object as an alias
960  *
961  * \param sorcery Pointer to a sorcery structure
962  * \param type Type of object
963  * \param name Name of the field
964  * \param default_val Default value of the field
965  * \param opt_type Option type
966  * \param flags Option type specific flags
967  *
968  * \retval 0 success
969  * \retval -1 failure
970  */
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__)
973 
974 /*!
975  * \brief Register a field within an object without documentation
976  *
977  * \param sorcery Pointer to a sorcery structure
978  * \param type Type of object
979  * \param name Name of the field
980  * \param default_val Default value of the field
981  * \param opt_type Option type
982  * \param flags Option type specific flags
983  *
984  * \retval 0 success
985  * \retval -1 failure
986  */
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__)
989 
990 /*!
991  * \brief Register a field within an object with custom handlers
992  *
993  * \param sorcery Pointer to a sorcery structure
994  * \param type Type of object
995  * \param name Name of the field
996  * \param default_val Default value of the field
997  * \param config_handler Custom configuration handler
998  * \param sorcery_handler Custom sorcery handler
999  * \param multiple_handler Custom multiple handler
1000  * \param flags Option type specific flags
1001  *
1002  * \retval 0 success
1003  * \retval -1 failure
1004  */
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__);
1007 
1008 /*!
1009  * \brief Register a field within an object with custom handlers as an alias
1010  *
1011  * \param sorcery Pointer to a sorcery structure
1012  * \param type Type of object
1013  * \param name Name of the field
1014  * \param default_val Default value of the field
1015  * \param config_handler Custom configuration handler
1016  * \param sorcery_handler Custom sorcery handler
1017  * \param multiple_handler Custom multiple handler
1018  * \param flags Option type specific flags
1019  *
1020  * \retval 0 success
1021  * \retval -1 failure
1022  */
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__);
1025 
1026 /*!
1027  * \brief Register a field within an object with custom handlers without documentation
1028  *
1029  * \param sorcery Pointer to a sorcery structure
1030  * \param type Type of object
1031  * \param name Name of the field
1032  * \param default_val Default value of the field
1033  * \param config_handler Custom configuration handler
1034  * \param sorcery_handler Custom sorcery handler
1035  * \param multiple_handler Custom multiple handler
1036  * \param flags Option type specific flags
1037  *
1038  * \retval 0 success
1039  * \retval -1 failure
1040  */
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__);
1043 
1044 /*!
1045  * \brief Inform any wizards to load persistent objects
1046  *
1047  * \param sorcery Pointer to a sorcery structure
1048  */
1049 void ast_sorcery_load(const struct ast_sorcery *sorcery);
1050 
1051 /*!
1052  * \brief Inform any wizards of a specific object type to load persistent objects
1053  *
1054  * \param sorcery Pointer to a sorcery structure
1055  * \param type Name of the object type to load
1056  */
1057 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
1058 
1059 /*!
1060  * \brief Inform any wizards to reload persistent objects
1061  *
1062  * \param sorcery Pointer to a sorcery structure
1063  */
1064 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
1065 
1066 /*!
1067  * \brief Inform any wizards to reload persistent objects, even if no changes determined
1068  *
1069  * \param sorcery Pointer to a sorcery structure
1070  *
1071  * \since 13.32.0
1072  * \since 16.9.0
1073  * \since 17.3.0
1074  */
1075 void ast_sorcery_force_reload(const struct ast_sorcery *sorcery);
1076 
1077 /*!
1078  * \brief Inform any wizards of a specific object type to reload persistent objects
1079  *
1080  * \param sorcery Pointer to a sorcery structure
1081  * \param type Name of the object type to reload
1082  */
1083 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
1084 
1085 /*!
1086  * \brief Inform any wizards of a specific object type to reload persistent objects
1087  * even if no changes determined
1088  *
1089  * \param sorcery Pointer to a sorcery structure
1090  * \param type Name of the object type to reload
1091  *
1092  * \since 13.32.0
1093  * \since 16.9.0
1094  * \since 17.3.0
1095  */
1096 void ast_sorcery_force_reload_object(const struct ast_sorcery *sorcery, const char *type);
1097 
1098 /*!
1099  * \brief Increase the reference count of a sorcery structure
1100  *
1101  * \param sorcery Pointer to a sorcery structure
1102  */
1103 void ast_sorcery_ref(struct ast_sorcery *sorcery);
1104 
1105 
1106 /*!
1107  * \brief Create an object set (KVP list) for an object
1108  *
1109  * \param sorcery Pointer to a sorcery structure
1110  * \param object Pointer to a sorcery object
1111  * \param flags Flags indicating which handler to use and in what order.
1112  *
1113  * \retval non-NULL success
1114  * \retval NULL if error occurred
1115  *
1116  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1117  */
1119  const void *object, enum ast_sorcery_field_handler_flags flags);
1120 
1121 /*!
1122  * \brief Create an object set (KVP list) for an object
1123  *
1124  * \param sorcery Pointer to a sorcery structure
1125  * \param object Pointer to a sorcery object
1126  *
1127  * \retval non-NULL success
1128  * \retval NULL if error occurred
1129  *
1130  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1131  *
1132  * \note This function attempts to use a field's sorcery_fields_handler first and if that
1133  * doesn't exist or fails, a field's sorcery_field_handler is used. The difference is
1134  * that the former may return multiple list entries for the same field and the latter will only
1135  * return 1. It's up to the field itself to determine what the appropriate content is.
1136  */
1137 #define ast_sorcery_objectset_create(sorcery, object) \
1138  ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
1139 
1140 /*!
1141  * \brief Create an object set in JSON format for an object
1142  *
1143  * \param sorcery Pointer to a sorcery structure
1144  * \param object Pointer to a sorcery object
1145  *
1146  * \retval non-NULL success
1147  * \retval NULL if error occurred
1148  *
1149  * \note The returned ast_json object must be unreferenced using ast_json_unref
1150  */
1151 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
1152 
1153 /*!
1154  * \brief Apply an object set (KVP list) to an object
1155  *
1156  * \param sorcery Pointer to a sorcery structure
1157  * \param object Pointer to a sorcery object
1158  * \param objectset Object set itself
1159  *
1160  * \retval 0 success
1161  * \retval -1 failure
1162  *
1163  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
1164  * applied object set.
1165  */
1166 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
1167 
1168 /*!
1169  * \brief Create a changeset given two object sets
1170  *
1171  * \param original Original object set
1172  * \param modified Modified object set
1173  * \param changes Pointer to hold any changes between the object sets
1174  *
1175  * \retval 0 success
1176  * \retval -1 failure
1177  *
1178  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1179  */
1180 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
1181 
1182 /*!
1183  * \brief Allocate a generic sorcery capable object
1184  *
1185  * \param size Size of the object
1186  * \param destructor Optional destructor function
1187  *
1188  * \retval non-NULL success
1189  * \retval NULL failure
1190  *
1191  * \note The returned object does not support AO2 locking.
1192  */
1193 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
1194 
1195 /*!
1196  * \since 14.1.0
1197  * \brief Allocate a generic sorcery capable object with locking.
1198  *
1199  * \details Sorcery objects may be replaced with new allocations during reloads.
1200  * If locking is required on sorcery objects it must be shared between the old
1201  * object and the new one. lockobj can be any AO2 object with locking enabled,
1202  * but in most cases named locks should be used to provide stable locking.
1203  *
1204  * \param size Size of the object
1205  * \param destructor Optional destructor function
1206  * \param lockobj An AO2 object that will provide locking.
1207  *
1208  * \retval non-NULL success
1209  * \retval NULL failure
1210  */
1211 void *ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj);
1212 
1213 /*!
1214  * \brief Allocate an object
1215  *
1216  * \param sorcery Pointer to a sorcery structure
1217  * \param type Type of object to allocate
1218  * \param id Optional unique identifier, if none is provided one will be generated
1219  *
1220  * \retval non-NULL success
1221  * \retval NULL failure
1222  */
1223 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
1224 
1225 /*!
1226  * \brief Create a copy of an object
1227  *
1228  * \param sorcery Pointer to a sorcery structure
1229  * \param object Existing object
1230  *
1231  * \retval non-NULL success
1232  * \retval NULL failure
1233  */
1234 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
1235 
1236 /*!
1237  * \brief Create a changeset of two objects
1238  *
1239  * \param sorcery Pointer to a sorcery structure
1240  * \param original Original object
1241  * \param modified Modified object
1242  * \param changes Pointer which will be populated with changes if any exist
1243  *
1244  * \retval 0 success
1245  * \retval -1 failure
1246  *
1247  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1248  *
1249  * \note While the objects must be of the same type they do not have to be the same object
1250  */
1251 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
1252 
1253 /*!
1254  * \brief Add a global observer to sorcery
1255  *
1256  * \param callbacks Implementation of the global observer interface
1257  *
1258  * \retval 0 success
1259  * \retval -1 failure
1260  *
1261  * \note You must be ready to accept observer invocations before this function is called
1262  */
1264 
1265 /*!
1266  * \brief Remove a global observer from sorcery.
1267  *
1268  * A global observer is notified...
1269  * After a new wizard is registered.
1270  * After a new sorcery instance is opened.
1271  * Before an instance is destroyed.
1272  * Before a wizard is unregistered.
1273  *
1274  * \param callbacks Implementation of the global observer interface
1275  */
1277 
1278 /*!
1279  * \brief Add an observer to a sorcery instance
1280  *
1281  * \param sorcery Pointer to a sorcery structure
1282  * \param callbacks Implementation of the instance observer interface
1283  *
1284  * An instance observer is notified...
1285  * Before an instance is loaded or reloaded.
1286  * After an instance is loaded or reloaded.
1287  * After a wizard is mapped to an object type.
1288  * After an object type is registered.
1289  * Before an object type is loaded or reloaded.
1290  * After an object type is loaded or reloaded.
1291  *
1292  * \retval 0 success
1293  * \retval -1 failure
1294  *
1295  * \note You must be ready to accept observer invocations before this function is called
1296  */
1299 
1300 /*!
1301  * \brief Remove an observer from a sorcery instance
1302  *
1303  * \param sorcery Pointer to a sorcery structure
1304  * \param callbacks Implementation of the instance observer interface
1305  */
1308 
1309 /*!
1310  * \brief Add an observer to a sorcery wizard
1311  *
1312  * \param wizard Pointer to a previously registered wizard structure
1313  * \param callbacks Implementation of the wizard observer interface
1314  *
1315  * A wizard observer is notified...
1316  * Before a wizard is loaded or reloaded.
1317  * After a wizard is loaded or reloaded.
1318  *
1319  * \retval 0 success
1320  * \retval -1 failure
1321  *
1322  * \note You must be ready to accept observer invocations before this function is called
1323  */
1325  const struct ast_sorcery_wizard_observer *callbacks);
1326 
1327 /*!
1328  * \brief Remove an observer from a sorcery wizard.
1329  *
1330  * \param interface Pointer to a sorcery structure
1331  * \param callbacks Implementation of the wizard observer interface
1332  */
1334  const struct ast_sorcery_wizard_observer *callbacks);
1335 
1336 /*!
1337  * \brief Add an observer to a specific object type
1338  *
1339  * \param sorcery Pointer to a sorcery structure
1340  * \param type Type of object that should be observed
1341  * \param callbacks Implementation of the observer interface
1342  *
1343  * \retval 0 success
1344  * \retval -1 failure
1345  *
1346  * \note You must be ready to accept observer invocations before this function is called
1347  */
1348 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1349 
1350 /*!
1351  * \brief Remove an observer from a specific object type
1352  *
1353  * \param sorcery Pointer to a sorcery structure
1354  * \param type Type of object that should no longer be observed
1355  * \param callbacks Implementation of the observer interface
1356  */
1357 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1358 
1359 /*!
1360  * \brief Create and potentially persist an object using an available wizard
1361  *
1362  * \param sorcery Pointer to a sorcery structure
1363  * \param object Pointer to a sorcery object
1364  *
1365  * \retval 0 success
1366  * \retval -1 failure
1367  */
1368 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
1369 
1370 /*!
1371  * \brief Retrieve an object using its unique identifier
1372  *
1373  * \param sorcery Pointer to a sorcery structure
1374  * \param type Type of object to retrieve
1375  * \param id Unique object identifier
1376  *
1377  * \retval non-NULL if found
1378  * \retval NULL if not found
1379  */
1380 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
1381 
1382 /*!
1383  * \brief Retrieve an object or multiple objects using specific fields
1384  * \since 13.9.0
1385  *
1386  * \param sorcery Pointer to a sorcery structure
1387  * \param type Type of object to retrieve
1388  * \param flags Flags to control behavior
1389  * \param fields Optional object fields and values to match against
1390  *
1391  * \retval non-NULL if found
1392  * \retval NULL if not found
1393  *
1394  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
1395  * ao2_container that must be unreferenced after use.
1396  *
1397  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
1398  * of the given type.
1399  *
1400  * \note The fields parameter can contain realtime-style expressions in variable->name.
1401  * All operators defined for ast_strings_match can be used except for regex as
1402  * there's no common support for regex in the realtime backends at this time.
1403  * If multiple variables are in the fields list, all must match for an object to
1404  * be returned. See ast_strings_match for more information.
1405  *
1406  * Example:
1407  *
1408  * The following code can be significantly faster when a realtime backend is in use
1409  * because the expression "qualify_frequency > 0" is passed to the database to limit
1410  * the number of rows returned.
1411  *
1412  * struct ast_variable *var = ast_variable_new("qualify_frequency >", "0", "");
1413  * struct ao2_container *aors;
1414  *
1415  * if (!var) {
1416  * return;
1417  * }
1418  *
1419  * aors = ast_sorcery_retrieve_by_fields(ast_sip_get_sorcery(),
1420  * "aor", AST_RETRIEVE_FLAG_MULTIPLE, var);
1421  *
1422  */
1423 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
1424 
1425 /*!
1426  * \brief Retrieve multiple objects using a regular expression on their id
1427  *
1428  * \param sorcery Pointer to a sorcery structure
1429  * \param type Type of object to retrieve
1430  * \param regex Regular expression
1431  *
1432  * \retval non-NULL if error occurs
1433  * \retval NULL success
1434  *
1435  * \note The provided regex is treated as extended case sensitive.
1436  */
1437 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
1438 
1439 /*!
1440  * \brief Retrieve multiple objects whose id begins with the specified prefix
1441  * \since 13.19.0
1442  *
1443  * \param sorcery Pointer to a sorcery structure
1444  * \param type Type of object to retrieve
1445  * \param prefix Object id prefix
1446  * \param prefix_len The length of prefix in bytes
1447  *
1448  * \retval non-NULL if error occurs
1449  * \retval NULL success
1450  *
1451  * \note The prefix is matched in a case sensitive manner.
1452  */
1453 struct ao2_container *ast_sorcery_retrieve_by_prefix(const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len);
1454 
1455 /*!
1456  * \brief Update an object
1457  *
1458  * \param sorcery Pointer to a sorcery structure
1459  * \param object Pointer to a sorcery object
1460  *
1461  * \retval 0 success
1462  * \retval -1 failure
1463  */
1464 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
1465 
1466 /*!
1467  * \brief Delete an object
1468  *
1469  * \param sorcery Pointer to a sorcery structure
1470  * \param object Pointer to a sorcery object
1471  *
1472  * \retval 0 success
1473  * \retval -1 failure
1474  */
1475 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
1476 
1477 /*!
1478  * \brief Determine if a sorcery object is stale with respect to its backing datastore
1479  * \since 14.0.0
1480  *
1481  * This function will query the wizard(s) backing the particular sorcery object to
1482  * determine if the in-memory object is now stale. No action is taken to update
1483  * the object. Callers of this function may use one of the ast_sorcery_retrieve
1484  * functions to obtain a new instance of the object if desired.
1485  *
1486  * \retval 0 the object is not stale
1487  * \retval 1 the object is stale
1488  */
1489 int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
1490 
1491 /*!
1492  * \brief Decrease the reference count of a sorcery structure
1493  *
1494  * \param sorcery Pointer to a sorcery structure
1495  *
1496  * \note Prior to 16.0.0 this was a function which had to be used.
1497  * Now you can use any variant of ao2_cleanup or ao2_ref to
1498  * release a reference.
1499  */
1500 #define ast_sorcery_unref(sorcery) \
1501  ao2_cleanup(sorcery)
1502 
1503 /*!
1504  * \brief Get the unique identifier of a sorcery object
1505  *
1506  * \param object Pointer to a sorcery object
1507  *
1508  * \return unique identifier
1509  */
1510 const char *ast_sorcery_object_get_id(const void *object);
1511 
1512 /*!
1513  * \since 14.0.0
1514  * \brief Get when the sorcery object was created
1515  *
1516  * \param object Pointer to a sorcery object
1517  *
1518  * \return The time when the object was created
1519  */
1520 const struct timeval ast_sorcery_object_get_created(const void *object);
1521 
1522 /*!
1523  * \brief Get the type of a sorcery object
1524  *
1525  * \param object Pointer to a sorcery object
1526  *
1527  * \return type of object
1528  */
1529 const char *ast_sorcery_object_get_type(const void *object);
1530 
1531 /*!
1532  * \brief Get an extended field value from a sorcery object
1533  *
1534  * \param object Pointer to a sorcery object
1535  * \param name Name of the extended field value
1536  *
1537  * \retval non-NULL if found
1538  * \retval NULL if not found
1539  *
1540  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
1541  */
1542 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
1543 
1544 /*!
1545  * \brief Set an extended field value on a sorcery object
1546  *
1547  * \param object Pointer to a sorcery object
1548  * \param name Name of the extended field
1549  * \param value Value of the extended field
1550  *
1551  * \retval 0 success
1552  * \retval -1 failure
1553  *
1554  * \note The field name MUST begin with '@' to indicate it is an extended field.
1555  * \note If the extended field already exists it will be overwritten with the new value.
1556  */
1557 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
1558 
1559 /*!
1560  * \brief Get whether an object contains dynamic contents or not
1561  *
1562  * \param object Pointer to a sorcery object
1563  *
1564  * \since 19
1565  * \since 18.3.0
1566  * \since 16.17.0
1567  */
1568 unsigned int ast_sorcery_object_has_dynamic_contents(const void *object);
1569 
1570 /*!
1571  * \brief Set the dynamic contents flag on a sorcery object
1572  *
1573  * \param object Pointer to a sorcery object
1574  *
1575  * \since 19
1576  * \since 18.3.0
1577  * \since 16.17.0
1578  */
1579 void ast_sorcery_object_set_has_dynamic_contents(const void *object);
1580 
1581 /*!
1582  * \brief ao2 object comparator based on sorcery id.
1583  */
1584 int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
1585 
1586 /*!
1587  * \brief ao2 object sorter based on sorcery id.
1588  */
1589 int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
1590 
1591 /*!
1592  * \brief ao2 object hasher based on sorcery id.
1593  */
1594 int ast_sorcery_object_id_hash(const void *obj, int flags);
1595 
1596 /*!
1597  * \brief Get the sorcery object type given a type name.
1598  *
1599  * \param sorcery The sorcery from which to retrieve the object type
1600  * \param type The type name
1601  */
1603  const char *type);
1604 
1605 /*!
1606  * \brief Determine if a particular object field has been registered with sorcery
1607  *
1608  * \param object_type The object type to check against
1609  * \param field_name The name of the field to check
1610  *
1611  * \retval 0 The field is not registered for this sorcery type
1612  * \retval 1 The field is registered for this sorcery type
1613  */
1615  const char *field_name);
1616 
1617 /*!
1618  * \brief Get the module that has opened the provided sorcery instance.
1619  *
1620  * \param sorcery The sorcery instance
1621  *
1622  * \return The module
1623  */
1624 const char *ast_sorcery_get_module(const struct ast_sorcery *sorcery);
1625 
1626 #if defined(__cplusplus) || defined(c_plusplus)
1627 }
1628 #endif
1629 
1630 #endif /* _ASTERISK_SORCERY_H */
enum queue_result id
Definition: app_queue.c:1640
static int copy(char *infile, char *outfile)
Utility function to copy a file.
void(* ao2_destructor_fn)(void *vdoomed)
Typedef for an object destructor.
Definition: astobj2.h:358
static const char type[]
Definition: chan_ooh323.c:109
Configuration option-handling.
int(* aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj)
A callback function for handling a particular option.
aco_option_type
The option types.
void *(* aco_type_item_alloc)(const char *category)
Allocate a configurable ao2 object.
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
static int set(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
Definition: func_logic.c:206
static int regex(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
static char prefix[MAX_PREFIX]
Definition: http.c:144
static struct ast_sorcery * sorcery
struct @498 callbacks
struct ast_variable *(* sorcery_transform_handler)(struct ast_variable *set)
A callback function for performing a transformation on an object set.
Definition: sorcery.h:181
void * ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id)
Retrieve an object using its unique identifier.
Definition: sorcery.c:1853
int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface)
Unregister a sorcery wizard.
Definition: sorcery.c:474
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.
Definition: sorcery.c:2418
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
int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value)
Set an extended field value on a sorcery object.
Definition: sorcery.c:2344
void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
Remove an observer from a sorcery instance.
Definition: sorcery.c:537
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.
Definition: sorcery.c:1031
ast_sorcery_retrieve_flags
Retrieval flags.
Definition: sorcery.h:115
@ AST_RETRIEVE_FLAG_MULTIPLE
Return all matching objects.
Definition: sorcery.h:120
@ AST_RETRIEVE_FLAG_DEFAULT
Default retrieval flags.
Definition: sorcery.h:117
@ AST_RETRIEVE_FLAG_ALL
Perform no matching, return all objects.
Definition: sorcery.h:123
void ast_sorcery_load(const struct ast_sorcery *sorcery)
Inform any wizards to load persistent objects.
Definition: sorcery.c:1377
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.
Definition: sorcery.c:568
void * ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj)
Allocate a generic sorcery capable object with locking.
Definition: sorcery.c:1712
int(* sorcery_fields_handler)(const void *obj, struct ast_variable **fields)
A callback function for translating multiple values into an ast_variable list.
Definition: sorcery.h:169
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.
Definition: sorcery.c:1128
void ast_sorcery_object_set_has_dynamic_contents(const void *object)
Set the dynamic contents flag on a sorcery object.
Definition: sorcery.c:2379
const char * ast_sorcery_get_module(const struct ast_sorcery *sorcery)
Get the module that has opened the provided sorcery instance.
Definition: sorcery.c:2531
void * ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor)
Allocate a generic sorcery capable object.
Definition: sorcery.c:1728
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.
Definition: sorcery.c:1949
int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object)
Create and potentially persist an object using an available wizard.
Definition: sorcery.c:2057
struct ast_sorcery * ast_sorcery_retrieve_by_module_name(const char *module_name)
Retrieves an existing sorcery instance by module name.
Definition: sorcery.c:672
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.
Definition: sorcery.c:1805
void ast_sorcery_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects.
Definition: sorcery.c:1408
int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery, const char *type)
Return the number of wizards mapped to an object type.
Definition: sorcery.c:778
int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module)
Register a sorcery wizard.
Definition: sorcery.c:432
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.
Definition: sorcery.c:2386
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
void ast_sorcery_force_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects, even if no changes determined.
Definition: sorcery.c:1425
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.
Definition: sorcery.c:1393
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.
Definition: sorcery.c:1984
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.
Definition: sorcery.h:194
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.
Definition: sorcery.c:1565
int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type)
Unregister an object type.
Definition: sorcery.c:1061
int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name)
Remove an object wizard mapping.
Definition: sorcery.c:850
int(* sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes)
A callback function for generating a changeset between two objects.
Definition: sorcery.h:217
int ast_sorcery_object_id_compare(void *obj, void *arg, int flags)
ao2 object comparator based on sorcery id.
Definition: sorcery.c:2459
const char * ast_sorcery_object_get_id(const void *object)
Get the unique identifier of a sorcery object.
Definition: sorcery.c:2312
int(* sorcery_copy_handler)(const void *src, void *dst)
A callback function for copying the contents of one object to another.
Definition: sorcery.h:205
unsigned int ast_sorcery_object_has_dynamic_contents(const void *object)
Get whether an object contains dynamic contents or not.
Definition: sorcery.c:2372
void ast_sorcery_ref(struct ast_sorcery *sorcery)
Increase the reference count of a sorcery structure.
Definition: sorcery.c:1473
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.
Definition: sorcery.c:1192
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.
Definition: sorcery.c:1080
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
ast_sorcery_wizard_position
Pre-defined locations to insert at.
Definition: sorcery.h:517
@ AST_SORCERY_WIZARD_POSITION_FIRST
Definition: sorcery.h:519
@ AST_SORCERY_WIZARD_POSITION_LAST
Definition: sorcery.h:518
enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module)
Apply configured wizard mappings.
Definition: sorcery.c:985
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.
Definition: sorcery.c:1897
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.
Definition: sorcery.c:2509
int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags)
ao2 object sorter based on sorcery id.
Definition: sorcery.c:2435
const struct timeval ast_sorcery_object_get_created(const void *object)
Get when the sorcery object was created.
Definition: sorcery.c:2318
int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object)
Update an object.
Definition: sorcery.c:2145
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
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.
Definition: sorcery.c:790
ast_sorcery_field_handler_flags
Field handler flags.
Definition: sorcery.h:129
@ AST_HANDLER_PREFER_STRING
Try both handlers, string first.
Definition: sorcery.h:131
@ AST_HANDLER_PREFER_LIST
Try both handlers, list first.
Definition: sorcery.h:134
@ AST_HANDLER_ONLY_LIST
Use list handler only.
Definition: sorcery.h:140
@ AST_HANDLER_ONLY_STRING
Use string handler only.
Definition: sorcery.h:137
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...
Definition: sorcery.c:1457
const char * ast_sorcery_object_get_type(const void *object)
Get the type of a sorcery object.
Definition: sorcery.c:2324
int(* sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf)
A callback function for translating a value into a string.
Definition: sorcery.h:158
void * ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object)
Create a copy of an object.
Definition: sorcery.c:1778
void * ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id)
Allocate an object.
Definition: sorcery.c:1744
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.
Definition: sorcery.c:977
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
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.
Definition: sorcery.c:543
void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks)
Remove a global observer from sorcery.
Definition: sorcery.c:514
int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks)
Add a global observer to sorcery.
Definition: sorcery.c:498
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.
Definition: sorcery.c:1442
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.
Definition: sorcery.c:2283
int ast_sorcery_instance_observer_add(struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
Add an observer to a sorcery instance.
Definition: sorcery.c:520
int ast_sorcery_object_id_hash(const void *obj, int flags)
ao2 object hasher based on sorcery id.
Definition: sorcery.c:2470
const char * ast_sorcery_object_get_extended(const void *object, const char *name)
Get an extended field value from a sorcery object.
Definition: sorcery.c:2330
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.
Definition: sorcery.c:1114
int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object)
Delete an object.
Definition: sorcery.c:2233
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.
Definition: sorcery.c:2489
struct ast_sorcery * __ast_sorcery_open(const char *module, const char *file, int line, const char *func)
Definition: sorcery.c:601
ast_sorcery_wizard_apply_flags
Wizard Apply Flags.
Definition: sorcery.h:575
@ AST_SORCERY_WIZARD_APPLY_NONE
Definition: sorcery.h:577
@ AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
Definition: sorcery.h:583
@ AST_SORCERY_WIZARD_APPLY_READONLY
Definition: sorcery.h:581
@ AST_SORCERY_WIZARD_APPLY_CACHING
Definition: sorcery.h:579
int ast_sorcery_init(void)
Initialize the sorcery API.
Definition: sorcery.c:387
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
ast_sorcery_apply_result
Definition: sorcery.h:423
@ AST_SORCERY_APPLY_SUCCESS
Definition: sorcery.h:427
@ AST_SORCERY_APPLY_NO_CONFIGURATION
Definition: sorcery.h:433
@ AST_SORCERY_APPLY_FAIL
Definition: sorcery.h:425
@ AST_SORCERY_APPLY_DUPLICATE
Definition: sorcery.h:429
@ AST_SORCERY_APPLY_DEFAULT_UNNECESSARY
Definition: sorcery.h:431
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.
Definition: sorcery.c:1139
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.
Definition: sorcery.c:1511
Generic container type.
Abstract JSON element (object, array, string, int, ...).
Interface for the global sorcery observer.
Definition: sorcery.h:220
void(* wizard_unregistering)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback before a wizard is unregistered.
Definition: sorcery.h:232
void(* instance_destroying)(const char *name, struct ast_sorcery *sorcery)
Callback before an instance is destroyed.
Definition: sorcery.h:229
void(* wizard_registered)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback after an wizard is registered.
Definition: sorcery.h:225
void(* instance_created)(const char *name, struct ast_sorcery *sorcery)
Callback after an instance is created.
Definition: sorcery.h:222
Interface for the sorcery instance observer.
Definition: sorcery.h:237
void(* instance_loaded)(const char *name, const struct ast_sorcery *sorcery, int reloaded)
Callback after instance is loaded/reloaded.
Definition: sorcery.h:243
void(* object_type_registered)(const char *name, struct ast_sorcery *sorcery, const char *object_type)
Callback after any object_type is registered.
Definition: sorcery.h:252
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.
Definition: sorcery.h:260
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.
Definition: sorcery.h:247
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.
Definition: sorcery.h:256
void(* instance_loading)(const char *name, const struct ast_sorcery *sorcery, int reloaded)
Callback before instance is loaded/reloaded.
Definition: sorcery.h:239
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
Structure for registered object type.
Definition: sorcery.c:148
Structure for internal sorcery object information.
Definition: sorcery.c:127
Interface for a sorcery object type observer.
Definition: sorcery.h:332
void(* loaded)(const char *object_type)
Callback for when an object type is loaded/reloaded.
Definition: sorcery.h:343
void(* deleted)(const void *object)
Callback for when an object is deleted.
Definition: sorcery.h:340
void(* created)(const void *object)
Callback for when an object is created.
Definition: sorcery.h:334
void(* updated)(const void *object)
Callback for when an object is updated.
Definition: sorcery.h:337
Interface for the sorcery wizard observer.
Definition: sorcery.h:265
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.
Definition: sorcery.h:267
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.
Definition: sorcery.h:271
Interface for a sorcery wizard.
Definition: sorcery.h:276
void(* close)(void *data)
Callback for closing a wizard.
Definition: sorcery.h:322
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 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
void(* load)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for loading persistent objects.
Definition: sorcery.h:287
int(* create)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for creating an object.
Definition: sorcery.h:293
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
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
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.
Definition: sorcery.h:328
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
int(* update)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for updating an object.
Definition: sorcery.h:316
void(* reload)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for reloading persistent objects.
Definition: sorcery.h:290
Full structure for sorcery.
Definition: sorcery.c:230
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
Structure for variables, used for configurations and for channel variables.
int value
Definition: syslog.c:37
const char * args
Universally unique identifier support.