Merge the sorcery data access layer API.
[asterisk/asterisk.git] / main / sorcery.c
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  *
21  * \brief Sorcery Data Access Layer API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 /*** MODULEINFO
27         <support_level>core</support_level>
28  ***/
29
30 #include "asterisk.h"
31
32 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
33
34 #include "asterisk/logger.h"
35 #include "asterisk/sorcery.h"
36 #include "asterisk/astobj2.h"
37 #include "asterisk/strings.h"
38 #include "asterisk/config_options.h"
39 #include "asterisk/netsock2.h"
40 #include "asterisk/module.h"
41
42 /*! \brief Number of buckets for wizards (should be prime for performance reasons) */
43 #define WIZARD_BUCKETS 7
44
45 /*! \brief Number of buckets for types (should be prime for performance reasons) */
46 #define TYPE_BUCKETS 53
47
48 /*! \brief Maximum length of an object field name */
49 #define MAX_OBJECT_FIELD 128
50
51 /*! \brief Structure for registered object type */
52 struct ast_sorcery_object_type {
53         /*! \brief Unique name of the object type */
54         char name[MAX_OBJECT_TYPE];
55
56         /*! \brief Optional transformation callback */
57         sorcery_transform_handler transform;
58
59         /*! \brief Optional object set apply callback */
60         sorcery_apply_handler apply;
61
62         /*! \brief Wizard instances */
63         struct ao2_container *wizards;
64
65         /*! \brief Object fields */
66         struct ao2_container *fields;
67
68         /*! \brief Configuration framework general information */
69         struct aco_info *info;
70
71         /*! \brief Configuration framework file information */
72         struct aco_file *file;
73
74         /*! \brief Type details */
75         struct aco_type type;
76 };
77
78 /*! \brief Structure for registered object field */
79 struct ast_sorcery_object_field {
80         /*! \brief Name of the field */
81         char name[MAX_OBJECT_FIELD];
82
83         /*! \brief Callback function for translation */
84         sorcery_field_handler handler;
85
86         /*! \brief Position of the field */
87         intptr_t args[];
88 };
89
90 /*! \brief Structure for a wizard instance which operates on objects */
91 struct ast_sorcery_object_wizard {
92         /*! \brief Wizard interface itself */
93         struct ast_sorcery_wizard *wizard;
94
95         /*! \brief Unique data for the wizard */
96         void *data;
97
98         /*! \brief Wizard is acting as an object cache */
99         unsigned int caching:1;
100 };
101
102 /*! \brief Full structure for sorcery */
103 struct ast_sorcery {
104         /*! \brief Container for known object types */
105         struct ao2_container *types;
106 };
107
108 /*! \brief Structure for passing load/reload details */
109 struct sorcery_load_details {
110         /*! \brief Sorcery structure in use */
111         const struct ast_sorcery *sorcery;
112
113         /*! \brief Type of object being loaded */
114         const char *type;
115
116         /*! \brief Whether this is a reload or not */
117         unsigned int reload:1;
118 };
119
120 /*! \brief Registered sorcery wizards */
121 struct ao2_container *wizards;
122
123 static int int_handler_fn(const void *obj, const intptr_t *args, char **buf)
124 {
125         int *field = (int *)(obj + args[0]);
126         return (ast_asprintf(buf, "%d", *field) < 0) ? -1 : 0;
127 }
128
129 static int uint_handler_fn(const void *obj, const intptr_t *args, char **buf)
130 {
131         unsigned int *field = (unsigned int *)(obj + args[0]);
132         return (ast_asprintf(buf, "%u", *field) < 0) ? -1 : 0;
133 }
134
135 static int double_handler_fn(const void *obj, const intptr_t *args, char **buf)
136 {
137         double *field = (double *)(obj + args[0]);
138         return (ast_asprintf(buf, "%f", *field) < 0) ? -1 : 0;
139 }
140
141 static int stringfield_handler_fn(const void *obj, const intptr_t *args, char **buf)
142 {
143         ast_string_field *field = (const char **)(obj + args[0]);
144         return !(*buf = ast_strdup(*field)) ? -1 : 0;
145 }
146
147 static int bool_handler_fn(const void *obj, const intptr_t *args, char **buf)
148 {
149         unsigned int *field = (unsigned int *)(obj + args[0]);
150         return !(*buf = ast_strdup(*field ? "true" : "false")) ? -1 : 0;
151 }
152
153 static int sockaddr_handler_fn(const void *obj, const intptr_t *args, char **buf)
154 {
155         struct ast_sockaddr *field = (struct ast_sockaddr *)(obj + args[0]);
156         return !(*buf = ast_strdup(ast_sockaddr_stringify(field))) ? -1 : 0;
157 }
158
159 static int noop_handler_fn(const void *obj, const intptr_t *args, char **buf)
160 {
161         return 0;
162 }
163
164 static int chararray_handler_fn(const void *obj, const intptr_t *args, char **buf)
165 {
166         char *field = (char *)(obj + args[0]);
167         return !(*buf = ast_strdup(field)) ? -1 : 0;
168 }
169
170 static sorcery_field_handler sorcery_field_default_handler(enum aco_option_type type)
171 {
172         switch(type) {
173         case OPT_BOOL_T: return bool_handler_fn;
174         case OPT_CHAR_ARRAY_T: return chararray_handler_fn;
175         case OPT_DOUBLE_T: return double_handler_fn;
176         case OPT_INT_T: return int_handler_fn;
177         case OPT_NOOP_T: return noop_handler_fn;
178         case OPT_SOCKADDR_T: return sockaddr_handler_fn;
179         case OPT_STRINGFIELD_T: return stringfield_handler_fn;
180         case OPT_UINT_T: return uint_handler_fn;
181
182         default:
183         case OPT_CUSTOM_T: return NULL;
184         }
185
186         return NULL;
187 }
188
189 /*! \brief Hashing function for sorcery wizards */
190 static int sorcery_wizard_hash(const void *obj, const int flags)
191 {
192         const struct ast_sorcery_wizard *wizard = obj;
193         const char *name = obj;
194
195         return ast_str_hash(flags & OBJ_KEY ? name : wizard->name);
196 }
197
198 /*! \brief Comparator function for sorcery wizards */
199 static int sorcery_wizard_cmp(void *obj, void *arg, int flags)
200 {
201         struct ast_sorcery_wizard *wizard1 = obj, *wizard2 = arg;
202         const char *name = arg;
203
204         return !strcmp(wizard1->name, flags & OBJ_KEY ? name : wizard2->name) ? CMP_MATCH | CMP_STOP : 0;
205 }
206
207 int ast_sorcery_init(void)
208 {
209         ast_assert(wizards == NULL);
210
211         if (!(wizards = ao2_container_alloc(WIZARD_BUCKETS, sorcery_wizard_hash, sorcery_wizard_cmp))) {
212                 return -1;
213         }
214
215         return 0;
216 }
217
218 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module)
219 {
220         struct ast_sorcery_wizard *wizard;
221         int res = -1;
222
223         ast_assert(!ast_strlen_zero(interface->name));
224
225         ao2_lock(wizards);
226
227         if ((wizard = ao2_find(wizards, interface->name, OBJ_KEY | OBJ_NOLOCK))) {
228                 ast_log(LOG_WARNING, "Attempted to register sorcery wizard '%s' twice\n",
229                         interface->name);
230                 goto done;
231         }
232
233         if (!(wizard = ao2_alloc(sizeof(*wizard), NULL))) {
234                 goto done;
235         }
236
237         *wizard = *interface;
238         wizard->module = module;
239
240         ao2_link_flags(wizards, wizard, OBJ_NOLOCK);
241         res = 0;
242
243         ast_verb(2, "Sorcery registered wizard '%s'\n", interface->name);
244
245 done:
246         ao2_cleanup(wizard);
247         ao2_unlock(wizards);
248
249         return res;
250 }
251
252 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface)
253 {
254         RAII_VAR(struct ast_sorcery_wizard *, wizard, ao2_find(wizards, interface->name, OBJ_KEY | OBJ_UNLINK), ao2_cleanup);
255
256         if (wizard) {
257                 ast_verb(2, "Sorcery unregistered wizard '%s'\n", interface->name);
258                 return 0;
259         } else {
260                 return -1;
261         }
262 }
263
264 /*! \brief Destructor called when sorcery structure is destroyed */
265 static void sorcery_destructor(void *obj)
266 {
267         struct ast_sorcery *sorcery = obj;
268
269         ao2_cleanup(sorcery->types);
270 }
271
272 /*! \brief Hashing function for sorcery types */
273 static int sorcery_type_hash(const void *obj, const int flags)
274 {
275         const struct ast_sorcery_object_type *type = obj;
276         const char *name = obj;
277
278         return ast_str_hash(flags & OBJ_KEY ? name : type->name);
279 }
280
281 /*! \brief Comparator function for sorcery types */
282 static int sorcery_type_cmp(void *obj, void *arg, int flags)
283 {
284         struct ast_sorcery_object_type *type1 = obj, *type2 = arg;
285         const char *name = arg;
286
287         return !strcmp(type1->name, flags & OBJ_KEY ? name : type2->name) ? CMP_MATCH | CMP_STOP : 0;
288 }
289
290 struct ast_sorcery *ast_sorcery_open(void)
291 {
292         struct ast_sorcery *sorcery;
293
294         if (!(sorcery = ao2_alloc(sizeof(*sorcery), sorcery_destructor))) {
295                 return NULL;
296         }
297
298         if (!(sorcery->types = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, TYPE_BUCKETS, sorcery_type_hash, sorcery_type_cmp))) {
299                 ao2_ref(sorcery, -1);
300                 sorcery = NULL;
301         }
302
303         return sorcery;
304 }
305
306 /*! \brief Destructor function for object types */
307 static void sorcery_object_type_destructor(void *obj)
308 {
309         struct ast_sorcery_object_type *object_type = obj;
310
311         ao2_cleanup(object_type->wizards);
312         ao2_cleanup(object_type->fields);
313
314         if (object_type->info) {
315                 aco_info_destroy(object_type->info);
316                 ast_free(object_type->info);
317         }
318
319         ast_free(object_type->file);
320 }
321
322 /*! \brief Internal function which allocates an object type structure */
323 static struct ast_sorcery_object_type *sorcery_object_type_alloc(const char *type)
324 {
325         struct ast_sorcery_object_type *object_type;
326
327         if (!(object_type = ao2_alloc(sizeof(*object_type), sorcery_object_type_destructor))) {
328                 return NULL;
329         }
330
331         /* Order matters for object wizards */
332         if (!(object_type->wizards = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, 1, NULL, NULL))) {
333                 ao2_ref(object_type, -1);
334                 return NULL;
335         }
336
337         if (!(object_type->fields = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, 1, NULL, NULL))) {
338                 ao2_ref(object_type, -1);
339                 return NULL;
340         }
341
342         if (!(object_type->info = ast_calloc(1, sizeof(*object_type->info) + 2 * sizeof(object_type->info->files[0])))) {
343                 ao2_ref(object_type, -1);
344                 return NULL;
345         }
346
347         if (!(object_type->file = ast_calloc(1, sizeof(*object_type->file) + 2 * sizeof(object_type->file->types[0])))) {
348                 ao2_ref(object_type, -1);
349                 return NULL;
350         }
351
352         object_type->info->files[0] = object_type->file;
353         object_type->info->files[1] = NULL;
354
355         ast_copy_string(object_type->name, type, sizeof(object_type->name));
356
357         return object_type;
358 }
359
360 /*! \brief Object wizard destructor */
361 static void sorcery_object_wizard_destructor(void *obj)
362 {
363         struct ast_sorcery_object_wizard *object_wizard = obj;
364
365         if (object_wizard->data) {
366                 object_wizard->wizard->close(object_wizard->data);
367         }
368
369         if (object_wizard->wizard) {
370                 ast_module_unref(object_wizard->wizard->module);
371         }
372 }
373
374 /*! \brief Internal function which creates an object type and adds a wizard mapping */
375 static int sorcery_apply_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *name, const char *data, unsigned int caching)
376 {
377         RAII_VAR(struct ast_sorcery_object_type *, object_type,  ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
378         RAII_VAR(struct ast_sorcery_wizard *, wizard, ao2_find(wizards, name, OBJ_KEY), ao2_cleanup);
379         RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, ao2_alloc(sizeof(*object_wizard), sorcery_object_wizard_destructor), ao2_cleanup);
380         int created = 0;
381
382         if (!wizard || !object_wizard) {
383                 return -1;
384         }
385
386         if (!object_type) {
387                 if (!(object_type = sorcery_object_type_alloc(type))) {
388                         return -1;
389                 }
390                 created = 1;
391         }
392
393         if (wizard->open && !(object_wizard->data = wizard->open(data))) {
394                 return -1;
395         }
396
397         ast_module_ref(wizard->module);
398
399         object_wizard->wizard = wizard;
400         object_wizard->caching = caching;
401
402         ao2_link(object_type->wizards, object_wizard);
403
404         if (created) {
405                 ao2_link(sorcery->types, object_type);
406         }
407
408         return 0;
409 }
410
411 int ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name)
412 {
413         struct ast_flags flags = { 0 };
414         struct ast_config *config = ast_config_load2("sorcery.conf", "sorcery", flags);
415         struct ast_variable *mapping;
416         int res = 0;
417
418         if (!config || (config == CONFIG_STATUS_FILEMISSING) || (config == CONFIG_STATUS_FILEINVALID)) {
419                 return -1;
420         }
421
422         for (mapping = ast_variable_browse(config, name); mapping; mapping = mapping->next) {
423                 RAII_VAR(char *, mapping_name, ast_strdup(mapping->name), ast_free);
424                 RAII_VAR(char *, mapping_value, ast_strdup(mapping->value), ast_free);
425                 char *options = mapping_name, *name = strsep(&options, "/");
426                 char *data = mapping_value, *wizard = strsep(&data, ",");
427                 unsigned int caching = 0;
428
429                 /* If no wizard exists just skip, nothing we can do */
430                 if (ast_strlen_zero(wizard)) {
431                         continue;
432                 }
433
434                 /* If the wizard is configured as a cache treat it as such */
435                 if (!ast_strlen_zero(options) && strstr(options, "cache")) {
436                         caching = 1;
437                 }
438
439                 /* Any error immediately causes us to stop */
440                 if ((res = sorcery_apply_wizard_mapping(sorcery, name, wizard, data, caching))) {
441                         break;
442                 }
443         }
444
445         ast_config_destroy(config);
446
447         return res;
448 }
449
450 int ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *name, const char *data)
451 {
452         RAII_VAR(struct ast_sorcery_object_type *, object_type,  ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
453
454         /* Defaults can not be added if any existing mapping exists */
455         if (object_type) {
456                 return -1;
457         }
458
459         return sorcery_apply_wizard_mapping(sorcery, type, name, data, 0);
460 }
461
462 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)
463 {
464         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
465
466         if (!object_type) {
467                 return -1;
468         }
469
470         object_type->type.type = ACO_ITEM;
471         object_type->type.category = "";
472         object_type->type.item_alloc = alloc;
473
474         object_type->transform = transform;
475         object_type->file->types[0] = &object_type->type;
476         object_type->file->types[1] = NULL;
477
478         if (aco_info_init(object_type->info)) {
479                 return -1;
480         }
481
482         return 0;
483 }
484
485 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,
486                                         aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, size_t argc, ...)
487 {
488         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
489         RAII_VAR(struct ast_sorcery_object_field *, object_field, NULL, ao2_cleanup);
490         int pos;
491         va_list args;
492
493         if (!object_type || !object_type->type.item_alloc) {
494                 return -1;
495         }
496
497         if (!sorcery_handler) {
498                 sorcery_handler = sorcery_field_default_handler(opt_type);
499         }
500
501         if (!(object_field = ao2_alloc(sizeof(*object_field) + argc * sizeof(object_field->args[0]), NULL))) {
502                 return -1;
503         }
504
505         ast_copy_string(object_field->name, name, sizeof(object_field->name));
506         object_field->handler = sorcery_handler;
507
508         va_start(args, argc);
509         for (pos = 0; pos < argc; pos++) {
510                 object_field->args[pos] = va_arg(args, size_t);
511         }
512         va_end(args);
513
514         ao2_link(object_type->fields, object_field);
515
516         /* TODO: Improve this hack */
517         if (!argc) {
518                 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc);
519         } else if (argc == 1) {
520                 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc,
521                                       object_field->args[0]);
522         } else if (argc == 2) {
523                 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc,
524                                       object_field->args[0], object_field->args[1]);
525         } else if (argc == 3) {
526                 __aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc,
527                                       object_field->args[0], object_field->args[1], object_field->args[2]);
528         } else {
529                 ast_assert(0); /* The hack... she does us no good for this */
530         }
531
532         return 0;
533 }
534
535 static int sorcery_wizard_load(void *obj, void *arg, int flags)
536 {
537         struct ast_sorcery_object_wizard *wizard = obj;
538         struct sorcery_load_details *details = arg;
539         void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
540
541         load = !details->reload ? wizard->wizard->load : wizard->wizard->reload;
542
543         if (load) {
544                 load(wizard->data, details->sorcery, details->type);
545         }
546
547         return 0;
548 }
549
550 static int sorcery_object_load(void *obj, void *arg, int flags)
551 {
552         struct ast_sorcery_object_type *type = obj;
553         struct sorcery_load_details *details = arg;
554
555         details->type = type->name;
556         ao2_callback(type->wizards, OBJ_NODATA, sorcery_wizard_load, details);
557
558         return 0;
559 }
560
561 void ast_sorcery_load(const struct ast_sorcery *sorcery)
562 {
563         struct sorcery_load_details details = {
564                 .sorcery = sorcery,
565                 .reload = 0,
566         };
567
568         ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
569 }
570
571 void ast_sorcery_reload(const struct ast_sorcery *sorcery)
572 {
573         struct sorcery_load_details details = {
574                 .sorcery = sorcery,
575                 .reload = 1,
576         };
577
578         ao2_callback(sorcery->types, OBJ_NODATA, sorcery_object_load, &details);
579 }
580
581 void ast_sorcery_ref(struct ast_sorcery *sorcery)
582 {
583         ao2_ref(sorcery, +1);
584 }
585
586 struct ast_variable *ast_sorcery_objectset_create(const struct ast_sorcery *sorcery, const void *object)
587 {
588         const struct ast_sorcery_object_details *details = object;
589         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->type, OBJ_KEY), ao2_cleanup);
590         struct ao2_iterator i;
591         struct ast_sorcery_object_field *object_field;
592         struct ast_variable *fields = NULL;
593         int res = 0;
594
595         if (!object_type) {
596                 return NULL;
597         }
598
599         i = ao2_iterator_init(object_type->fields, 0);
600
601         for (; (object_field = ao2_iterator_next(&i)); ao2_ref(object_field, -1)) {
602                 RAII_VAR(char *, buf, NULL, ast_free);
603                 struct ast_variable *tmp;
604
605                 /* Any fields with no handler just get skipped */
606                 if (!object_field->handler) {
607                         continue;
608                 }
609
610                 if ((res = object_field->handler(object, object_field->args, &buf)) ||
611                     !(tmp = ast_variable_new(object_field->name, S_OR(buf, ""), ""))) {
612                         res = -1;
613                         ao2_ref(object_field, -1);
614                         break;
615                 }
616
617                 tmp->next = fields;
618                 fields = tmp;
619         }
620
621         ao2_iterator_destroy(&i);
622
623         /* If any error occurs we destroy all fields handled before so a partial objectset is not returned */
624         if (res) {
625                 ast_variables_destroy(fields);
626                 fields = NULL;
627         }
628
629         return fields;
630 }
631
632 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset)
633 {
634         const struct ast_sorcery_object_details *details = object;
635         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->type, OBJ_KEY), ao2_cleanup);
636         RAII_VAR(struct ast_variable *, transformed, NULL, ast_variables_destroy);
637         struct ast_variable *field;
638         int res = 0;
639
640         if (!object_type) {
641                 return -1;
642         }
643
644         if (object_type->transform && (transformed = object_type->transform(objectset))) {
645                 field = transformed;
646         } else {
647                 field = objectset;
648         }
649
650         for (; field; field = field->next) {
651                 if ((res = aco_process_var(&object_type->type, details->id, field, object))) {
652                         break;
653                 }
654         }
655
656         if (!res && object_type->apply) {
657                 object_type->apply(sorcery, object);
658         }
659
660         return res;
661 }
662
663 static const struct ast_variable *sorcery_find_field(const struct ast_variable *fields, const char *name)
664 {
665         const struct ast_variable *field;
666
667         /* Search the linked list of fields to find the correct one */
668         for (field = fields; field; field = field->next) {
669                 if (!strcmp(field->name, name)) {
670                         return field;
671                 }
672         }
673
674         return NULL;
675 }
676
677 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes)
678 {
679         const struct ast_variable *field;
680         int res = 0;
681
682         *changes = NULL;
683
684         /* Unless the ast_variable list changes when examined... it can't differ from itself */
685         if (original == modified) {
686                 return 0;
687         }
688
689         for (field = modified; field; field = field->next) {
690                 const struct ast_variable *old = sorcery_find_field(original, field->name);
691
692                 if (!old || strcmp(old->value, field->value)) {
693                         struct ast_variable *tmp;
694
695                         if (!(tmp = ast_variable_new(field->name, field->value, ""))) {
696                                 res = -1;
697                                 break;
698                         }
699
700                         tmp->next = *changes;
701                         *changes = tmp;
702                 }
703         }
704
705         /* If an error occurred do not return a partial changeset */
706         if (res) {
707                 ast_variables_destroy(*changes);
708                 *changes = NULL;
709         }
710
711         return res;
712 }
713
714 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id)
715 {
716         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
717         struct ast_sorcery_object_details *details;
718
719         if (!object_type || !object_type->type.item_alloc ||
720             !(details = object_type->type.item_alloc(""))) {
721                 return NULL;
722         }
723
724         if (ast_strlen_zero(id)) {
725                 struct ast_uuid *uuid = ast_uuid_generate();
726
727                 if (!uuid) {
728                         ao2_ref(details, -1);
729                         return NULL;
730                 }
731
732                 ast_uuid_to_str(uuid, details->id, AST_UUID_STR_LEN);
733                 ast_free(uuid);
734         } else {
735                 ast_copy_string(details->id, id, sizeof(details->id));
736         }
737
738         ast_copy_string(details->type, type, sizeof(details->type));
739
740         if (aco_set_defaults(&object_type->type, id, details)) {
741                 ao2_ref(details, -1);
742                 return NULL;
743         }
744
745         return details;
746 }
747
748 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object)
749 {
750         const struct ast_sorcery_object_details *details = object;
751         struct ast_sorcery_object_details *copy = ast_sorcery_alloc(sorcery, details->type, details->id);
752         RAII_VAR(struct ast_variable *, objectset, NULL, ast_variables_destroy);
753
754         if (!copy ||
755             !(objectset = ast_sorcery_objectset_create(sorcery, object)) ||
756             ast_sorcery_objectset_apply(sorcery, copy, objectset)) {
757                 ao2_cleanup(copy);
758                 return NULL;
759         }
760
761         return copy;
762 }
763
764 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes)
765 {
766         RAII_VAR(struct ast_variable *, objectset1, NULL, ast_variables_destroy);
767         RAII_VAR(struct ast_variable *, objectset2, NULL, ast_variables_destroy);
768
769         *changes = NULL;
770
771         if (strcmp(ast_sorcery_object_get_type(original), ast_sorcery_object_get_type(modified))) {
772                 return -1;
773         }
774
775         objectset1 = ast_sorcery_objectset_create(sorcery, original);
776         objectset2 = ast_sorcery_objectset_create(sorcery, modified);
777
778         return ast_sorcery_changeset_create(objectset1, objectset2, changes);
779 }
780
781 /*! \brief Internal function used to create an object in caching wizards */
782 static int sorcery_cache_create(void *obj, void *arg, int flags)
783 {
784         struct ast_sorcery_object_wizard *object_wizard = obj;
785
786         if (!object_wizard->caching || !object_wizard->wizard->create) {
787                 return 0;
788         }
789
790         object_wizard->wizard->create(object_wizard->data, arg);
791
792         return 0;
793 }
794
795 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id)
796 {
797         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
798         void *object = NULL;
799         struct ao2_iterator i;
800         struct ast_sorcery_object_wizard *wizard;
801         unsigned int cached = 0;
802
803         if (!object_type || ast_strlen_zero(id)) {
804                 return NULL;
805         }
806
807         i = ao2_iterator_init(object_type->wizards, 0);
808         for (; (wizard = ao2_iterator_next(&i)); ao2_ref(wizard, -1)) {
809                 if (wizard->wizard->retrieve_id &&
810                     !(object = wizard->wizard->retrieve_id(sorcery, wizard->data, object_type->name, id))) {
811                         continue;
812                 }
813
814                 cached = wizard->caching;
815
816                 ao2_ref(wizard, -1);
817                 break;
818         }
819         ao2_iterator_destroy(&i);
820
821         if (!cached && object) {
822                 ao2_callback(object_type->wizards, 0, sorcery_cache_create, object);
823         }
824
825         return object;
826 }
827
828 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields)
829 {
830         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
831         void *object = NULL;
832         struct ao2_iterator i;
833         struct ast_sorcery_object_wizard *wizard;
834         unsigned int cached = 0;
835
836         if (!object_type) {
837                 return NULL;
838         }
839
840         /* If returning multiple objects create a container to store them in */
841         if ((flags & AST_RETRIEVE_FLAG_MULTIPLE)) {
842                 if (!(object = ao2_container_alloc_options(AO2_ALLOC_OPT_LOCK_NOLOCK, 1, NULL, NULL))) {
843                         return NULL;
844                 }
845         }
846
847         /* Inquire with the available wizards for retrieval */
848         i = ao2_iterator_init(object_type->wizards, 0);
849         for (; (wizard = ao2_iterator_next(&i)); ao2_ref(wizard, -1)) {
850                 if ((flags & AST_RETRIEVE_FLAG_MULTIPLE)) {
851                         if (wizard->wizard->retrieve_multiple) {
852                                 wizard->wizard->retrieve_multiple(sorcery, wizard->data, object_type->name, object, fields);
853                         }
854                 } else if (fields && wizard->wizard->retrieve_fields) {
855                         if (wizard->wizard->retrieve_fields) {
856                                 object = wizard->wizard->retrieve_fields(sorcery, wizard->data, object_type->name, fields);
857                         }
858                 }
859
860                 if ((flags & AST_RETRIEVE_FLAG_MULTIPLE) || !object) {
861                         continue;
862                 }
863
864                 cached = wizard->caching;
865
866                 ao2_ref(wizard, -1);
867                 break;
868         }
869         ao2_iterator_destroy(&i);
870
871         /* If we are returning a single object and it came from a non-cache source create it in any caches */
872         if (!(flags & AST_RETRIEVE_FLAG_MULTIPLE) && !cached && object) {
873                 ao2_callback(object_type->wizards, 0, sorcery_cache_create, object);
874         }
875
876         return object;
877 }
878
879 /*! \brief Internal function which returns if the wizard has created the object */
880 static int sorcery_wizard_create(void *obj, void *arg, int flags)
881 {
882         const struct ast_sorcery_object_wizard *object_wizard = obj;
883
884         return (!object_wizard->caching && !object_wizard->wizard->create(object_wizard->data, arg)) ? CMP_MATCH | CMP_STOP : 0;
885 }
886
887 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object)
888 {
889         const struct ast_sorcery_object_details *details = object;
890         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->type, OBJ_KEY), ao2_cleanup);
891         RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, NULL, ao2_cleanup);
892
893         if (!object_type) {
894                 return -1;
895         }
896
897         object_wizard = ao2_callback(object_type->wizards, 0, sorcery_wizard_create, object);
898
899         return object_wizard ? 0 : -1;
900 }
901
902 /*! \brief Internal function which returns if a wizard has updated the object */
903 static int sorcery_wizard_update(void *obj, void *arg, int flags)
904 {
905         const struct ast_sorcery_object_wizard *object_wizard = obj;
906
907         return (object_wizard->wizard->update && !object_wizard->wizard->update(object_wizard->data, arg) &&
908                 !object_wizard->caching) ? CMP_MATCH | CMP_STOP : 0;
909 }
910
911 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object)
912 {
913         const struct ast_sorcery_object_details *details = object;
914         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->type, OBJ_KEY), ao2_cleanup);
915         RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, NULL, ao2_cleanup);
916
917         if (!object_type) {
918                 return -1;
919         }
920
921         object_wizard = ao2_callback(object_type->wizards, 0, sorcery_wizard_update, object);
922
923         return object_wizard ? 0 : -1;
924 }
925
926 /*! \brief Internal function which returns if a wizard has deleted the object */
927 static int sorcery_wizard_delete(void *obj, void *arg, int flags)
928 {
929         const struct ast_sorcery_object_wizard *object_wizard = obj;
930
931         return (object_wizard->wizard->delete && !object_wizard->wizard->delete(object_wizard->data, arg) &&
932                 !object_wizard->caching) ? CMP_MATCH | CMP_STOP : 0;
933 }
934
935 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object)
936 {
937         const struct ast_sorcery_object_details *details = object;
938         RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, details->type, OBJ_KEY), ao2_cleanup);
939         RAII_VAR(struct ast_sorcery_object_wizard *, object_wizard, NULL, ao2_cleanup);
940
941         if (!object_type) {
942                 return -1;
943         }
944
945         object_wizard = ao2_callback(object_type->wizards, 0, sorcery_wizard_delete, object);
946
947         return object_wizard ? 0 : -1;
948 }
949
950 void ast_sorcery_unref(struct ast_sorcery *sorcery)
951 {
952         ao2_cleanup(sorcery);
953 }
954
955 const char *ast_sorcery_object_get_id(const void *object)
956 {
957         const struct ast_sorcery_object_details *details = object;
958         return details->id;
959 }
960
961 const char *ast_sorcery_object_get_type(const void *object)
962 {
963         const struct ast_sorcery_object_details *details = object;
964         return details->type;
965 }