Fix stuck channel in ARI through the introduction of synchronous bridge actions.
[asterisk/asterisk.git] / include / asterisk / sorcery.h
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  */
115 enum ast_sorcery_retrieve_flags {
116         /*! \brief Default retrieval flags */
117         AST_RETRIEVE_FLAG_DEFAULT = 0,
118
119         /*! \brief Return all matching objects */
120         AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
121
122         /*! \brief Perform no matching, return all objects */
123         AST_RETRIEVE_FLAG_ALL = (1 << 1),
124 };
125
126 /*!
127  * \brief Field handler flags
128  */
129 enum ast_sorcery_field_handler_flags {
130         /*! \brief Try both handlers, string first */
131         AST_HANDLER_PREFER_STRING,
132
133         /*! \brief Try both handlers, list first */
134         AST_HANDLER_PREFER_LIST,
135
136         /*! \brief Use string handler only */
137         AST_HANDLER_ONLY_STRING,
138
139         /*! \brief Use list handler only */
140         AST_HANDLER_ONLY_LIST,
141 };
142
143
144 /*! \brief Forward declaration for the sorcery main structure */
145 struct ast_sorcery;
146
147 /*!
148  * \brief A callback function for translating a value into a string
149  *
150  * \param obj Object to get value from
151  * \param args Where the field is
152  * \param buf Pointer to the buffer that the handler has created which contains the field value
153  *
154  * \retval 0 success
155  * \retval -1 failure
156  */
157 typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
158
159 /*!
160  * \brief A callback function for translating multiple values into an ast_variable list
161  *
162  * \param obj Object to get values from
163  * \param fields Pointer to store the list of fields
164  *
165  * \retval 0 success
166  * \retval -1 failure
167  */
168 typedef int (*sorcery_fields_handler)(const void *obj, struct ast_variable **fields);
169
170 /*!
171  * \brief A callback function for performing a transformation on an object set
172  *
173  * \param set The existing object set
174  *
175  * \retval non-NULL new object set if changed
176  * \retval NULL if no changes present
177  *
178  * \note The returned ast_variable list must be *new*. You can not return the input set.
179  */
180 typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
181
182 /*!
183  * \brief A callback function for when an object set is successfully applied to an object
184  *
185  * \note On a failure return, the state of the object is left undefined. It is a bad
186  * idea to try to use this object.
187  *
188  * \param sorcery Sorcery structure in use
189  * \param obj The object itself
190  * \retval 0 Success
191  * \retval non-zero Failure
192  */
193 typedef int (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
194
195 /*!
196  * \brief A callback function for copying the contents of one object to another
197  *
198  * \param src The source object
199  * \param dst The destination object
200  *
201  * \retval 0 success
202  * \retval -1 failure
203  */
204 typedef int (*sorcery_copy_handler)(const void *src, void *dst);
205
206 /*!
207  * \brief A callback function for generating a changeset between two objects
208  *
209  * \param original The original object
210  * \param modified The modified object
211  * \param changes The changeset
212  *
213  * \param 0 success
214  * \param -1 failure
215  */
216 typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
217
218 /*! \brief Interface for a sorcery wizard */
219 struct ast_sorcery_wizard {
220         /*! \brief Name of the wizard */
221         const char *name;
222
223         /*! \brief Pointer to the Asterisk module this wizard is implemented by */
224         struct ast_module *module;
225
226         /*! \brief Callback for opening a wizard */
227         void *(*open)(const char *data);
228
229         /*! \brief Optional callback for loading persistent objects */
230         void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
231
232         /*! \brief Optional callback for reloading persistent objects */
233         void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
234
235         /*! \brief Callback for creating an object */
236         int (*create)(const struct ast_sorcery *sorcery, void *data, void *object);
237
238         /*! \brief Callback for retrieving an object using an id */
239         void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
240
241         /*! \brief Callback for retrieving multiple objects using a regex on their id */
242         void (*retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
243
244         /*! \brief Optional callback for retrieving an object using fields */
245         void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
246
247         /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
248         void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
249
250         /*! \brief Callback for updating an object */
251         int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
252
253         /*! \brief Callback for deleting an object */
254         int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
255
256         /*! \brief Callback for closing a wizard */
257         void (*close)(void *data);
258 };
259
260 /*! \brief Interface for a sorcery object type observer */
261 struct ast_sorcery_observer {
262         /*! \brief Callback for when an object is created */
263         void (*created)(const void *object);
264
265         /*! \brief Callback for when an object is updated */
266         void (*updated)(const void *object);
267
268         /*! \brief Callback for when an object is deleted */
269         void (*deleted)(const void *object);
270
271         /*! \brief Callback for when an object type is loaded/reloaded */
272         void (*loaded)(const char *object_type);
273 };
274
275 /*! \brief Opaque structure for internal sorcery object */
276 struct ast_sorcery_object;
277
278 /*! \brief Structure which contains details about a sorcery object */
279 struct ast_sorcery_object_details {
280         /*! \brief Pointer to internal sorcery object information */
281         struct ast_sorcery_object *object;
282 };
283
284 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
285 #define SORCERY_OBJECT(details)                    \
286 struct {                                           \
287         struct ast_sorcery_object_details details; \
288 }                                                  \
289
290 /*!
291  * \brief Initialize the sorcery API
292  *
293  * \retval 0 success
294  * \retval -1 failure
295  */
296 int ast_sorcery_init(void);
297
298 /*!
299  * \brief Register a sorcery wizard
300  *
301  * \param interface Pointer to a wizard interface
302  * \param module Pointer to the module implementing the interface
303  *
304  * \retval 0 success
305  * \retval -1 failure
306  */
307 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
308
309 /*!
310  * \brief See \ref __ast_sorcery_wizard_register()
311  */
312 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, ast_module_info ? ast_module_info->self : NULL)
313
314 /*!
315  * \brief Unregister a sorcery wizard
316  *
317  * \param interface Pointer to the wizard interface
318  *
319  * \retval 0 success
320  * \retval -1 failure
321  */
322 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
323
324 /*!
325  * \brief Open a new sorcery structure
326  *
327  * \param module The module name (AST_MODULE)
328  *
329  * When called, this will automatically also call __ast_sorcery_apply_config()
330  * with the module name as the configuration section.
331  *
332  * \retval non-NULL success
333  * \retval NULL if allocation failed
334  */
335 struct ast_sorcery *__ast_sorcery_open(const char *module);
336
337 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE)
338
339 /*!
340  * \brief Retrieves an existing sorcery instance by module name
341  *
342  * \param module The module name
343  *
344  * \retval non-NULL success
345  * \retval NULL if no instance was found
346  *
347  * \note The returned instance has its reference count incremented.  The caller
348  * must decrement the count when they're finished with it.
349  *
350  */
351 struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
352
353 enum ast_sorcery_apply_result {
354         /*! Sorcery wizard failed to apply. */
355         AST_SORCERY_APPLY_FAIL = -1,
356         /*! Sorcery wizard applied successfully. */
357         AST_SORCERY_APPLY_SUCCESS = 0,
358         /*! Sorcery wizard has already been applied to the object type. */
359         AST_SORCERY_APPLY_DUPLICATE = 1,
360         /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
361         AST_SORCERY_APPLY_DEFAULT_UNNECESSARY = 2,
362 };
363
364 /*!
365  * \brief Apply configured wizard mappings
366  *
367  * \param sorcery Pointer to a sorcery structure
368  * \param name Name of the category to use within the configuration file, normally the module name
369  * \param module The module name (AST_MODULE)
370  *
371  * This function is called automatically by __ast_sorcery_open() using the module name as the
372  * configuration category. The only reason you should call this function is if your module
373  * wishes to apply configuration from additional sections of sorcery.conf.
374  *
375  * If a configuration section attempts to apply the same sorcery wizard to an object type
376  * more than once, the wizard will only be applied one time.
377  *
378  * \return What happened when attempting to apply the default.
379  */
380 enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery,
381                 const char *name, const char *module);
382
383 #define ast_sorcery_apply_config(sorcery, name) \
384         __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
385
386 /*!
387  * \brief Apply default object wizard mappings
388  *
389  * \param sorcery Pointer to a sorcery structure
390  * \param type Type of object to apply to
391  * \param module The name of the module, typically AST_MODULE
392  * \param name Name of the wizard to use
393  * \param data Data to be passed to wizard
394  *
395  * \return What occurred when applying the default
396  *
397  * \note This should be called *after* applying configuration sourced mappings
398  *
399  * \note Only a single default can exist per object type
400  */
401 enum ast_sorcery_apply_result __ast_sorcery_apply_default(struct ast_sorcery *sorcery,
402                 const char *type, const char *module, const char *name, const char *data);
403
404 #define ast_sorcery_apply_default(sorcery, type, name, data) \
405         __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
406
407 /*!
408  * \brief Register an object type
409  *
410  * \param sorcery Pointer to a sorcery structure
411  * \param type Type of object
412  * \param hidden All objects of this type are internal and should not be manipulated by users
413  * \param reloadable All objects of this type are reloadable
414  * \param alloc Required object allocation callback
415  * \param transform Optional transformation callback
416  * \param apply Optional object set apply callback
417  *
418  * \note In general, this function should not be used directly. One of the various
419  * macro'd versions should be used instead.
420  *
421  * \retval 0 success
422  * \retval -1 failure
423  */
424 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);
425
426 /*!
427  * \brief Register an object type
428  *
429  * \param sorcery Pointer to a sorcery structure
430  * \param type Type of object
431  * \param alloc Required object allocation callback
432  * \param transform Optional transformation callback
433  * \param apply Optional object set apply callback
434  *
435  * \retval 0 success
436  * \retval -1 failure
437  */
438 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
439         __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
440
441 /*!
442  * \brief Register an object type that is not reloadable
443  *
444  * \param sorcery Pointer to a sorcery structure
445  * \param type Type of object
446  * \param alloc Required object allocation callback
447  * \param transform Optional transformation callback
448  * \param apply Optional object set apply callback
449  *
450  * \retval 0 success
451  * \retval -1 failure
452  */
453 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
454         __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
455
456 /*!
457  * \brief Register an internal, hidden object type
458  *
459  * \param sorcery Pointer to a sorcery structure
460  * \param type Type of object
461  * \param alloc Required object allocation callback
462  * \param transform Optional transformation callback
463  * \param apply Optional object set apply callback
464  *
465  * \retval 0 success
466  * \retval -1 failure
467  */
468 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
469         __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
470
471 /*!
472  * \brief Set the copy handler for an object type
473  *
474  * \param sorcery Pointer to a sorcery structure
475  * \param type Type of object
476  * \param copy Copy handler
477  */
478 void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
479
480 /*!
481  * \brief Set the diff handler for an object type
482  *
483  * \param sorcery Pointer to a sorcery structure
484  * \param type Type of object
485  * \param diff Diff handler
486  */
487 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
488
489 /*!
490  * \brief Register a regex for multiple fields within an object
491  *
492  * \param sorcery Pointer to a sorcery structure
493  * \param type Type of object
494  * \param regex A regular expression pattern for the fields
495  * \param config_handler A custom handler for translating the string representation of the fields
496  * \param sorcery_handler A custom handler for translating the native representation of the fields
497  *
498  * \retval 0 success
499  * \retval -1 failure
500  */
501 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
502                                                                            sorcery_fields_handler sorcery_handler);
503
504 /*!
505  * \brief Register a field within an object
506  *
507  * \param sorcery Pointer to a sorcery structure
508  * \param type Type of object
509  * \param name Name of the field
510  * \param default_val Default value of the field
511  * \param config_handler A custom handler for translating the string representation of the fields
512  * \param sorcery_handler A custom handler for translating the native representation of the fields
513  * \param multiple_handler A custom handler for translating the native representation of the fields
514  * \param opt_type Option type
515  * \param flags Option type specific flags
516  * \param no_doc Field should not be documented
517  * \param alias Interpret and apply field value only
518  *
519  * \retval 0 success
520  * \retval -1 failure
521  */
522 int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type,
523         const char *name, const char *default_val, enum aco_option_type opt_type,
524         aco_option_handler config_handler, sorcery_field_handler sorcery_handler,
525         sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc,
526         unsigned int alias, size_t argc, ...);
527
528 /*!
529  * \brief Register a field within an object
530  *
531  * \param sorcery Pointer to a sorcery structure
532  * \param type Type of object
533  * \param name Name of the field
534  * \param default_val Default value of the field
535  * \param opt_type Option type
536  * \param flags Option type specific flags
537  *
538  * \retval 0 success
539  * \retval -1 failure
540  */
541 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
542     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
543
544 /*!
545  * \brief Register a field within an object as an alias
546  *
547  * \param sorcery Pointer to a sorcery structure
548  * \param type Type of object
549  * \param name Name of the field
550  * \param default_val Default value of the field
551  * \param opt_type Option type
552  * \param flags Option type specific flags
553  *
554  * \retval 0 success
555  * \retval -1 failure
556  */
557 #define ast_sorcery_object_field_register_alias(sorcery, type, name, default_val, opt_type, flags, ...) \
558     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
559
560 /*!
561  * \brief Register a field within an object without documentation
562  *
563  * \param sorcery Pointer to a sorcery structure
564  * \param type Type of object
565  * \param name Name of the field
566  * \param default_val Default value of the field
567  * \param opt_type Option type
568  * \param flags Option type specific flags
569  *
570  * \retval 0 success
571  * \retval -1 failure
572  */
573 #define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
574     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
575
576 /*!
577  * \brief Register a field within an object with custom handlers
578  *
579  * \param sorcery Pointer to a sorcery structure
580  * \param type Type of object
581  * \param name Name of the field
582  * \param default_val Default value of the field
583  * \param config_handler Custom configuration handler
584  * \param sorcery_handler Custom sorcery handler
585  * \param multiple_handler Custom multiple handler
586  * \param flags Option type specific flags
587  *
588  * \retval 0 success
589  * \retval -1 failure
590  */
591 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
592     __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__);
593
594 /*!
595  * \brief Register a field within an object with custom handlers as an alias
596  *
597  * \param sorcery Pointer to a sorcery structure
598  * \param type Type of object
599  * \param name Name of the field
600  * \param default_val Default value of the field
601  * \param config_handler Custom configuration handler
602  * \param sorcery_handler Custom sorcery handler
603  * \param flags Option type specific flags
604  *
605  * \retval 0 success
606  * \retval -1 failure
607  */
608 #define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
609     __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__);
610
611 /*!
612  * \brief Register a field within an object with custom handlers without documentation
613  *
614  * \param sorcery Pointer to a sorcery structure
615  * \param type Type of object
616  * \param name Name of the field
617  * \param default_val Default value of the field
618  * \param config_handler Custom configuration handler
619  * \param sorcery_handler Custom sorcery handler
620  * \param multiple_handler Custom multiple handler
621  * \param flags Option type specific flags
622  *
623  * \retval 0 success
624  * \retval -1 failure
625  */
626 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
627     __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__);
628
629 /*!
630  * \brief Inform any wizards to load persistent objects
631  *
632  * \param sorcery Pointer to a sorcery structure
633  */
634 void ast_sorcery_load(const struct ast_sorcery *sorcery);
635
636 /*!
637  * \brief Inform any wizards of a specific object type to load persistent objects
638  *
639  * \param sorcery Pointer to a sorcery structure
640  * \param type Name of the object type to load
641  */
642 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
643
644 /*!
645  * \brief Inform any wizards to reload persistent objects
646  *
647  * \param sorcery Pointer to a sorcery structure
648  */
649 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
650
651 /*!
652  * \brief Inform any wizards of a specific object type to reload persistent objects
653  *
654  * \param sorcery Pointer to a sorcery structure
655  * \param type Name of the object type to reload
656  */
657 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
658
659 /*!
660  * \brief Increase the reference count of a sorcery structure
661  *
662  * \param sorcery Pointer to a sorcery structure
663  */
664 void ast_sorcery_ref(struct ast_sorcery *sorcery);
665
666
667 /*!
668  * \brief Create an object set (KVP list) for an object
669  *
670  * \param sorcery Pointer to a sorcery structure
671  * \param object Pointer to a sorcery object
672  * \param flags Flags indicating which handler to use and in what order.
673  *
674  * \retval non-NULL success
675  * \retval NULL if error occurred
676  *
677  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
678  */
679 struct ast_variable *ast_sorcery_objectset_create2(const struct ast_sorcery *sorcery,
680         const void *object, enum ast_sorcery_field_handler_flags flags);
681
682 /*!
683  * \brief Create an object set (KVP list) for an object
684  *
685  * \param sorcery Pointer to a sorcery structure
686  * \param object Pointer to a sorcery object
687  *
688  * \retval non-NULL success
689  * \retval NULL if error occurred
690  *
691  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
692  *
693  * \note This function attempts to use a field's sorcery_fields_handler first and if that
694  * doesn't exist or fails, a field's sorcery_field_handler is used.  The difference is
695  * that the former may return multiple list entries for the same field and the latter will only
696  * return 1.  It's up to the field itself to determine what the appropriate content is.
697  */
698 #define ast_sorcery_objectset_create(sorcery, object) \
699         ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
700
701 /*!
702  * \brief Create an object set in JSON format for an object
703  *
704  * \param sorcery Pointer to a sorcery structure
705  * \param object Pointer to a sorcery object
706  *
707  * \retval non-NULL success
708  * \retval NULL if error occurred
709  *
710  * \note The returned ast_json object must be unreferenced using ast_json_unref
711  */
712 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
713
714 /*!
715  * \brief Apply an object set (KVP list) to an object
716  *
717  * \param sorcery Pointer to a sorcery structure
718  * \param object Pointer to a sorcery object
719  * \param objectset Object set itself
720  *
721  * \retval 0 success
722  * \retval -1 failure
723  *
724  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
725  *       applied object set.
726  */
727 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
728
729 /*!
730  * \brief Create a changeset given two object sets
731  *
732  * \param original Original object set
733  * \param modified Modified object set
734  * \param changes Pointer to hold any changes between the object sets
735  *
736  * \retval 0 success
737  * \retval -1 failure
738  *
739  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
740  */
741 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
742
743 /*!
744  * \brief Allocate a generic sorcery capable object
745  *
746  * \param size Size of the object
747  * \param destructor Optional destructor function
748  *
749  * \retval non-NULL success
750  * \retval NULL failure
751  */
752 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
753
754 /*!
755  * \brief Allocate an object
756  *
757  * \param sorcery Pointer to a sorcery structure
758  * \param type Type of object to allocate
759  * \param id Optional unique identifier, if none is provided one will be generated
760  *
761  * \retval non-NULL success
762  * \retval NULL failure
763  */
764 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
765
766 /*!
767  * \brief Create a copy of an object
768  *
769  * \param sorcery Pointer to a sorcery structure
770  * \param object Existing object
771  *
772  * \retval non-NULL success
773  * \retval NULL failure
774  */
775 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
776
777 /*!
778  * \brief Create a changeset of two objects
779  *
780  * \param sorcery Pointer to a sorcery structure
781  * \param original Original object
782  * \param modified Modified object
783  * \param changes Pointer which will be populated with changes if any exist
784  *
785  * \retval 0 success
786  * \retval -1 failure
787  *
788  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
789  *
790  * \note While the objects must be of the same type they do not have to be the same object
791  */
792 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
793
794 /*!
795  * \brief Add an observer to a specific object type
796  *
797  * \param sorcery Pointer to a sorcery structure
798  * \param type Type of object that should be observed
799  * \param callbacks Implementation of the observer interface
800  *
801  * \retval 0 success
802  * \retval -1 failure
803  *
804  * \note You must be ready to accept observer invocations before this function is called
805  */
806 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
807
808 /*!
809  * \brief Remove an observer from a specific object type
810  *
811  * \param sorcery Pointer to a sorcery structure
812  * \param type Type of object that should no longer be observed
813  * \param callbacks Implementation of the observer interface
814  *
815  * \retval 0 success
816  * \retval -1 failure
817  */
818 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
819
820 /*!
821  * \brief Create and potentially persist an object using an available wizard
822  *
823  * \param sorcery Pointer to a sorcery structure
824  * \param object Pointer to a sorcery object
825  *
826  * \retval 0 success
827  * \retval -1 failure
828  */
829 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
830
831 /*!
832  * \brief Retrieve an object using its unique identifier
833  *
834  * \param sorcery Pointer to a sorcery structure
835  * \param type Type of object to retrieve
836  * \param id Unique object identifier
837  *
838  * \retval non-NULL if found
839  * \retval NULL if not found
840  */
841 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
842
843 /*!
844  * \brief Retrieve an object or multiple objects using specific fields
845  *
846  * \param sorcery Pointer to a sorcery structure
847  * \param type Type of object to retrieve
848  * \param flags Flags to control behavior
849  * \param fields Optional object fields and values to match against
850  *
851  * \retval non-NULL if found
852  * \retval NULL if not found
853  *
854  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
855  *       ao2_container that must be unreferenced after use.
856  *
857  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
858  *       of the given type.
859  */
860 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
861
862 /*!
863  * \brief Retrieve multiple objects using a regular expression on their id
864  *
865  * \param sorcery Pointer to a sorcery structure
866  * \param type Type of object to retrieve
867  * \param regex Regular expression
868  *
869  * \retval non-NULL if error occurs
870  * \retval NULL success
871  *
872  * \note The provided regex is treated as extended case sensitive.
873  */
874 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
875
876 /*!
877  * \brief Update an object
878  *
879  * \param sorcery Pointer to a sorcery structure
880  * \param object Pointer to a sorcery object
881  *
882  * \retval 0 success
883  * \retval -1 failure
884  */
885 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
886
887 /*!
888  * \brief Delete an object
889  *
890  * \param sorcery Pointer to a sorcery structure
891  * \param object Pointer to a sorcery object
892  *
893  * \retval 0 success
894  * \retval -1 failure
895  */
896 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
897
898 /*!
899  * \brief Decrease the reference count of a sorcery structure
900  *
901  * \param sorcery Pointer to a sorcery structure
902  */
903 void ast_sorcery_unref(struct ast_sorcery *sorcery);
904
905 /*!
906  * \brief Get the unique identifier of a sorcery object
907  *
908  * \param object Pointer to a sorcery object
909  *
910  * \retval unique identifier
911  */
912 const char *ast_sorcery_object_get_id(const void *object);
913
914 /*!
915  * \brief Get the type of a sorcery object
916  *
917  * \param object Pointer to a sorcery object
918  *
919  * \retval type of object
920  */
921 const char *ast_sorcery_object_get_type(const void *object);
922
923 /*!
924  * \brief Get an extended field value from a sorcery object
925  *
926  * \param object Pointer to a sorcery object
927  * \param name Name of the extended field value
928  *
929  * \retval non-NULL if found
930  * \retval NULL if not found
931  *
932  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
933  */
934 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
935
936 /*!
937  * \brief Set an extended field value on a sorcery object
938  *
939  * \param object Pointer to a sorcery object
940  * \param name Name of the extended field
941  * \param value Value of the extended field
942  *
943  * \retval 0 success
944  * \retval -1 failure
945  *
946  * \note The field name MUST begin with '@' to indicate it is an extended field.
947  * \note If the extended field already exists it will be overwritten with the new value.
948  */
949 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
950
951 /*!
952  * \brief ao2 object comparator based on sorcery id.
953  */
954 int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
955
956 /*!
957  * \brief ao2 object sorter based on sorcery id.
958  */
959 int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
960
961 /*!
962  * \brief ao2 object hasher based on sorcery id.
963  */
964 int ast_sorcery_object_id_hash(const void *obj, int flags);
965
966 /*!
967  * \brief Get the sorcery object type given a type name.
968  *
969  * \param sorcery The sorcery from which to retrieve the object type
970  * \param type The type name
971  */
972 struct ast_sorcery_object_type *ast_sorcery_get_object_type(const struct ast_sorcery *sorcery,
973                 const char *type);
974
975 /*!
976  * \brief Determine if a particular object field has been registered with sorcery
977  *
978  * \param object_type The object type to check against
979  * \param field_name The name of the field to check
980  *
981  * \retval 0 The field is not registered for this sorcery type
982  * \retval 1 The field is registered for this sorcery type
983  */
984 int ast_sorcery_is_object_field_registered(const struct ast_sorcery_object_type *object_type,
985                 const char *field_name);
986
987 #if defined(__cplusplus) || defined(c_plusplus)
988 }
989 #endif
990
991 #endif /* _ASTERISK_SORCERY_H */