sorcery: Create sorcery instance registry.
[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. If the storage of the object types are such that a default wizard can be used this can
43  * be applied using the \ref ast_sorcery_apply_default API call. Note that the default mappings will not
44  * override configured mappings. They are only used in the case where no configured mapping exists.
45  *
46  * Configuring object mappings implicitly creates a basic version of an object type. The object type
47  * must be fully registered, however, using the \ref ast_sorcery_object_register API call before any
48  * objects of the type can be allocated, created, or retrieved.
49  *
50  * Once the object type itself has been fully registered the individual fields within the object must
51  * be registered using the \ref ast_sorcery_object_field_register API call. Note that not all fields *need*
52  * be registered. Only fields that should be accessible using the sorcery API have to be registered.
53  *
54  * \par Creating Objects
55  *
56  * Before an object can be created within the sorcery API it must first be allocated using the
57  * \ref ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific
58  * details, and applies default values to the object. A unique identifier can optionally be specified
59  * when allocating an object. If it is not provided one will be automatically generated. Allocating
60  * an object does not create it within any object storage mechanisms that are configured for the
61  * object type. Creation must explicitly be done using the \ref ast_sorcery_create API call. This API call
62  * passes the object to each configured object storage mechanism for the object type until one
63  * successfully persists the object.
64  *
65  * \par Retrieving Objects
66  *
67  * To retrieve a single object using its unique identifier the \ref ast_sorcery_retrieve_by_id API call
68  * can be used.
69  *
70  * To retrieve potentially multiple objects using specific fields the \ref ast_sorcery_retrieve_by_fields
71  * API call can be used. The behavior of this API call is controlled using different flags. If the
72  * AST_RETRIEVE_FLAG_MULTIPLE flag is used a container will be returned which contains all matching objects.
73  * To retrieve all objects the AST_RETRIEVE_FLAG_ALL flag can be specified. Note that when specifying this flag
74  * you do not need to pass any fields.
75  *
76  * Both API calls return shared objects. Modification of the object can not occur until it has been copied.
77  *
78  * \par Updating Objects
79  *
80  * As retrieved objects may be shared the first step to updating the object with new details is creating a
81  * copy using the \ref ast_sorcery_copy API call. This will return a new object which is specific to the caller.
82  * Any field within the object may be modified as needed. Once changes are done the changes can be committed
83  * using the \ref ast_sorcery_update API call. Note that as the copied object is specific to the caller it must
84  * be unreferenced after use.
85  *
86  * \par Deleting Objects
87  *
88  * To delete an object simply call the \ref ast_sorcery_delete API call with an object retrieved using the
89  * ast_sorcery_retrieve_by_* API calls or a copy returned from \ref ast_sorcery_copy.
90  */
91
92 #ifndef _ASTERISK_SORCERY_H
93 #define _ASTERISK_SORCERY_H
94
95 #if defined(__cplusplus) || defined(c_plusplus)
96 extern "C" {
97 #endif
98
99 #include "asterisk/config_options.h"
100 #include "asterisk/uuid.h"
101
102 /*! \brief Maximum size of an object type */
103 #define MAX_OBJECT_TYPE 64
104
105 /*! \brief Maximum length of an object field name */
106 #define MAX_OBJECT_FIELD 128
107
108 /*!
109  * \brief Retrieval flags
110  */
111 enum ast_sorcery_retrieve_flags {
112         /*! \brief Default retrieval flags */
113         AST_RETRIEVE_FLAG_DEFAULT = 0,
114
115         /*! \brief Return all matching objects */
116         AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
117
118         /*! \brief Perform no matching, return all objects */
119         AST_RETRIEVE_FLAG_ALL = (1 << 1),
120 };
121
122 /*! \brief Forward declaration for the sorcery main structure */
123 struct ast_sorcery;
124
125 /*!
126  * \brief A callback function for translating a value into a string
127  *
128  * \param obj Object to get value from
129  * \param args Where the field is
130  * \param buf Pointer to the buffer that the handler has created which contains the field value
131  *
132  * \retval 0 success
133  * \retval -1 failure
134  */
135 typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
136
137 /*!
138  * \brief A callback function for translating multiple values into an ast_variable list
139  *
140  * \param obj Object to get values from
141  * \param fields Pointer to store the list of fields
142  *
143  * \retval 0 success
144  * \retval -1 failure
145  */
146 typedef int (*sorcery_fields_handler)(const void *obj, struct ast_variable **fields);
147
148 /*!
149  * \brief A callback function for performing a transformation on an object set
150  *
151  * \param set The existing object set
152  *
153  * \retval non-NULL new object set if changed
154  * \retval NULL if no changes present
155  *
156  * \note The returned ast_variable list must be *new*. You can not return the input set.
157  */
158 typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
159
160 /*!
161  * \brief A callback function for when an object set is successfully applied to an object
162  *
163  * \note On a failure return, the state of the object is left undefined. It is a bad
164  * idea to try to use this object.
165  *
166  * \param sorcery Sorcery structure in use
167  * \param obj The object itself
168  * \retval 0 Success
169  * \retval non-zero Failure
170  */
171 typedef int (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
172
173 /*!
174  * \brief A callback function for copying the contents of one object to another
175  *
176  * \param src The source object
177  * \param dst The destination object
178  *
179  * \retval 0 success
180  * \retval -1 failure
181  */
182 typedef int (*sorcery_copy_handler)(const void *src, void *dst);
183
184 /*!
185  * \brief A callback function for generating a changeset between two objects
186  *
187  * \param original The original object
188  * \param modified The modified object
189  * \param changes The changeset
190  *
191  * \param 0 success
192  * \param -1 failure
193  */
194 typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
195
196 /*! \brief Interface for a sorcery wizard */
197 struct ast_sorcery_wizard {
198         /*! \brief Name of the wizard */
199         const char *name;
200
201         /*! \brief Pointer to the Asterisk module this wizard is implemented by */
202         struct ast_module *module;
203
204         /*! \brief Callback for opening a wizard */
205         void *(*open)(const char *data);
206
207         /*! \brief Optional callback for loading persistent objects */
208         void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
209
210         /*! \brief Optional callback for reloading persistent objects */
211         void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
212
213         /*! \brief Callback for creating an object */
214         int (*create)(const struct ast_sorcery *sorcery, void *data, void *object);
215
216         /*! \brief Callback for retrieving an object using an id */
217         void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
218
219         /*! \brief Callback for retrieving multiple objects using a regex on their id */
220         void (*retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
221
222         /*! \brief Optional callback for retrieving an object using fields */
223         void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
224
225         /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
226         void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
227
228         /*! \brief Callback for updating an object */
229         int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
230
231         /*! \brief Callback for deleting an object */
232         int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
233
234         /*! \brief Callback for closing a wizard */
235         void (*close)(void *data);
236 };
237
238 /*! \brief Interface for a sorcery object type observer */
239 struct ast_sorcery_observer {
240         /*! \brief Callback for when an object is created */
241         void (*created)(const void *object);
242
243         /*! \brief Callback for when an object is updated */
244         void (*updated)(const void *object);
245
246         /*! \brief Callback for when an object is deleted */
247         void (*deleted)(const void *object);
248
249         /*! \brief Callback for when an object type is loaded/reloaded */
250         void (*loaded)(const char *object_type);
251 };
252
253 /*! \brief Opaque structure for internal sorcery object */
254 struct ast_sorcery_object;
255
256 /*! \brief Structure which contains details about a sorcery object */
257 struct ast_sorcery_object_details {
258         /*! \brief Pointer to internal sorcery object information */
259         struct ast_sorcery_object *object;
260 };
261
262 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
263 #define SORCERY_OBJECT(details)                    \
264 struct {                                           \
265         struct ast_sorcery_object_details details; \
266 }                                                  \
267
268 /*!
269  * \brief Initialize the sorcery API
270  *
271  * \retval 0 success
272  * \retval -1 failure
273  */
274 int ast_sorcery_init(void);
275
276 /*!
277  * \brief Register a sorcery wizard
278  *
279  * \param interface Pointer to a wizard interface
280  * \param module Pointer to the module implementing the interface
281  *
282  * \retval 0 success
283  * \retval -1 failure
284  */
285 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
286
287 /*!
288  * \brief See \ref __ast_sorcery_wizard_register()
289  */
290 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, ast_module_info ? ast_module_info->self : NULL)
291
292 /*!
293  * \brief Unregister a sorcery wizard
294  *
295  * \param interface Pointer to the wizard interface
296  *
297  * \retval 0 success
298  * \retval -1 failure
299  */
300 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
301
302 /*!
303  * \brief Open a new sorcery structure
304  *
305  * \param module The module name (AST_MODULE)
306  *
307  * \retval non-NULL success
308  * \retval NULL if allocation failed
309  */
310 struct ast_sorcery *__ast_sorcery_open(const char *module);
311
312 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE)
313
314 /*!
315  * \brief Retrieves an existing sorcery instance by module name
316  *
317  * \param module The module name
318  *
319  * \retval non-NULL success
320  * \retval NULL if no instance was found
321  *
322  * \note The returned instance has its reference count incremented.  The caller
323  * must decrement the count when they're finished with it.
324  *
325  */
326 struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
327
328 /*!
329  * \brief Apply configured wizard mappings
330  *
331  * \param sorcery Pointer to a sorcery structure
332  * \param name Name of the category to use within the configuration file, normally the module name
333  * \param module The module name (AST_MODULE)
334  *
335  * \retval 0 success
336  * \retval -1 failure
337  */
338 int __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module);
339
340 #define ast_sorcery_apply_config(sorcery, name) \
341         __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
342
343 /*!
344  * \brief Apply default object wizard mappings
345  *
346  * \param sorcery Pointer to a sorcery structure
347  * \param type Type of object to apply to
348  * \param module The name of the module, typically AST_MODULE
349  * \param name Name of the wizard to use
350  * \param data Data to be passed to wizard
351  *
352  * \retval 0 success
353  * \retval -1 failure
354  *
355  * \note This should be called *after* applying configuration sourced mappings
356  *
357  * \note Only a single default can exist per object type
358  */
359 int __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data);
360
361 #define ast_sorcery_apply_default(sorcery, type, name, data) \
362         __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
363
364 /*!
365  * \brief Register an object type
366  *
367  * \param sorcery Pointer to a sorcery structure
368  * \param type Type of object
369  * \param hidden All objects of this type are internal and should not be manipulated by users
370  * \param reloadable All objects of this type are reloadable
371  * \param alloc Required object allocation callback
372  * \param transform Optional transformation callback
373  * \param apply Optional object set apply callback
374  *
375  * \note In general, this function should not be used directly. One of the various
376  * macro'd versions should be used instead.
377  *
378  * \retval 0 success
379  * \retval -1 failure
380  */
381 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);
382
383 /*!
384  * \brief Register an object type
385  *
386  * \param sorcery Pointer to a sorcery structure
387  * \param type Type of object
388  * \param alloc Required object allocation callback
389  * \param transform Optional transformation callback
390  * \param apply Optional object set apply callback
391  *
392  * \retval 0 success
393  * \retval -1 failure
394  */
395 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
396         __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
397
398 /*!
399  * \brief Register an object type that is not reloadable
400  *
401  * \param sorcery Pointer to a sorcery structure
402  * \param type Type of object
403  * \param alloc Required object allocation callback
404  * \param transform Optional transformation callback
405  * \param apply Optional object set apply callback
406  *
407  * \retval 0 success
408  * \retval -1 failure
409  */
410 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
411         __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
412
413 /*!
414  * \brief Register an internal, hidden object type
415  *
416  * \param sorcery Pointer to a sorcery structure
417  * \param type Type of object
418  * \param alloc Required object allocation callback
419  * \param transform Optional transformation callback
420  * \param apply Optional object set apply callback
421  *
422  * \retval 0 success
423  * \retval -1 failure
424  */
425 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
426         __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
427
428 /*!
429  * \brief Set the copy handler for an object type
430  *
431  * \param sorcery Pointer to a sorcery structure
432  * \param type Type of object
433  * \param copy Copy handler
434  */
435 void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
436
437 /*!
438  * \brief Set the diff handler for an object type
439  *
440  * \param sorcery Pointer to a sorcery structure
441  * \param type Type of object
442  * \param diff Diff handler
443  */
444 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
445
446 /*!
447  * \brief Register a regex for multiple fields within an object
448  *
449  * \param sorcery Pointer to a sorcery structure
450  * \param type Type of object
451  * \param regex A regular expression pattern for the fields
452  * \param config_handler A custom handler for translating the string representation of the fields
453  * \param sorcery_handler A custom handler for translating the native representation of the fields
454  *
455  * \retval 0 success
456  * \retval -1 failure
457  */
458 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
459                                                                            sorcery_fields_handler sorcery_handler);
460
461 /*!
462  * \brief Register a field within an object
463  *
464  * \param sorcery Pointer to a sorcery structure
465  * \param type Type of object
466  * \param name Name of the field
467  * \param default_val Default value of the field
468  * \param opt_type Option type
469  * \param flags Option type specific flags
470  *
471  * \retval 0 success
472  * \retval -1 failure
473  */
474 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,
475                                         aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, unsigned int no_doc,
476                                         size_t argc, ...);
477
478 /*!
479  * \brief Register a field within an object
480  *
481  * \param sorcery Pointer to a sorcery structure
482  * \param type Type of object
483  * \param name Name of the field
484  * \param default_val Default value of the field
485  * \param opt_type Option type
486  * \param flags Option type specific flags
487  *
488  * \retval 0 success
489  * \retval -1 failure
490  */
491 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
492     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
493
494 /*!
495  * \brief Register a field within an object without documentation
496  *
497  * \param sorcery Pointer to a sorcery structure
498  * \param type Type of object
499  * \param name Name of the field
500  * \param default_val Default value of the field
501  * \param opt_type Option type
502  * \param flags Option type specific flags
503  *
504  * \retval 0 success
505  * \retval -1 failure
506  */
507 #define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
508     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
509
510 /*!
511  * \brief Register a field within an object with custom handlers
512  *
513  * \param sorcery Pointer to a sorcery structure
514  * \param type Type of object
515  * \param name Name of the field
516  * \param default_val Default value of the field
517  * \param config_handler Custom configuration handler
518  * \param sorcery_handler Custom sorcery handler
519  * \param flags Option type specific flags
520  *
521  * \retval 0 success
522  * \retval -1 failure
523  */
524 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, flags, ...) \
525     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
526
527 /*!
528  * \brief Register a field within an object with custom handlers without documentation
529  *
530  * \param sorcery Pointer to a sorcery structure
531  * \param type Type of object
532  * \param name Name of the field
533  * \param default_val Default value of the field
534  * \param config_handler Custom configuration handler
535  * \param sorcery_handler Custom sorcery handler
536  * \param flags Option type specific flags
537  *
538  * \retval 0 success
539  * \retval -1 failure
540  */
541 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, flags, ...) \
542     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, flags, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
543
544 /*!
545  * \brief Inform any wizards to load persistent objects
546  *
547  * \param sorcery Pointer to a sorcery structure
548  */
549 void ast_sorcery_load(const struct ast_sorcery *sorcery);
550
551 /*!
552  * \brief Inform any wizards of a specific object type to load persistent objects
553  *
554  * \param sorcery Pointer to a sorcery structure
555  * \param type Name of the object type to load
556  */
557 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
558
559 /*!
560  * \brief Inform any wizards to reload persistent objects
561  *
562  * \param sorcery Pointer to a sorcery structure
563  */
564 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
565
566 /*!
567  * \brief Inform any wizards of a specific object type to reload persistent objects
568  *
569  * \param sorcery Pointer to a sorcery structure
570  * \param type Name of the object type to reload
571  */
572 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
573
574 /*!
575  * \brief Increase the reference count of a sorcery structure
576  *
577  * \param sorcery Pointer to a sorcery structure
578  */
579 void ast_sorcery_ref(struct ast_sorcery *sorcery);
580
581 /*!
582  * \brief Create an object set (KVP list) for an object
583  *
584  * \param sorcery Pointer to a sorcery structure
585  * \param object Pointer to a sorcery object
586  *
587  * \retval non-NULL success
588  * \retval NULL if error occurred
589  *
590  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
591  */
592 struct ast_variable *ast_sorcery_objectset_create(const struct ast_sorcery *sorcery, const void *object);
593
594 /*!
595  * \brief Create an object set in JSON format for an object
596  *
597  * \param sorcery Pointer to a sorcery structure
598  * \param object Pointer to a sorcery object
599  *
600  * \retval non-NULL success
601  * \retval NULL if error occurred
602  *
603  * \note The returned ast_json object must be unreferenced using ast_json_unref
604  */
605 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
606
607 /*!
608  * \brief Apply an object set (KVP list) to an object
609  *
610  * \param sorcery Pointer to a sorcery structure
611  * \param object Pointer to a sorcery object
612  * \param objectset Object set itself
613  *
614  * \retval 0 success
615  * \retval -1 failure
616  *
617  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
618  *       applied object set.
619  */
620 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
621
622 /*!
623  * \brief Create a changeset given two object sets
624  *
625  * \param original Original object set
626  * \param modified Modified object set
627  * \param changes Pointer to hold any changes between the object sets
628  *
629  * \retval 0 success
630  * \retval -1 failure
631  *
632  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
633  */
634 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
635
636 /*!
637  * \brief Allocate a generic sorcery capable object
638  *
639  * \param size Size of the object
640  * \param destructor Optional destructor function
641  *
642  * \retval non-NULL success
643  * \retval NULL failure
644  */
645 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
646
647 /*!
648  * \brief Allocate an object
649  *
650  * \param sorcery Pointer to a sorcery structure
651  * \param type Type of object to allocate
652  * \param id Optional unique identifier, if none is provided one will be generated
653  *
654  * \retval non-NULL success
655  * \retval NULL failure
656  */
657 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
658
659 /*!
660  * \brief Create a copy of an object
661  *
662  * \param sorcery Pointer to a sorcery structure
663  * \param object Existing object
664  *
665  * \retval non-NULL success
666  * \retval NULL failure
667  */
668 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
669
670 /*!
671  * \brief Create a changeset of two objects
672  *
673  * \param sorcery Pointer to a sorcery structure
674  * \param original Original object
675  * \param modified Modified object
676  * \param changes Pointer which will be populated with changes if any exist
677  *
678  * \retval 0 success
679  * \retval -1 failure
680  *
681  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
682  *
683  * \note While the objects must be of the same type they do not have to be the same object
684  */
685 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
686
687 /*!
688  * \brief Add an observer to a specific object type
689  *
690  * \param sorcery Pointer to a sorcery structure
691  * \param type Type of object that should be observed
692  * \param callbacks Implementation of the observer interface
693  *
694  * \retval 0 success
695  * \retval -1 failure
696  *
697  * \note You must be ready to accept observer invocations before this function is called
698  */
699 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
700
701 /*!
702  * \brief Remove an observer from a specific object type
703  *
704  * \param sorcery Pointer to a sorcery structure
705  * \param type Type of object that should no longer be observed
706  * \param callbacks Implementation of the observer interface
707  *
708  * \retval 0 success
709  * \retval -1 failure
710  */
711 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
712
713 /*!
714  * \brief Create and potentially persist an object using an available wizard
715  *
716  * \param sorcery Pointer to a sorcery structure
717  * \param object Pointer to a sorcery object
718  *
719  * \retval 0 success
720  * \retval -1 failure
721  */
722 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
723
724 /*!
725  * \brief Retrieve an object using its unique identifier
726  *
727  * \param sorcery Pointer to a sorcery structure
728  * \param type Type of object to retrieve
729  * \param id Unique object identifier
730  *
731  * \retval non-NULL if found
732  * \retval NULL if not found
733  */
734 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
735
736 /*!
737  * \brief Retrieve an object or multiple objects using specific fields
738  *
739  * \param sorcery Pointer to a sorcery structure
740  * \param type Type of object to retrieve
741  * \param flags Flags to control behavior
742  * \param fields Optional object fields and values to match against
743  *
744  * \retval non-NULL if found
745  * \retval NULL if not found
746  *
747  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
748  *       ao2_container that must be unreferenced after use.
749  *
750  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
751  *       of the given type.
752  */
753 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
754
755 /*!
756  * \brief Retrieve multiple objects using a regular expression on their id
757  *
758  * \param sorcery Pointer to a sorcery structure
759  * \param type Type of object to retrieve
760  * \param regex Regular expression
761  *
762  * \retval non-NULL if error occurs
763  * \retval NULL success
764  *
765  * \note The provided regex is treated as extended case sensitive.
766  */
767 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
768
769 /*!
770  * \brief Update an object
771  *
772  * \param sorcery Pointer to a sorcery structure
773  * \param object Pointer to a sorcery object
774  *
775  * \retval 0 success
776  * \retval -1 failure
777  */
778 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
779
780 /*!
781  * \brief Delete an object
782  *
783  * \param sorcery Pointer to a sorcery structure
784  * \param object Pointer to a sorcery object
785  *
786  * \retval 0 success
787  * \retval -1 failure
788  */
789 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
790
791 /*!
792  * \brief Decrease the reference count of a sorcery structure
793  *
794  * \param sorcery Pointer to a sorcery structure
795  */
796 void ast_sorcery_unref(struct ast_sorcery *sorcery);
797
798 /*!
799  * \brief Get the unique identifier of a sorcery object
800  *
801  * \param object Pointer to a sorcery object
802  *
803  * \retval unique identifier
804  */
805 const char *ast_sorcery_object_get_id(const void *object);
806
807 /*!
808  * \brief Get the type of a sorcery object
809  *
810  * \param object Pointer to a sorcery object
811  *
812  * \retval type of object
813  */
814 const char *ast_sorcery_object_get_type(const void *object);
815
816 /*!
817  * \brief Get an extended field value from a sorcery object
818  *
819  * \param object Pointer to a sorcery object
820  * \param name Name of the extended field value
821  *
822  * \retval non-NULL if found
823  * \retval NULL if not found
824  *
825  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
826  */
827 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
828
829 /*!
830  * \brief Set an extended field value on a sorcery object
831  *
832  * \param object Pointer to a sorcery object
833  * \param name Name of the extended field
834  * \param value Value of the extended field
835  *
836  * \retval 0 success
837  * \retval -1 failure
838  *
839  * \note The field name MUST begin with '@' to indicate it is an extended field.
840  * \note If the extended field already exists it will be overwritten with the new value.
841  */
842 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
843
844 /*!
845  * \brief Sorcery object comparator based on id.
846  */
847 int ast_sorcery_object_id_compare(const void *obj_left, const void *obj_right, int flags);
848
849
850 #if defined(__cplusplus) || defined(c_plusplus)
851 }
852 #endif
853
854 #endif /* _ASTERISK_SORCERY_H */