Asterisk - The Open Source Telephony Project  GIT-master-8beac82
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  * \param 0 success
215  * \param -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 struct ast_sorcery *__ast_sorcery_open(const char *module, const char *file, int line, const char *func);
407 
408 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)
409 
410 /*!
411  * \brief Retrieves an existing sorcery instance by module name
412  *
413  * \param module The module name
414  *
415  * \retval non-NULL success
416  * \retval NULL if no instance was found
417  *
418  * \note The returned instance has its reference count incremented. The caller
419  * must decrement the count when they're finished with it.
420  *
421  */
422 struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
423 
425  /*! Sorcery wizard failed to apply. */
427  /*! Sorcery wizard applied successfully. */
429  /*! Sorcery wizard has already been applied to the object type. */
431  /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
433  /*! No sorcery.conf configuration file was found to apply. */
435 };
436 
437 /*!
438  * \brief Apply configured wizard mappings
439  *
440  * \param sorcery Pointer to a sorcery structure
441  * \param name Name of the category to use within the configuration file, normally the module name
442  * \param module The module name (AST_MODULE)
443  *
444  * This function is called automatically by __ast_sorcery_open() using the module name as the
445  * configuration category. The only reason you should call this function is if your module
446  * wishes to apply configuration from additional sections of sorcery.conf.
447  *
448  * If a configuration section attempts to apply the same sorcery wizard to an object type
449  * more than once, the wizard will only be applied one time.
450  *
451  * \return What happened when attempting to apply the config.
452  */
454  const char *name, const char *module);
455 
456 #define ast_sorcery_apply_config(sorcery, name) \
457  __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
458 
459 /*!
460  * \brief Apply default object wizard mappings
461  *
462  * \param sorcery Pointer to a sorcery structure
463  * \param type Type of object to apply to
464  * \param module The name of the module, typically AST_MODULE
465  * \param name Name of the wizard to use
466  * \param data Data to be passed to wizard
467  *
468  * \return What occurred when applying the default
469  *
470  * \note This should be called *after* applying configuration sourced mappings
471  *
472  * \note Only a single default can exist per object type
473  */
475  const char *type, const char *module, const char *name, const char *data);
476 
477 #define ast_sorcery_apply_default(sorcery, type, name, data) \
478  __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
479 
480 
481 /*!
482  * \brief Apply additional object wizard mappings
483  *
484  * \param sorcery Pointer to a sorcery structure
485  * \param type Type of object to apply to
486  * \param module The name of the module, typically AST_MODULE
487  * \param name Name of the wizard to use
488  * \param data Data to be passed to wizard
489  * \param caching Wizard should cache
490  *
491  * \return What occurred when applying the mapping
492  *
493  * \note This should be called *after* applying default mappings
494  */
496  const char *type, const char *module, const char *name, const char *data, unsigned int caching);
497 
498 /*!
499  * \brief Apply additional object wizard mappings
500  *
501  * \param sorcery Pointer to a sorcery structure
502  * \param type Type of object to apply to
503  * \param module The name of the module, typically AST_MODULE
504  * \param name Name of the wizard to use
505  * \param data Data to be passed to wizard
506  *
507  * \return What occurred when applying the mapping
508  *
509  * \note This should be called *after* applying default mappings
510  */
511 #define ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching) \
512  __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));
513 
514 
515 /*!
516  * \brief Pre-defined locations to insert at
517  */
521 };
522 
523 /*!
524  * \brief Insert an additional object wizard mapping at a specific position
525  * in the wizard list
526  *
527  * \param sorcery Pointer to a sorcery structure
528  * \param type Type of object to apply to
529  * \param module The name of the module, typically AST_MODULE
530  * \param name Name of the wizard to use
531  * \param data Data to be passed to wizard
532  * \param caching Wizard should cache
533  * \param position An index to insert to or one of ast_sorcery_wizard_position
534  *
535  * \return What occurred when applying the mapping
536  *
537  * \note This should be called *after* applying default mappings
538  * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count
539  * and iterating over them using ast_sorcery_get_wizard_mapping.
540  *
541  * \since 13.4.0
542  */
544  const char *type, const char *module, const char *name, const char *data,
545  unsigned int caching, int position);
546 
547 /*!
548  * \brief Insert an additional object wizard mapping at a specific position
549  * in the wizard list
550  *
551  * \param sorcery Pointer to a sorcery structure
552  * \param type Type of object to apply to
553  * \param module The name of the module, typically AST_MODULE
554  * \param name Name of the wizard to use
555  * \param data Data to be passed to wizard
556  * \param position One of ast_sorcery_wizard_position
557  *
558  * \return What occurred when applying the mapping
559  *
560  * \note This should be called *after* applying default mappings
561  * \since 13.4.0
562  */
563 #define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \
564  __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
565  (caching), (position))
566 
567 /*!
568  * \brief Wizard Apply Flags
569  *
570  * These flags apply only to a wizard/object-type combination.
571  * The same wizard may be applied to a different object-type with
572  * different flags and behavior. If ALLOW_DUPLICATE is set
573  * the wizard could even be applied to the same object-type
574  * with different flags.
575  */
577  /*! Apply no special behavior */
579  /*! This wizard will cache this object type's entries */
581  /*! This wizard won't allow Create, Update or Delete operations on this object type */
583  /*! This wizard will allow other instances of itself on the same object type */
585 };
586 
587 /*!
588  * \brief Insert an additional object wizard mapping at a specific position
589  * in the wizard list returning wizard information
590  * \since 13.26.0
591  * \since 16.3.0
592  *
593  * \param sorcery Pointer to a sorcery structure
594  * \param object_type_name Name of the object type to apply to
595  * \param module The name of the module, typically AST_MODULE
596  * \param wizard_type_name Name of the wizard type to use
597  * \param wizard_args Opaque string to be passed to the wizard
598  * May be NULL but see note below
599  * \param flags One or more of enum ast_sorcery_wizard_apply_flags
600  * \param position An index to insert to or one of ast_sorcery_wizard_position
601  * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
602  * May be NULL if not needed.
603  * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
604  * May be NULL if not needed.
605  *
606  * \return What occurred when applying the mapping
607  *
608  * \note This should be called *after* applying default mappings
609  *
610  * \note Although \ref wizard_args is an optional parameter it is highly
611  * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
612  * flag, and you intend to ever remove a wizard mapping, you'll need wizard_args
613  * to remove specific instances of a wizard type.
614  */
616  const char *object_type_name, const char *module, const char *wizard_type_name,
617  const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position,
618  struct ast_sorcery_wizard **wizard, void **wizard_data);
619 
620 /*!
621  * \brief Insert an additional object wizard mapping at a specific position
622  * in the wizard list returning wizard information
623  * \since 13.26.0
624  * \since 16.3.0
625  *
626  * \param sorcery Pointer to a sorcery structure
627  * \param object_type_name Name of the object type to apply to
628  * \param wizard_type_name Name of the wizard type to use
629  * \param wizard_args Opaque string to be passed to the wizard
630  * May be NULL but see note below
631  * \param flags One or more of enum ast_sorcery_wizard_apply_flags
632  * \param position An index to insert to or one of ast_sorcery_wizard_position
633  * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
634  * May be NULL if not needed.
635  * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
636  * May be NULL if not needed.
637  *
638  * \return What occurred when applying the mapping
639  *
640  * \note This should be called *after* applying default mappings
641  *
642  * \note Although \ref wizard_args is an optional parameter it is highly
643  * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
644  * flag, and you intend to ever remove a wizard mapping, you'll need wizard_args
645  * to remove specific instances.
646  */
647 #define ast_sorcery_object_type_insert_wizard(sorcery, \
648  object_type_name, wizard_type_name, wizard_args, flags, \
649  position, wizard, wizard_data) \
650  __ast_sorcery_object_type_insert_wizard((sorcery), \
651  (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
652  position, (wizard), (wizard_data))
653 
654 /*!
655  * \brief Apply additional object wizard mappings returning wizard information
656  * \since 13.26.0
657  * \since 16.3.0
658  *
659  * \param sorcery Pointer to a sorcery structure
660  * \param object_type_name Name of the object type to apply to
661  * \param wizard_type_name Name of the wizard type to use
662  * \param wizard_args Opaque string to be passed to the wizard
663  * May be NULL but see note below
664  * \param flags One or more of enum ast_sorcery_wizard_apply_flags
665  * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
666  * May be NULL if not needed.
667  * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
668  * May be NULL if not needed.
669  *
670  * \return What occurred when applying the mapping
671  *
672  * \note This should be called *after* applying default mappings
673  *
674  * \note Although \ref wizard_args is an optional parameter it is highly
675  * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
676  * flag, and you intend to ever remove a wizard mapping, you'll need wizard_args
677  * to remove specific instances.
678  */
679 #define ast_sorcery_object_type_apply_wizard(sorcery, \
680  object_type_name, wizard_type_name, wizard_args, flags, \
681  wizard, wizard_data) \
682  __ast_sorcery_object_type_insert_wizard((sorcery), \
683  (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
684  AST_SORCERY_WIZARD_POSITION_LAST, (wizard), (wizard_data))
685 
686 /*!
687  * \brief Remove an object wizard mapping
688  * \since 13.26.0
689  * \since 16.3.0
690  *
691  * \param sorcery Pointer to a sorcery structure
692  * \param object_type_name Name of the object type to remove from
693  * \param module The name of the module, typically AST_MODULE
694  * \param wizard_type_name The name of the of the wizard type to remove
695  * \param wizard_args Opaque string originally passed to the wizard
696  *
697  * \retval 0 success
698  * \retval -1 failure
699  *
700  * \note If there were multiple instances of the same wizard type
701  * added to this object type without using \ref wizard_args, then
702  * only the first wizard matching wizard_type will be removed.
703  */
705  const char *object_type_name, const char *module, const char *wizard_type_name,
706  const char *wizard_args);
707 
708 /*!
709  * \brief Remove an object wizard mapping
710  * \since 13.26.0
711  * \since 16.3.0
712  *
713  * \param sorcery Pointer to a sorcery structure
714  * \param object_type_name Name of the object type to remove from
715  * \param wizard_type_name The name of the of the wizard type to remove
716  * \param wizard_args Opaque string originally passed to the wizard
717  *
718  * \retval 0 success
719  * \retval -1 failure
720  *
721  * \note If there were multiple instances of the same wizard type
722  * added to this object type without using \ref wizard_args, then
723  * only the first wizard matching wizard_type will be removed.
724  */
725 #define ast_sorcery_object_type_remove_wizard(sorcery, object_type_name, \
726  wizard_type_name, wizard_args) \
727  __ast_sorcery_object_type_remove_wizard((sorcery), (object_type_name), \
728  AST_MODULE, (wizard_type_name), (wizard_args))
729 
730 /*!
731  * \brief Remove an object wizard mapping
732  *
733  * \param sorcery Pointer to a sorcery structure
734  * \param type Type of object to remove from
735  * \param module The name of the module, typically AST_MODULE
736  * \param name The name of the wizard to remove
737  *
738  * \retval 0 success
739  * \retval -1 failure
740  *
741  * \since 13.4.0
742  */
744  const char *type, const char *module, const char *name);
745 
746 /*!
747  * \brief Remove an object wizard mapping
748  *
749  * \param sorcery Pointer to a sorcery structure
750  * \param type Type of object to remove from
751  * \param name The name of the wizard to remove
752  *
753  * \retval 0 success
754  * \retval -1 failure
755  *
756  * \since 13.4.0
757  */
758 #define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
759  __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
760 
761 /*!
762  * \brief Return the number of wizards mapped to an object type
763  *
764  * \param sorcery Pointer to a sorcery structure
765  * \param type Type of object
766  *
767  * \return Number of wizards or -1 for error
768  * \since 13.4.0
769  */
771  const char *type);
772 
773 /*!
774  * \brief By index, return a wizard mapped to an object type
775  *
776  * \param sorcery Pointer to a sorcery structure
777  * \param type Type of object
778  * \param index Index of the wizard
779  * \param wizard A pointer to receive the wizard pointer
780  * \param data A pointer to receive the data pointer
781  *
782  * \retval 0 success
783  * \retval -1 failure
784  *
785  * \warning The wizard will have its reference count bumped so you must
786  * call ao2_cleanup when you're done with it.
787  *
788  * \note The wizard and data returned are valid only for this object type
789  * and only while the wizard is applied to the object type.
790  *
791  * \since 13.4.0
792  */
793 int ast_sorcery_get_wizard_mapping(struct ast_sorcery *sorcery,
794  const char *type, int index, struct ast_sorcery_wizard **wizard, void **data);
795 
796 /*!
797  * \brief Unregister an object type
798  *
799  * \param sorcery Pointer to a sorcery structure
800  * \param type Type of object
801  *
802  * \retval 0 success
803  * \retval -1 failure
804  */
805 int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type);
806 
807 /*!
808  * \brief Register an object type
809  *
810  * \param sorcery Pointer to a sorcery structure
811  * \param type Type of object
812  * \param hidden All objects of this type are internal and should not be manipulated by users
813  * \param reloadable All objects of this type are reloadable
814  * \param alloc Required object allocation callback
815  * \param transform Optional transformation callback
816  * \param apply Optional object set apply callback
817  *
818  * \note In general, this function should not be used directly. One of the various
819  * macro'd versions should be used instead.
820  *
821  * \retval 0 success
822  * \retval -1 failure
823  */
824 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);
825 
826 /*!
827  * \brief Register an object type
828  *
829  * \param sorcery Pointer to a sorcery structure
830  * \param type Type of object
831  * \param alloc Required object allocation callback
832  * \param transform Optional transformation callback
833  * \param apply Optional object set apply callback
834  *
835  * \retval 0 success
836  * \retval -1 failure
837  */
838 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
839  __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
840 
841 /*!
842  * \brief Register an object type that is not reloadable
843  *
844  * \param sorcery Pointer to a sorcery structure
845  * \param type Type of object
846  * \param alloc Required object allocation callback
847  * \param transform Optional transformation callback
848  * \param apply Optional object set apply callback
849  *
850  * \retval 0 success
851  * \retval -1 failure
852  */
853 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
854  __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
855 
856 /*!
857  * \brief Register an internal, hidden object type
858  *
859  * \param sorcery Pointer to a sorcery structure
860  * \param type Type of object
861  * \param alloc Required object allocation callback
862  * \param transform Optional transformation callback
863  * \param apply Optional object set apply callback
864  *
865  * \retval 0 success
866  * \retval -1 failure
867  */
868 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
869  __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
870 
871 /*!
872  * \brief Set the high and low alert water marks of the sorcery object type.
873  * \since 13.10.0
874  *
875  * \param sorcery Pointer to a sorcery structure
876  * \param type Type of object
877  * \param low_water New queue low water mark. (-1 to set as 90% of high_water)
878  * \param high_water New queue high water mark.
879  *
880  * \retval 0 on success.
881  * \retval -1 on error (water marks not changed).
882  */
883 int ast_sorcery_object_set_congestion_levels(struct ast_sorcery *sorcery, const char *type, long low_water, long high_water);
884 
885 /*!
886  * \brief Set the copy handler for an object type
887  *
888  * \param sorcery Pointer to a sorcery structure
889  * \param type Type of object
890  * \param copy Copy handler
891  */
893 
894 /*!
895  * \brief Set the diff handler for an object type
896  *
897  * \param sorcery Pointer to a sorcery structure
898  * \param type Type of object
899  * \param diff Diff handler
900  */
901 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
902 
903 /*!
904  * \brief Register a regex for multiple fields within an object
905  *
906  * \param sorcery Pointer to a sorcery structure
907  * \param type Type of object
908  * \param regex A regular expression pattern for the fields
909  * \param config_handler A custom handler for translating the string representation of the fields
910  * \param sorcery_handler A custom handler for translating the native representation of the fields
911  *
912  * \retval 0 success
913  * \retval -1 failure
914  */
915 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
916  sorcery_fields_handler sorcery_handler);
917 
918 /*!
919  * \brief Register a field within an object
920  *
921  * \param sorcery Pointer to a sorcery structure
922  * \param type Type of object
923  * \param name Name of the field
924  * \param default_val Default value of the field
925  * \param config_handler A custom handler for translating the string representation of the fields
926  * \param sorcery_handler A custom handler for translating the native representation of the fields
927  * \param multiple_handler A custom handler for translating the native representation of the fields
928  * \param opt_type Option type
929  * \param flags Option type specific flags
930  * \param no_doc Field should not be documented
931  * \param alias Interpret and apply field value only
932  *
933  * \retval 0 success
934  * \retval -1 failure
935  */
936 int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type,
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 flags Option type specific flags
1018  *
1019  * \retval 0 success
1020  * \retval -1 failure
1021  */
1022 #define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1023  __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__);
1024 
1025 /*!
1026  * \brief Register a field within an object with custom handlers without documentation
1027  *
1028  * \param sorcery Pointer to a sorcery structure
1029  * \param type Type of object
1030  * \param name Name of the field
1031  * \param default_val Default value of the field
1032  * \param config_handler Custom configuration handler
1033  * \param sorcery_handler Custom sorcery handler
1034  * \param multiple_handler Custom multiple handler
1035  * \param flags Option type specific flags
1036  *
1037  * \retval 0 success
1038  * \retval -1 failure
1039  */
1040 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1041  __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__);
1042 
1043 /*!
1044  * \brief Inform any wizards to load persistent objects
1045  *
1046  * \param sorcery Pointer to a sorcery structure
1047  */
1048 void ast_sorcery_load(const struct ast_sorcery *sorcery);
1049 
1050 /*!
1051  * \brief Inform any wizards of a specific object type to load persistent objects
1052  *
1053  * \param sorcery Pointer to a sorcery structure
1054  * \param type Name of the object type to load
1055  */
1056 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
1057 
1058 /*!
1059  * \brief Inform any wizards to reload persistent objects
1060  *
1061  * \param sorcery Pointer to a sorcery structure
1062  */
1063 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
1064 
1065 /*!
1066  * \brief Inform any wizards to reload persistent objects, even if no changes determined
1067  *
1068  * \param sorcery Pointer to a sorcery structure
1069  *
1070  * \since 13.32.0
1071  * \since 16.9.0
1072  * \since 17.3.0
1073  */
1074 void ast_sorcery_force_reload(const struct ast_sorcery *sorcery);
1075 
1076 /*!
1077  * \brief Inform any wizards of a specific object type to reload persistent objects
1078  *
1079  * \param sorcery Pointer to a sorcery structure
1080  * \param type Name of the object type to reload
1081  */
1082 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
1083 
1084 /*!
1085  * \brief Inform any wizards of a specific object type to reload persistent objects
1086  * even if no changes determined
1087  *
1088  * \param sorcery Pointer to a sorcery structure
1089  * \param type Name of the object type to reload
1090  *
1091  * \since 13.32.0
1092  * \since 16.9.0
1093  * \since 17.3.0
1094  */
1095 void ast_sorcery_force_reload_object(const struct ast_sorcery *sorcery, const char *type);
1096 
1097 /*!
1098  * \brief Increase the reference count of a sorcery structure
1099  *
1100  * \param sorcery Pointer to a sorcery structure
1101  */
1102 void ast_sorcery_ref(struct ast_sorcery *sorcery);
1103 
1104 
1105 /*!
1106  * \brief Create an object set (KVP list) for an object
1107  *
1108  * \param sorcery Pointer to a sorcery structure
1109  * \param object Pointer to a sorcery object
1110  * \param flags Flags indicating which handler to use and in what order.
1111  *
1112  * \retval non-NULL success
1113  * \retval NULL if error occurred
1114  *
1115  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1116  */
1117 struct ast_variable *ast_sorcery_objectset_create2(const struct ast_sorcery *sorcery,
1118  const void *object, enum ast_sorcery_field_handler_flags flags);
1119 
1120 /*!
1121  * \brief Create an object set (KVP list) for an object
1122  *
1123  * \param sorcery Pointer to a sorcery structure
1124  * \param object Pointer to a sorcery object
1125  *
1126  * \retval non-NULL success
1127  * \retval NULL if error occurred
1128  *
1129  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1130  *
1131  * \note This function attempts to use a field's sorcery_fields_handler first and if that
1132  * doesn't exist or fails, a field's sorcery_field_handler is used. The difference is
1133  * that the former may return multiple list entries for the same field and the latter will only
1134  * return 1. It's up to the field itself to determine what the appropriate content is.
1135  */
1136 #define ast_sorcery_objectset_create(sorcery, object) \
1137  ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
1138 
1139 /*!
1140  * \brief Create an object set in JSON format for an object
1141  *
1142  * \param sorcery Pointer to a sorcery structure
1143  * \param object Pointer to a sorcery object
1144  *
1145  * \retval non-NULL success
1146  * \retval NULL if error occurred
1147  *
1148  * \note The returned ast_json object must be unreferenced using ast_json_unref
1149  */
1150 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
1151 
1152 /*!
1153  * \brief Apply an object set (KVP list) to an object
1154  *
1155  * \param sorcery Pointer to a sorcery structure
1156  * \param object Pointer to a sorcery object
1157  * \param objectset Object set itself
1158  *
1159  * \retval 0 success
1160  * \retval -1 failure
1161  *
1162  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
1163  * applied object set.
1164  */
1165 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
1166 
1167 /*!
1168  * \brief Create a changeset given two object sets
1169  *
1170  * \param original Original object set
1171  * \param modified Modified object set
1172  * \param changes Pointer to hold any changes between the object sets
1173  *
1174  * \retval 0 success
1175  * \retval -1 failure
1176  *
1177  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1178  */
1179 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
1180 
1181 /*!
1182  * \brief Allocate a generic sorcery capable object
1183  *
1184  * \param size Size of the object
1185  * \param destructor Optional destructor function
1186  *
1187  * \retval non-NULL success
1188  * \retval NULL failure
1189  *
1190  * \note The returned object does not support AO2 locking.
1191  */
1192 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
1193 
1194 /*!
1195  * \since 14.1.0
1196  * \brief Allocate a generic sorcery capable object with locking.
1197  *
1198  * \details Sorcery objects may be replaced with new allocations during reloads.
1199  * If locking is required on sorcery objects it must be shared between the old
1200  * object and the new one. lockobj can be any AO2 object with locking enabled,
1201  * but in most cases named locks should be used to provide stable locking.
1202  *
1203  * \param size Size of the object
1204  * \param destructor Optional destructor function
1205  * \param lockobj An AO2 object that will provide locking.
1206  *
1207  * \retval non-NULL success
1208  * \retval NULL failure
1209  */
1210 void *ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj);
1211 
1212 /*!
1213  * \brief Allocate an object
1214  *
1215  * \param sorcery Pointer to a sorcery structure
1216  * \param type Type of object to allocate
1217  * \param id Optional unique identifier, if none is provided one will be generated
1218  *
1219  * \retval non-NULL success
1220  * \retval NULL failure
1221  */
1222 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
1223 
1224 /*!
1225  * \brief Create a copy of an object
1226  *
1227  * \param sorcery Pointer to a sorcery structure
1228  * \param object Existing object
1229  *
1230  * \retval non-NULL success
1231  * \retval NULL failure
1232  */
1233 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
1234 
1235 /*!
1236  * \brief Create a changeset of two objects
1237  *
1238  * \param sorcery Pointer to a sorcery structure
1239  * \param original Original object
1240  * \param modified Modified object
1241  * \param changes Pointer which will be populated with changes if any exist
1242  *
1243  * \retval 0 success
1244  * \retval -1 failure
1245  *
1246  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1247  *
1248  * \note While the objects must be of the same type they do not have to be the same object
1249  */
1250 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
1251 
1252 /*!
1253  * \brief Add a global observer to sorcery
1254  *
1255  * \param callbacks Implementation of the global observer interface
1256  *
1257  * \retval 0 success
1258  * \retval -1 failure
1259  *
1260  * \note You must be ready to accept observer invocations before this function is called
1261  */
1263 
1264 /*!
1265  * \brief Remove a global observer from sorcery.
1266  *
1267  * A global observer is notified...
1268  * After a new wizard is registered.
1269  * After a new sorcery instance is opened.
1270  * Before an instance is destroyed.
1271  * Before a wizard is unregistered.
1272  *
1273  * \param callbacks Implementation of the global observer interface
1274  */
1276 
1277 /*!
1278  * \brief Add an observer to a sorcery instance
1279  *
1280  * \param sorcery Pointer to a sorcery structure
1281  * \param callbacks Implementation of the instance observer interface
1282  *
1283  * An instance observer is notified...
1284  * Before an instance is loaded or reloaded.
1285  * After an instance is loaded or reloaded.
1286  * After a wizard is mapped to an object type.
1287  * After an object type is registered.
1288  * Before an object type is loaded or reloaded.
1289  * After an object type is loaded or reloaded.
1290  *
1291  * \retval 0 success
1292  * \retval -1 failure
1293  *
1294  * \note You must be ready to accept observer invocations before this function is called
1295  */
1297  const struct ast_sorcery_instance_observer *callbacks);
1298 
1299 /*!
1300  * \brief Remove an observer from a sorcery instance
1301  *
1302  * \param sorcery Pointer to a sorcery structure
1303  * \param callbacks Implementation of the instance observer interface
1304  */
1306  const struct ast_sorcery_instance_observer *callbacks);
1307 
1308 /*!
1309  * \brief Add an observer to a sorcery wizard
1310  *
1311  * \param sorcery Pointer to a previously registered wizard structure
1312  * \param callbacks Implementation of the wizard observer interface
1313  *
1314  * A wizard observer is notified...
1315  * Before a wizard is loaded or reloaded.
1316  * After a wizard is loaded or reloaded.
1317  *
1318  * \retval 0 success
1319  * \retval -1 failure
1320  *
1321  * \note You must be ready to accept observer invocations before this function is called
1322  */
1324  const struct ast_sorcery_wizard_observer *callbacks);
1325 
1326 /*!
1327  * \brief Remove an observer from a sorcery wizard.
1328  *
1329  * \param sorcery Pointer to a sorcery structure
1330  * \param callbacks Implementation of the wizard observer interface
1331  */
1333  const struct ast_sorcery_wizard_observer *callbacks);
1334 
1335 /*!
1336  * \brief Add an observer to a specific object type
1337  *
1338  * \param sorcery Pointer to a sorcery structure
1339  * \param type Type of object that should be observed
1340  * \param callbacks Implementation of the observer interface
1341  *
1342  * \retval 0 success
1343  * \retval -1 failure
1344  *
1345  * \note You must be ready to accept observer invocations before this function is called
1346  */
1347 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1348 
1349 /*!
1350  * \brief Remove an observer from a specific object type
1351  *
1352  * \param sorcery Pointer to a sorcery structure
1353  * \param type Type of object that should no longer be observed
1354  * \param callbacks Implementation of the observer interface
1355  *
1356  * \retval 0 success
1357  * \retval -1 failure
1358  */
1359 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1360 
1361 /*!
1362  * \brief Create and potentially persist an object using an available wizard
1363  *
1364  * \param sorcery Pointer to a sorcery structure
1365  * \param object Pointer to a sorcery object
1366  *
1367  * \retval 0 success
1368  * \retval -1 failure
1369  */
1370 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
1371 
1372 /*!
1373  * \brief Retrieve an object using its unique identifier
1374  *
1375  * \param sorcery Pointer to a sorcery structure
1376  * \param type Type of object to retrieve
1377  * \param id Unique object identifier
1378  *
1379  * \retval non-NULL if found
1380  * \retval NULL if not found
1381  */
1382 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
1383 
1384 /*!
1385  * \brief Retrieve an object or multiple objects using specific fields
1386  * \since 13.9.0
1387  *
1388  * \param sorcery Pointer to a sorcery structure
1389  * \param type Type of object to retrieve
1390  * \param flags Flags to control behavior
1391  * \param fields Optional object fields and values to match against
1392  *
1393  * \retval non-NULL if found
1394  * \retval NULL if not found
1395  *
1396  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
1397  * ao2_container that must be unreferenced after use.
1398  *
1399  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
1400  * of the given type.
1401  *
1402  * \note The fields parameter can contain realtime-style expressions in variable->name.
1403  * All operators defined for ast_strings_match can be used except for regex as
1404  * there's no common support for regex in the realtime backends at this time.
1405  * If multiple variables are in the fields list, all must match for an object to
1406  * be returned. See ast_strings_match for more information.
1407  *
1408  * Example:
1409  *
1410  * The following code can be significantly faster when a realtime backend is in use
1411  * because the expression "qualify_frequency > 0" is passed to the database to limit
1412  * the number of rows returned.
1413  *
1414  * struct ast_variable *var = ast_variable_new("qualify_frequency >", "0", "");
1415  * struct ao2_container *aors;
1416  *
1417  * if (!var) {
1418  * return;
1419  * }
1420  *
1421  * aors = ast_sorcery_retrieve_by_fields(ast_sip_get_sorcery(),
1422  * "aor", AST_RETRIEVE_FLAG_MULTIPLE, var);
1423  *
1424  */
1425 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
1426 
1427 /*!
1428  * \brief Retrieve multiple objects using a regular expression on their id
1429  *
1430  * \param sorcery Pointer to a sorcery structure
1431  * \param type Type of object to retrieve
1432  * \param regex Regular expression
1433  *
1434  * \retval non-NULL if error occurs
1435  * \retval NULL success
1436  *
1437  * \note The provided regex is treated as extended case sensitive.
1438  */
1439 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
1440 
1441 /*!
1442  * \brief Retrieve multiple objects whose id begins with the specified prefix
1443  * \since 13.19.0
1444  *
1445  * \param sorcery Pointer to a sorcery structure
1446  * \param type Type of object to retrieve
1447  * \param prefix Object id prefix
1448  * \param prefix_len The length of prefix in bytes
1449  *
1450  * \retval non-NULL if error occurs
1451  * \retval NULL success
1452  *
1453  * \note The prefix is matched in a case sensitive manner.
1454  */
1455 struct ao2_container *ast_sorcery_retrieve_by_prefix(const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len);
1456 
1457 /*!
1458  * \brief Update an object
1459  *
1460  * \param sorcery Pointer to a sorcery structure
1461  * \param object Pointer to a sorcery object
1462  *
1463  * \retval 0 success
1464  * \retval -1 failure
1465  */
1466 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
1467 
1468 /*!
1469  * \brief Delete an object
1470  *
1471  * \param sorcery Pointer to a sorcery structure
1472  * \param object Pointer to a sorcery object
1473  *
1474  * \retval 0 success
1475  * \retval -1 failure
1476  */
1477 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
1478 
1479 /*!
1480  * \brief Determine if a sorcery object is stale with respect to its backing datastore
1481  * \since 14.0.0
1482  *
1483  * This function will query the wizard(s) backing the particular sorcery object to
1484  * determine if the in-memory object is now stale. No action is taken to update
1485  * the object. Callers of this function may use one of the ast_sorcery_retrieve
1486  * functions to obtain a new instance of the object if desired.
1487  *
1488  * \retval 0 the object is not stale
1489  * \retval 1 the object is stale
1490  */
1491 int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
1492 
1493 /*!
1494  * \brief Decrease the reference count of a sorcery structure
1495  *
1496  * \param sorcery Pointer to a sorcery structure
1497  *
1498  * \note Prior to 16.0.0 this was a function which had to be used.
1499  * Now you can use any variant of ao2_cleanup or ao2_ref to
1500  * release a reference.
1501  */
1502 #define ast_sorcery_unref(sorcery) \
1503  ao2_cleanup(sorcery)
1504 
1505 /*!
1506  * \brief Get the unique identifier of a sorcery object
1507  *
1508  * \param object Pointer to a sorcery object
1509  *
1510  * \retval unique identifier
1511  */
1512 const char *ast_sorcery_object_get_id(const void *object);
1513 
1514 /*!
1515  * \since 14.0.0
1516  * \brief Get when the socery object was created
1517  *
1518  * \param object Pointer to a sorcery object
1519  *
1520  * \retval The time when the object was created
1521  */
1522 const struct timeval ast_sorcery_object_get_created(const void *object);
1523 
1524 /*!
1525  * \brief Get the type of a sorcery object
1526  *
1527  * \param object Pointer to a sorcery object
1528  *
1529  * \retval type of object
1530  */
1531 const char *ast_sorcery_object_get_type(const void *object);
1532 
1533 /*!
1534  * \brief Get an extended field value from a sorcery object
1535  *
1536  * \param object Pointer to a sorcery object
1537  * \param name Name of the extended field value
1538  *
1539  * \retval non-NULL if found
1540  * \retval NULL if not found
1541  *
1542  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
1543  */
1544 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
1545 
1546 /*!
1547  * \brief Set an extended field value on a sorcery object
1548  *
1549  * \param object Pointer to a sorcery object
1550  * \param name Name of the extended field
1551  * \param value Value of the extended field
1552  *
1553  * \retval 0 success
1554  * \retval -1 failure
1555  *
1556  * \note The field name MUST begin with '@' to indicate it is an extended field.
1557  * \note If the extended field already exists it will be overwritten with the new value.
1558  */
1559 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
1560 
1561 /*!
1562  * \brief Get whether an object contains dynamic contents or not
1563  *
1564  * \param object Pointer to a sorcery object
1565  *
1566  * \since 19
1567  * \since 18.3.0
1568  * \since 16.17.0
1569  */
1570 unsigned int ast_sorcery_object_has_dynamic_contents(const void *object);
1571 
1572 /*!
1573  * \brief Set the dynamic contents flag on a sorcery object
1574  *
1575  * \param object Pointer to a sorcery object
1576  *
1577  * \since 19
1578  * \since 18.3.0
1579  * \since 16.17.0
1580  */
1581 void ast_sorcery_object_set_has_dynamic_contents(const void *object);
1582 
1583 /*!
1584  * \brief ao2 object comparator based on sorcery id.
1585  */
1586 int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
1587 
1588 /*!
1589  * \brief ao2 object sorter based on sorcery id.
1590  */
1591 int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
1592 
1593 /*!
1594  * \brief ao2 object hasher based on sorcery id.
1595  */
1596 int ast_sorcery_object_id_hash(const void *obj, int flags);
1597 
1598 /*!
1599  * \brief Get the sorcery object type given a type name.
1600  *
1601  * \param sorcery The sorcery from which to retrieve the object type
1602  * \param type The type name
1603  */
1605  const char *type);
1606 
1607 /*!
1608  * \brief Determine if a particular object field has been registered with sorcery
1609  *
1610  * \param object_type The object type to check against
1611  * \param field_name The name of the field to check
1612  *
1613  * \retval 0 The field is not registered for this sorcery type
1614  * \retval 1 The field is registered for this sorcery type
1615  */
1617  const char *field_name);
1618 
1619 /*!
1620  * \brief Get the module that has opened the provided sorcery instance.
1621  *
1622  * \param sorcery The sorcery instance
1623  *
1624  * \return The module
1625  */
1626 const char *ast_sorcery_get_module(const struct ast_sorcery *sorcery);
1627 
1628 #if defined(__cplusplus) || defined(c_plusplus)
1629 }
1630 #endif
1631 
1632 #endif /* _ASTERISK_SORCERY_H */
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.
Definition: sorcery.h:134
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
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
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
unsigned int ast_sorcery_object_has_dynamic_contents(const void *object)
Get whether an object contains dynamic contents or not.
Definition: sorcery.c:2372
ast_sorcery_field_handler_flags
Field handler flags.
Definition: sorcery.h:129
enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast_sorcery *sorcery, const char *object_type_name, const char *module, const char *wizard_type_name, const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position, struct ast_sorcery_wizard **wizard, void **wizard_data)
Insert an additional object wizard mapping at a specific position in the wizard list returning wizard...
Definition: sorcery.c:869
int ast_sorcery_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
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
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
static int reload(void)
void(* instance_created)(const char *name, struct ast_sorcery *sorcery)
Callback after an instance is created.
Definition: sorcery.h:222
static void update(int code_size, int y, int wi, int fi, int dq, int sr, int dqsez, struct g726_state *state_ptr)
Definition: codec_g726.c:367
Interface for the global sorcery observer.
Definition: sorcery.h:220
int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module)
Register a sorcery wizard.
Definition: sorcery.c:432
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
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
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_sorcery * __ast_sorcery_open(const char *module, const char *file, int line, const char *func)
Open a new sorcery structure.
Definition: sorcery.c:601
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
Structure for variables, used for configurations and for channel variables.
static int loaded
Definition: cdr_csv.c:58
Universally unique identifier support.
Use list handler only.
Definition: sorcery.h:140
Perform no matching, return all objects.
Definition: sorcery.h:123
int ast_sorcery_object_id_compare(void *obj, void *arg, int flags)
ao2 object comparator based on sorcery id.
Definition: sorcery.c:2459
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 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_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
Full structure for sorcery.
Definition: sorcery.c:230
void(* wizard_registered)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback after an wizard is registered.
Definition: sorcery.h:225
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
static int copy(char *infile, char *outfile)
Utility function to copy a file.
Return all matching objects.
Definition: sorcery.h:120
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
struct ast_module * module
Pointer to the Asterisk module this wizard is implemented by.
Definition: sorcery.h:281
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
const char * args
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
int value
Definition: syslog.c:37
const char * name
Name of the wizard.
Definition: sorcery.h:278
int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks)
Add a global observer to sorcery.
Definition: sorcery.c:498
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_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_retrieve_flags
Retrieval flags.
Definition: sorcery.h:115
int ast_sorcery_init(void)
Initialize the sorcery API.
Definition: sorcery.c:387
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_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
const char * ast_sorcery_object_get_type(const void *object)
Get the type of a sorcery object.
Definition: sorcery.c:2324
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
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
ast_sorcery_wizard_position
Pre-defined locations to insert at.
Definition: sorcery.h:518
void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks)
Remove a global observer from sorcery.
Definition: sorcery.c:514
const struct timeval ast_sorcery_object_get_created(const void *object)
Get when the socery object was created.
Definition: sorcery.c:2318
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_create(const struct ast_sorcery *sorcery, void *object)
Create and potentially persist an object using an available wizard.
Definition: sorcery.c:2057
ast_sorcery_wizard_apply_flags
Wizard Apply Flags.
Definition: sorcery.h:576
ast_sorcery_apply_result
Definition: sorcery.h:424
void *(* aco_type_item_alloc)(const char *category)
Allocate a configurable ao2 object.
Structure for registered object type.
Definition: sorcery.c:148
void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *wizard, const struct ast_sorcery_wizard_observer *callbacks)
Remove an observer from a sorcery wizard.
Definition: sorcery.c:568
int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type)
Unregister an object type.
Definition: sorcery.c:1061
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
Interface for the sorcery instance observer.
Definition: sorcery.h:237
Use string handler only.
Definition: sorcery.h:137
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 char * ast_sorcery_object_get_id(const void *object)
Get the unique identifier of a sorcery object.
Definition: sorcery.c:2312
Structure for internal sorcery object information.
Definition: sorcery.c:127
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
void(* instance_destroying)(const char *name, struct ast_sorcery *sorcery)
Callback before an instance is destroyed.
Definition: sorcery.h:229
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.
Definition: sorcery.c:2489
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
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
Default retrieval flags.
Definition: sorcery.h:117
Configuration option-handling.
int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object)
Delete an object.
Definition: sorcery.c:2233
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
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
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
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
int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface)
Unregister a sorcery wizard.
Definition: sorcery.c:474
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
Interface for a sorcery object type observer.
Definition: sorcery.h:332
void(* ao2_destructor_fn)(void *vdoomed)
Typedef for an object destructor.
Definition: astobj2.h:360
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_config(struct ast_sorcery *sorcery, const char *name, const char *module)
Apply configured wizard mappings.
Definition: sorcery.c:985
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
static int regex(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
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
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_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
Interface for a sorcery wizard.
Definition: sorcery.h:276
void ast_sorcery_load(const struct ast_sorcery *sorcery)
Inform any wizards to load persistent objects.
Definition: sorcery.c:1377
void ast_sorcery_object_set_has_dynamic_contents(const void *object)
Set the dynamic contents flag on a sorcery object.
Definition: sorcery.c:2379
void ast_sorcery_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects.
Definition: sorcery.c:1408
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
static struct ast_sorcery * sorcery
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
Interface for the sorcery wizard observer.
Definition: sorcery.h:265
void * ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object)
Create a copy of an object.
Definition: sorcery.c:1778
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
int ast_sorcery_object_id_hash(const void *obj, int flags)
ao2 object hasher based on sorcery id.
Definition: sorcery.c:2470
Try both handlers, string first.
Definition: sorcery.h:131
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.
Definition: sorcery.c:1565
enum queue_result id
Definition: app_queue.c:1513
Generic container type.
void ast_sorcery_ref(struct ast_sorcery *sorcery)
Increase the reference count of a sorcery structure.
Definition: sorcery.c:1473
void * ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor)
Allocate a generic sorcery capable object.
Definition: sorcery.c:1728
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 __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_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
void(* wizard_unregistering)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback before a wizard is unregistered.
Definition: sorcery.h:232
struct ast_sorcery * ast_sorcery_retrieve_by_module_name(const char *module)
Retrieves an existing sorcery instance by module name.
Definition: sorcery.c:672
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
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
int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object)
Update an object.
Definition: sorcery.c:2145
static char prefix[MAX_PREFIX]
Definition: http.c:141
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352