res_fax.c: Add chan locked precondition comments.
[asterisk/asterisk.git] / res / res_sorcery_realtime.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 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 /*!
20  * \file
21  *
22  * \brief Sorcery Realtime Object Wizard
23  *
24  * \author Joshua Colp <jcolp@digium.com>
25  */
26
27 /*** MODULEINFO
28         <support_level>core</support_level>
29  ***/
30
31 #include "asterisk.h"
32
33 ASTERISK_REGISTER_FILE()
34
35 #include <regex.h>
36
37 #include "asterisk/module.h"
38 #include "asterisk/sorcery.h"
39
40 /*! \brief They key field used to store the unique identifier for the object */
41 #define UUID_FIELD "id"
42
43 enum unqualified_fetch {
44         UNQUALIFIED_FETCH_NO,
45         UNQUALIFIED_FETCH_WARN,
46         UNQUALIFIED_FETCH_YES,
47         UNQUALIFIED_FETCH_ERROR,
48 };
49
50 struct sorcery_config {
51         enum unqualified_fetch fetch;
52         char family[];
53 };
54
55 static void *sorcery_realtime_open(const char *data);
56 static int sorcery_realtime_create(const struct ast_sorcery *sorcery, void *data, void *object);
57 static void *sorcery_realtime_retrieve_id(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
58 static void *sorcery_realtime_retrieve_fields(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
59 static void sorcery_realtime_retrieve_multiple(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects,
60                                              const struct ast_variable *fields);
61 static void sorcery_realtime_retrieve_regex(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
62 static int sorcery_realtime_update(const struct ast_sorcery *sorcery, void *data, void *object);
63 static int sorcery_realtime_delete(const struct ast_sorcery *sorcery, void *data, void *object);
64 static void sorcery_realtime_close(void *data);
65
66 static struct ast_sorcery_wizard realtime_object_wizard = {
67         .name = "realtime",
68         .open = sorcery_realtime_open,
69         .create = sorcery_realtime_create,
70         .retrieve_id = sorcery_realtime_retrieve_id,
71         .retrieve_fields = sorcery_realtime_retrieve_fields,
72         .retrieve_multiple = sorcery_realtime_retrieve_multiple,
73         .retrieve_regex = sorcery_realtime_retrieve_regex,
74         .update = sorcery_realtime_update,
75         .delete = sorcery_realtime_delete,
76         .close = sorcery_realtime_close,
77 };
78
79 static int sorcery_realtime_create(const struct ast_sorcery *sorcery, void *data, void *object)
80 {
81         struct sorcery_config *config = data;
82         RAII_VAR(struct ast_variable *, fields, ast_sorcery_objectset_create(sorcery, object), ast_variables_destroy);
83         struct ast_variable *id = ast_variable_new(UUID_FIELD, ast_sorcery_object_get_id(object), "");
84
85         if (!fields || !id) {
86                 ast_variables_destroy(id);
87                 return -1;
88         }
89
90         /* Place the identifier at the front for sanity sake */
91         id->next = fields;
92         fields = id;
93
94         return (ast_store_realtime_fields(config->family, fields) <= 0) ? -1 : 0;
95 }
96
97 /*! \brief Internal helper function which returns a filtered objectset. 
98  *
99  * The following are filtered out of the objectset:
100  * \li The id field. This is returned to the caller in an out parameter.
101  * \li Fields that are not registered with sorcery.
102  *
103  * \param objectset Objectset to filter.
104  * \param[out] id The ID of the sorcery object, as found in the objectset.
105  * \param sorcery The sorcery instance that is requesting an objectset.
106  * \param type The object type
107  *
108  * \return The filtered objectset
109  */
110 static struct ast_variable *sorcery_realtime_filter_objectset(struct ast_variable *objectset, struct ast_variable **id,
111                 const struct ast_sorcery *sorcery, const char *type)
112 {
113         struct ast_variable *previous = NULL, *field = objectset;
114         struct ast_sorcery_object_type *object_type;
115
116         object_type = ast_sorcery_get_object_type(sorcery, type);
117         if (!object_type) {
118                 ast_log(LOG_WARNING, "Unknown sorcery object type %s. Expect errors\n", type);
119                 /* Continue since we still want to filter out the id */
120         }
121
122         while (field) {
123                 int remove_field = 0;
124                 int delete_field = 0;
125
126                 if (!strcmp(field->name, UUID_FIELD)) {
127                         *id = field;
128                         remove_field = 1;
129                 } else if (object_type &&
130                                 !ast_sorcery_is_object_field_registered(object_type, field->name)) {
131                         ast_debug(1, "Filtering out realtime field '%s' from retrieval\n", field->name);
132                         remove_field = 1;
133                         delete_field = 1;
134                 }
135
136                 if (remove_field) {
137                         struct ast_variable *removed;
138
139                         if (previous) {
140                                 previous->next = field->next;
141                         } else {
142                                 objectset = field->next;
143                         }
144
145                         removed = field;
146                         field = field->next;
147                         removed->next = NULL;
148                         if (delete_field) {
149                                 ast_variables_destroy(removed);
150                         }
151                 } else {
152                         previous = field;
153                         field = field->next;
154                 }
155         }
156
157         ao2_cleanup(object_type);
158
159         return objectset;
160 }
161
162 static void *sorcery_realtime_retrieve_fields(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields)
163 {
164         struct sorcery_config *config = data;
165         RAII_VAR(struct ast_variable *, objectset, NULL, ast_variables_destroy);
166         RAII_VAR(struct ast_variable *, id, NULL, ast_variables_destroy);
167         void *object = NULL;
168
169         if (!(objectset = ast_load_realtime_fields(config->family, fields))) {
170                 return NULL;
171         }
172
173         objectset = sorcery_realtime_filter_objectset(objectset, &id, sorcery, type);
174
175         if (!id
176                 || !(object = ast_sorcery_alloc(sorcery, type, id->value))
177                 || ast_sorcery_objectset_apply(sorcery, object, objectset)) {
178                 return NULL;
179         }
180
181         return object;
182 }
183
184 static void *sorcery_realtime_retrieve_id(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id)
185 {
186         RAII_VAR(struct ast_variable *, fields, ast_variable_new(UUID_FIELD, id, ""), ast_variables_destroy);
187
188         return sorcery_realtime_retrieve_fields(sorcery, data, type, fields);
189 }
190
191 static void sorcery_realtime_retrieve_multiple(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields)
192 {
193         struct sorcery_config *config = data;
194         RAII_VAR(struct ast_config *, rows, NULL, ast_config_destroy);
195         RAII_VAR(struct ast_variable *, all, NULL, ast_variables_destroy);
196         struct ast_category *row = NULL;
197
198         if (!fields) {
199                 char field[strlen(UUID_FIELD) + 6], value[2];
200
201                 if (config->fetch == UNQUALIFIED_FETCH_NO) {
202                         return;
203                 }
204                 if (config->fetch == UNQUALIFIED_FETCH_ERROR) {
205                         ast_log(LOG_ERROR, "Unqualified fetch prevented on %s\n", config->family);
206                         return;
207                 }
208                 if (config->fetch == UNQUALIFIED_FETCH_WARN) {
209                         ast_log(LOG_WARNING, "Unqualified fetch attempted on %s\n", config->family);
210                         return;
211                 }
212
213                 /* If no fields have been specified we want all rows, so trick realtime into doing it */
214                 snprintf(field, sizeof(field), "%s LIKE", UUID_FIELD);
215                 snprintf(value, sizeof(value), "%%");
216
217                 if (!(all = ast_variable_new(field, value, ""))) {
218                         return;
219                 }
220
221                 fields = all;
222         }
223
224         if (!(rows = ast_load_realtime_multientry_fields(config->family, fields))) {
225                 return;
226         }
227
228         while ((row = ast_category_browse_filtered(rows, NULL, row, NULL))) {
229                 struct ast_variable *objectset = ast_category_detach_variables(row);
230                 RAII_VAR(struct ast_variable *, id, NULL, ast_variables_destroy);
231                 RAII_VAR(void *, object, NULL, ao2_cleanup);
232
233                 objectset = sorcery_realtime_filter_objectset(objectset, &id, sorcery, type);
234
235                 if (id && (object = ast_sorcery_alloc(sorcery, type, id->value)) && !ast_sorcery_objectset_apply(sorcery, object, objectset)) {
236                         ao2_link(objects, object);
237                 }
238
239                 ast_variables_destroy(objectset);
240         }
241 }
242
243 static void sorcery_realtime_retrieve_regex(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex)
244 {
245         char field[strlen(UUID_FIELD) + 6], value[strlen(regex) + 3];
246         RAII_VAR(struct ast_variable *, fields, NULL, ast_variables_destroy);
247
248         if (!ast_strlen_zero(regex)) {
249                 /* The realtime API provides no direct ability to do regex so for now we support a limited subset using pattern matching */
250                 snprintf(field, sizeof(field), "%s LIKE", UUID_FIELD);
251                 if (regex[0] == '^') {
252                         snprintf(value, sizeof(value), "%s%%", regex + 1);
253                 } else {
254                         snprintf(value, sizeof(value), "%%%s%%", regex);
255                 }
256
257                 if (!(fields = ast_variable_new(field, value, ""))) {
258                         return;
259                 }
260         }
261
262         sorcery_realtime_retrieve_multiple(sorcery, data, type, objects, fields);
263 }
264
265 static int sorcery_realtime_update(const struct ast_sorcery *sorcery, void *data, void *object)
266 {
267         struct sorcery_config *config = data;
268         RAII_VAR(struct ast_variable *, fields, ast_sorcery_objectset_create(sorcery, object), ast_variables_destroy);
269
270         if (!fields) {
271                 return -1;
272         }
273
274         return (ast_update_realtime_fields(config->family, UUID_FIELD, ast_sorcery_object_get_id(object), fields) < 0) ? -1 : 0;
275 }
276
277 static int sorcery_realtime_delete(const struct ast_sorcery *sorcery, void *data, void *object)
278 {
279         struct sorcery_config *config = data;
280
281         return (ast_destroy_realtime_fields(config->family, UUID_FIELD, ast_sorcery_object_get_id(object), NULL) <= 0) ? -1 : 0;
282 }
283
284 static void *sorcery_realtime_open(const char *data)
285 {
286         struct sorcery_config *config;
287         char *tmp;
288         char *family;
289         char *option;
290
291         /* We require a prefix for family string generation, or else stuff could mix together */
292         if (ast_strlen_zero(data)) {
293                 return NULL;
294         }
295
296         tmp = ast_strdupa(data);
297         family = strsep(&tmp, ",");
298
299         if (!ast_realtime_is_mapping_defined(family)) {
300                 return NULL;
301         }
302
303         config = ast_calloc(1, sizeof(*config) + strlen(family) + 1);
304         if (!config) {
305                 return NULL;
306         }
307
308         strcpy(config->family, family); /* Safe */
309         config->fetch = UNQUALIFIED_FETCH_YES;
310
311         while ((option = strsep(&tmp, ","))) {
312                 char *name = strsep(&option, "=");
313                 char *value = option;
314
315                 if (!strcasecmp(name, "allow_unqualified_fetch")) {
316                         if (ast_strlen_zero(value) || !strcasecmp(value, "yes")) {
317                                 config->fetch = UNQUALIFIED_FETCH_YES;
318                         } else if (!strcasecmp(value, "no")) {
319                                 config->fetch = UNQUALIFIED_FETCH_NO;
320                         } else if (!strcasecmp(value, "warn")) {
321                                 config->fetch = UNQUALIFIED_FETCH_WARN;
322                         } else if (!strcasecmp(value, "error")) {
323                                 config->fetch = UNQUALIFIED_FETCH_ERROR;
324                         } else {
325                                 ast_log(LOG_ERROR, "Unrecognized value in %s:%s: '%s'\n", family, name, value);
326                                 return NULL;
327                         }
328                 } else {
329                         ast_log(LOG_ERROR, "Unrecognized option in %s: '%s'\n", family, name);
330                         return NULL;
331                 }
332         }
333
334         return config;
335 }
336
337 static void sorcery_realtime_close(void *data)
338 {
339         ast_free(data);
340 }
341
342 static int load_module(void)
343 {
344         if (ast_sorcery_wizard_register(&realtime_object_wizard)) {
345                 return AST_MODULE_LOAD_DECLINE;
346         }
347
348         return AST_MODULE_LOAD_SUCCESS;
349 }
350
351 static int unload_module(void)
352 {
353         ast_sorcery_wizard_unregister(&realtime_object_wizard);
354         return 0;
355 }
356
357 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "Sorcery Realtime Object Wizard",
358         .support_level = AST_MODULE_SUPPORT_CORE,
359         .load = load_module,
360         .unload = unload_module,
361         .load_pri = AST_MODPRI_REALTIME_DRIVER,
362 );