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