af43393c5d752e8e05312ec9d6e43b54a2372510
[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_type_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 /*!
106  * \brief Retrieval flags
107  */
108 enum ast_sorcery_retrieve_flags {
109         /*! \brief Default retrieval flags */
110         AST_RETRIEVE_FLAG_DEFAULT = 0,
111
112         /*! \brief Return all matching objects */
113         AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
114
115         /*! \brief Perform no matching, return all objects */
116         AST_RETRIEVE_FLAG_ALL = (1 << 1),
117 };
118
119 /*! \brief Forward declaration for the sorcery main structure */
120 struct ast_sorcery;
121
122 /*!
123  * \brief A callback function for translating a value into a string
124  *
125  * \param obj Object to get value from
126  * \param args Where the field is
127  * \param buf Pointer to the buffer that the handler has created which contains the field value
128  *
129  * \retval 0 success
130  * \retval -1 failure
131  */
132 typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
133
134 /*!
135  * \brief A callback function for translating multiple values into an ast_variable list
136  *
137  * \param obj Object to get values from
138  * \param fields Pointer to store the list of fields
139  *
140  * \retval 0 success
141  * \retval -1 failure
142  */
143 typedef int (*sorcery_fields_handler)(const void *obj, struct ast_variable **fields);
144
145 /*!
146  * \brief A callback function for performing a transformation on an object set
147  *
148  * \param set The existing object set
149  *
150  * \retval non-NULL new object set if changed
151  * \retval NULL if no changes present
152  *
153  * \note The returned ast_variable list must be *new*. You can not return the input set.
154  */
155 typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
156
157 /*!
158  * \brief A callback function for when an object set is successfully applied to an object
159  *
160  * \param sorcery Sorcery structure in use
161  * \param obj The object itself
162  */
163 typedef void (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
164
165 /*!
166  * \brief A callback function for copying the contents of one object to another
167  *
168  * \param src The source object
169  * \param dst The destination object
170  *
171  * \retval 0 success
172  * \retval -1 failure
173  */
174 typedef int (*sorcery_copy_handler)(const void *src, void *dst);
175
176 /*!
177  * \brief A callback function for generating a changeset between two objects
178  *
179  * \param original The original object
180  * \param modified The modified object
181  * \param changes The changeset
182  *
183  * \param 0 success
184  * \param -1 failure
185  */
186 typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
187
188 /*! \brief Interface for a sorcery wizard */
189 struct ast_sorcery_wizard {
190         /*! \brief Name of the wizard */
191         const char *name;
192
193         /*! \brief Pointer to the Asterisk module this wizard is implemented by */
194         struct ast_module *module;
195
196         /*! \brief Callback for opening a wizard */
197         void *(*open)(const char *data);
198
199         /*! \brief Optional callback for loading persistent objects */
200         void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
201
202         /*! \brief Optional callback for reloading persistent objects */
203         void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
204
205         /*! \brief Callback for creating an object */
206         int (*create)(const struct ast_sorcery *sorcery, void *data, void *object);
207
208         /*! \brief Callback for retrieving an object using an id */
209         void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
210
211         /*! \brief Callback for retrieving multiple objects using a regex on their id */
212         void (*retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
213
214         /*! \brief Optional callback for retrieving an object using fields */
215         void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
216
217         /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
218         void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
219
220         /*! \brief Callback for updating an object */
221         int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
222
223         /*! \brief Callback for deleting an object */
224         int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
225
226         /*! \brief Callback for closing a wizard */
227         void (*close)(void *data);
228 };
229
230 /*! \brief Structure which contains details about a sorcery object */
231 struct ast_sorcery_object_details {
232         /*! \brief Unique identifier of this object */
233         char id[AST_UUID_STR_LEN];
234
235         /*! \brief Type of object */
236         char type[MAX_OBJECT_TYPE];
237 };
238
239 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
240 #define SORCERY_OBJECT(details)                    \
241 struct {                                           \
242         struct ast_sorcery_object_details details; \
243 }                                                  \
244
245 /*!
246  * \brief Initialize the sorcery API
247  *
248  * \retval 0 success
249  * \retval -1 failure
250  */
251 int ast_sorcery_init(void);
252
253 /*!
254  * \brief Register a sorcery wizard
255  *
256  * \param interface Pointer to a wizard interface
257  * \param module Pointer to the module implementing the interface
258  *
259  * \retval 0 success
260  * \retval -1 failure
261  */
262 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
263
264 /*!
265  * \brief See \ref __ast_sorcery_wizard_register()
266  */
267 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, ast_module_info ? ast_module_info->self : NULL)
268
269 /*!
270  * \brief Unregister a sorcery wizard
271  *
272  * \param interface Pointer to the wizard interface
273  *
274  * \retval 0 success
275  * \retval -1 failure
276  */
277 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
278
279 /*!
280  * \brief Open a new sorcery structure
281  *
282  * \retval non-NULL success
283  * \retval NULL if allocation failed
284  */
285 struct ast_sorcery *ast_sorcery_open(void);
286
287 /*!
288  * \brief Apply configured wizard mappings
289  *
290  * \param sorcery Pointer to a sorcery structure
291  * \param name Name of the category to use within the configuration file, normally the module name
292  * \param module The module name (AST_MODULE)
293  *
294  * \retval 0 success
295  * \retval -1 failure
296  */
297 int __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module);
298
299 #define ast_sorcery_apply_config(sorcery, name) \
300         __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
301
302 /*!
303  * \brief Apply default object wizard mappings
304  *
305  * \param sorcery Pointer to a sorcery structure
306  * \param type Type of object to apply to
307  * \param module The name of the module, typically AST_MODULE
308  * \param name Name of the wizard to use
309  * \param data Data to be passed to wizard
310  *
311  * \retval 0 success
312  * \retval -1 failure
313  *
314  * \note This should be called *after* applying configuration sourced mappings
315  *
316  * \note Only a single default can exist per object type
317  */
318 int __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data);
319
320 #define ast_sorcery_apply_default(sorcery, type, name, data) \
321         __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
322
323 /*!
324  * \brief Register an object type
325  *
326  * \param sorcery Pointer to a sorcery structure
327  * \param type Type of object
328  * \param alloc Required object allocation callback
329  * \param transform Optional transformation callback
330  * \param apply Optional object set apply callback
331  *
332  * \retval 0 success
333  * \retval -1 failure
334  */
335 int ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply);
336
337 /*!
338  * \brief Set the copy handler for an object type
339  *
340  * \param sorcery Pointer to a sorcery structure
341  * \param type Type of object
342  * \param copy Copy handler
343  */
344 void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
345
346 /*!
347  * \brief Set the diff handler for an object type
348  *
349  * \param sorcery Pointer to a sorcery structure
350  * \param type Type of object
351  * \param diff Diff handler
352  */
353 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
354
355 /*!
356  * \brief Register a regex for multiple fields within an object
357  *
358  * \param sorcery Pointer to a sorcery structure
359  * \param type Type of object
360  * \param regex A regular expression pattern for the fields
361  * \param config_handler A custom handler for translating the string representation of the fields
362  * \param sorcery_handler A custom handler for translating the native representation of the fields
363  *
364  * \retval 0 success
365  * \retval -1 failure
366  */
367 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
368                                                                            sorcery_fields_handler sorcery_handler);
369
370 /*!
371  * \brief Register a field within an object
372  *
373  * \param sorcery Pointer to a sorcery structure
374  * \param type Type of object
375  * \param name Name of the field
376  * \param default_val Default value of the field
377  * \param opt_type Option type
378  * \param flags Option type specific flags
379  *
380  * \retval 0 success
381  * \retval -1 failure
382  */
383 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,
384                                         aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, size_t argc, ...);
385
386 /*!
387  * \brief Register a field within an object
388  *
389  * \param sorcery Pointer to a sorcery structure
390  * \param type Type of object
391  * \param name Name of the field
392  * \param default_val Default value of the field
393  * \param opt_type Option type
394  * \param flags Option type specific flags
395  *
396  * \retval 0 success
397  * \retval -1 failure
398  */
399 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
400     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
401
402 /*!
403  * \brief Register a field within an object with custom handlers
404  *
405  * \param sorcery Pointer to a sorcery structure
406  * \param type Type of object
407  * \param name Name of the field
408  * \param default_val Default value of the field
409  * \param config_handler Custom configuration handler
410  * \param sorcery_handler Custom sorcery handler
411  * \param flags Option type specific flags
412  *
413  * \retval 0 success
414  * \retval -1 failure
415  */
416 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, flags, ...) \
417     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
418
419 /*!
420  * \brief Inform any wizards to load persistent objects
421  *
422  * \param sorcery Pointer to a sorcery structure
423  */
424 void ast_sorcery_load(const struct ast_sorcery *sorcery);
425
426 /*!
427  * \brief Inform any wizards of a specific object type to load persistent objects
428  *
429  * \param sorcery Pointer to a sorcery structure
430  * \param type Name of the object type to load
431  */
432 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
433
434 /*!
435  * \brief Inform any wizards to reload persistent objects
436  *
437  * \param sorcery Pointer to a sorcery structure
438  */
439 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
440
441 /*!
442  * \brief Inform any wizards of a specific object type to reload persistent objects
443  *
444  * \param sorcery Pointer to a sorcery structure
445  * \param type Name of the object type to reload
446  */
447 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
448
449 /*!
450  * \brief Increase the reference count of a sorcery structure
451  *
452  * \param sorcery Pointer to a sorcery structure
453  */
454 void ast_sorcery_ref(struct ast_sorcery *sorcery);
455
456 /*!
457  * \brief Create an object set (KVP list) for an object
458  *
459  * \param sorcery Pointer to a sorcery structure
460  * \param object Pointer to a sorcery object
461  *
462  * \retval non-NULL success
463  * \retval NULL if error occurred
464  *
465  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
466  */
467 struct ast_variable *ast_sorcery_objectset_create(const struct ast_sorcery *sorcery, const void *object);
468
469 /*!
470  * \brief Apply an object set (KVP list) to an object
471  *
472  * \param sorcery Pointer to a sorcery structure
473  * \param object Pointer to a sorcery object
474  * \param objectset Object set itself
475  *
476  * \retval 0 success
477  * \retval -1 failure
478  *
479  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
480  *       applied object set.
481  */
482 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
483
484 /*!
485  * \brief Create a changeset given two object sets
486  *
487  * \param original Original object set
488  * \param modified Modified object set
489  * \param changes Pointer to hold any changes between the object sets
490  *
491  * \retval 0 success
492  * \retval -1 failure
493  *
494  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
495  */
496 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
497
498 /*!
499  * \brief Allocate an object
500  *
501  * \param sorcery Pointer to a sorcery structure
502  * \param type Type of object to allocate
503  * \param id Optional unique identifier, if none is provided one will be generated
504  *
505  * \retval non-NULL success
506  * \retval NULL failure
507  */
508 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
509
510 /*!
511  * \brief Create a copy of an object
512  *
513  * \param sorcery Pointer to a sorcery structure
514  * \param object Existing object
515  *
516  * \retval non-NULL success
517  * \retval NULL failure
518  */
519 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
520
521 /*!
522  * \brief Create a changeset of two objects
523  *
524  * \param sorcery Pointer to a sorcery structure
525  * \param original Original object
526  * \param modified Modified object
527  * \param changes Pointer which will be populated with changes if any exist
528  *
529  * \retval 0 success
530  * \retval -1 failure
531  *
532  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
533  *
534  * \note While the objects must be of the same type they do not have to be the same object
535  */
536 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
537
538 /*!
539  * \brief Create and potentially persist an object using an available wizard
540  *
541  * \param sorcery Pointer to a sorcery structure
542  * \param object Pointer to a sorcery object
543  *
544  * \retval 0 success
545  * \retval -1 failure
546  */
547 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
548
549 /*!
550  * \brief Retrieve an object using its unique identifier
551  *
552  * \param sorcery Pointer to a sorcery structure
553  * \param type Type of object to retrieve
554  * \param id Unique object identifier
555  *
556  * \retval non-NULL if found
557  * \retval NULL if not found
558  */
559 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
560
561 /*!
562  * \brief Retrieve an object or multiple objects using specific fields
563  *
564  * \param sorcery Pointer to a sorcery structure
565  * \param type Type of object to retrieve
566  * \param flags Flags to control behavior
567  * \param fields Optional jbject fields and values to match against
568  *
569  * \retval non-NULL if found
570  * \retval NULL if not found
571  *
572  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
573  *       ao2_container that must be unreferenced after use.
574  *
575  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
576  *       of the given type.
577  */
578 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
579
580 /*!
581  * \brief Retrieve multiple objects using a regular expression on their id
582  *
583  * \param sorcery Pointer to a sorcery structure
584  * \param type Type of object to retrieve
585  * \param regex Regular expression
586  *
587  * \retval non-NULL if error occurs
588  * \retval NULL success
589  *
590  * \note The provided regex is treated as extended case sensitive.
591  */
592 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
593
594 /*!
595  * \brief Update an object
596  *
597  * \param sorcery Pointer to a sorcery structure
598  * \param object Pointer to a sorcery object
599  *
600  * \retval 0 success
601  * \retval -1 failure
602  */
603 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
604
605 /*!
606  * \brief Delete an object
607  *
608  * \param sorcery Pointer to a sorcery structure
609  * \param object Pointer to a sorcery object
610  *
611  * \retval 0 success
612  * \retval -1 failure
613  */
614 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
615
616 /*!
617  * \brief Decrease the reference count of a sorcery structure
618  *
619  * \param sorcery Pointer to a sorcery structure
620  */
621 void ast_sorcery_unref(struct ast_sorcery *sorcery);
622
623 /*!
624  * \brief Get the unique identifier of a sorcery object
625  *
626  * \param object Pointer to a sorcery object
627  *
628  * \retval unique identifier
629  */
630 const char *ast_sorcery_object_get_id(const void *object);
631
632 /*!
633  * \brief Get the type of a sorcery object
634  *
635  * \param object Pointer to a sorcery object
636  *
637  * \retval type of object
638  */
639 const char *ast_sorcery_object_get_type(const void *object);
640
641 #if defined(__cplusplus) || defined(c_plusplus)
642 }
643 #endif
644
645 #endif /* _ASTERISK_SORCERY_H */