ARI: Add ability to raise arbitrary User Events
[asterisk/asterisk.git] / main / optional_api.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@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 #include "asterisk.h"
20
21 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
22
23 #include "asterisk/optional_api.h"
24 #include "asterisk/utils.h"
25
26 #if defined(OPTIONAL_API)
27
28 /*
29  * \file Optional API innards.
30  *
31  * The calls to ast_optional_api_*() happen implicitly from \c __constructor__
32  * calls which are defined in header files. This means that some number of them
33  * happen before main() is called. This makes calling most Asterisk APIs
34  * dangerous, since we could be called before they are initialized. This
35  * includes things like AO2, malloc debug, and static mutexes.
36  *
37  * Another limitation is that most functions are called from the midst of
38  * dlopen() or dlclose(), and there is no opportunity to return a failure code.
39  * The best we can do is log an error, and call ast_do_crash().
40  *
41  * Fortunately, there are some constraints that help us out. The \c
42  * ast_optional_api_*() are called during module loads, which happens either
43  * before main(), or during dlopen() calls. These are already serialized, so we
44  * don't have to lock ourselves.
45  */
46
47 /*! \brief A user of an optional API */
48 struct optional_api_user {
49         /*! Pointer to function pointer to link */
50         ast_optional_fn *optional_ref;
51         /*! Stub to use when impl is unavailable */
52         ast_optional_fn stub;
53         /*! Name of the module using the API */
54         char module[];
55 };
56
57 /*! \brief An optional API */
58 struct optional_api {
59         /*! Pointer to the implementation function; could be null */
60         ast_optional_fn impl;
61         /*! Variable length array of users of this API */
62         struct optional_api_user **users;
63         /*! Allocated size of the \a users array */
64         size_t users_maxlen;
65         /*! Number of entries in the \a users array */
66         size_t users_len;
67         /*! Name of the optional API function */
68         char symname[];
69 };
70
71 /*!
72  * \brief Free an \ref optional_api_user.
73  *
74  * \param user User struct to free.
75  */
76 static void optional_api_user_destroy(struct optional_api_user *user)
77 {
78         *user->optional_ref = user->stub;
79         ast_std_free(user);
80 }
81
82 /*!
83  * \brief Create an \ref optional_api_user.
84  *
85  * \param optional_ref Pointer-to-function-pointer to link to impl/stub.
86  * \param stub Stub function to link to when impl is not available.
87  * \param module Name of the module requesting the API.
88  *
89  * \return New \ref optional_api_user.
90  * \return \c NULL on error.
91  */
92 static struct optional_api_user *optional_api_user_create(
93         ast_optional_fn *optional_ref, ast_optional_fn stub, const char *module)
94 {
95         struct optional_api_user *user;
96         size_t size = sizeof(*user) + strlen(module) + 1;
97
98         user = ast_std_calloc(1, size);
99         if (!user) {
100                 return NULL;
101         }
102
103         user->optional_ref = optional_ref;
104         user->stub = stub;
105         strcpy(user->module, module); /* SAFE */
106
107         return user;
108 }
109
110 /*!
111  * \brief Free an \ref optional_api.
112  *
113  * \param api API struct to free.
114  */
115 static void optional_api_destroy(struct optional_api *api)
116 {
117         while (api->users_len--) {
118                 optional_api_user_destroy(api->users[api->users_len]);
119         }
120         ast_std_free(api->users);
121         api->users = NULL;
122         api->users_maxlen = 0;
123         ast_std_free(api);
124 }
125
126 /*!
127  * \brief Create an \ref optional_api.
128  *
129  * \param symname Name of the optional function.
130  * \return New \ref optional_api.
131  * \return \c NULL on error.
132  */
133 static struct optional_api *optional_api_create(const char *symname)
134 {
135         struct optional_api *api;
136         size_t size;
137
138         ast_verb(6, "%s: building api object\n", symname);
139         size = sizeof(*api) + strlen(symname) + 1;
140         api = ast_std_calloc(1, size);
141         if (!api) {
142                 ast_log(LOG_ERROR, "Failed to allocate api\n");
143                 return NULL;
144         }
145
146         strcpy(api->symname, symname); /* SAFE */
147
148         return api;
149 }
150
151 /*! Array of \ref optional_api functions */
152 struct {
153         /*! Variable length array of API's */
154         struct optional_api **list;
155         /*! Allocated size of the \a list array */
156         size_t maxlen;
157         /*! Number of entries in the \a list array */
158         size_t len;
159 } apis;
160
161 /*!
162  * \brief Gets (or creates) the \ref optional_api for the given function.
163  *
164  * \param sysname Name of the function to look up.
165  * \return Corresponding \ref optional_api.
166  * \return \c NULL on error.
167  */
168 static struct optional_api *get_api(const char *symname)
169 {
170         struct optional_api *api;
171         size_t i;
172
173         /* Find one, if we already have it */
174         if (apis.list) {
175                 for (i = 0; i < apis.len; ++i) {
176                         if (strcmp(symname, apis.list[i]->symname) == 0) {
177                                 return apis.list[i];
178                         }
179                 }
180         }
181
182         /* API not found. Build one */
183         api = optional_api_create(symname);
184         if (!api) {
185                 return NULL;
186         }
187
188         /* Grow the list, if needed */
189         if (apis.len + 1 > apis.maxlen) {
190                 size_t new_maxlen = apis.maxlen ? 2 * apis.maxlen : 1;
191                 struct optional_api **new_list;
192
193                 new_list = ast_std_realloc(apis.list, new_maxlen * sizeof(*new_list));
194                 if (!new_list) {
195                         optional_api_destroy(api);
196                         ast_log(LOG_ERROR, "Failed to allocate api list\n");
197                         return NULL;
198                 }
199
200                 apis.maxlen = new_maxlen;
201                 apis.list = new_list;
202         }
203
204         apis.list[apis.len++] = api;
205
206         return api;
207 }
208
209 /*!
210  * \brief Re-links a given \a user against its associated \a api.
211  *
212  * If the \a api has an implementation, the \a user is linked to that
213  * implementation. Otherwise, the \a user is linked to its \a stub.
214  *
215  * \param user \ref optional_api_user to link.
216  * \param api \ref optional_api to link.
217  */
218 static void optional_api_user_relink(struct optional_api_user *user,
219         struct optional_api *api)
220 {
221         if (api->impl && *user->optional_ref != api->impl) {
222                 ast_verb(4, "%s: linking for %s\n", api->symname, user->module);
223                 *user->optional_ref = api->impl;
224         } else if (!api->impl && *user->optional_ref != user->stub) {
225                 ast_verb(4, "%s: stubbing for %s\n", api->symname,
226                         user->module);
227                 *user->optional_ref = user->stub;
228         }
229 }
230
231 /*!
232  * \brief Sets the implementation function pointer for an \a api.
233  *
234  * \param api API to implement/stub out.
235  * \param impl Pointer to implementation function. Can be 0 to remove
236  *             implementation.
237  */
238 static void optional_api_set_impl(struct optional_api *api,
239         ast_optional_fn impl)
240 {
241         size_t i;
242
243         api->impl = impl;
244
245         /* re-link all users */
246         for (i = 0; i < api->users_len; ++i) {
247                 optional_api_user_relink(api->users[i], api);
248         }
249 }
250
251 void ast_optional_api_provide(const char *symname, ast_optional_fn impl)
252 {
253         struct optional_api *api;
254
255         ast_verb(4, "%s: providing\n", symname);
256
257         api = get_api(symname);
258         if (!api) {
259                 ast_log(LOG_ERROR, "%s: Allocation failed\n", symname);
260                 ast_do_crash();
261                 return;
262         }
263
264         optional_api_set_impl(api, impl);
265 }
266
267 void ast_optional_api_unprovide(const char *symname, ast_optional_fn impl)
268 {
269         struct optional_api *api;
270
271         ast_verb(4, "%s: un-providing\n", symname);
272
273         api = get_api(symname);
274         if (!api) {
275                 ast_log(LOG_ERROR, "%s: Could not find api\n", symname);
276                 ast_do_crash();
277                 return;
278         }
279
280         optional_api_set_impl(api, 0);
281 }
282
283 void ast_optional_api_use(const char *symname, ast_optional_fn *optional_ref,
284         ast_optional_fn stub, const char *module)
285 {
286         struct optional_api_user *user;
287         struct optional_api *api;
288
289
290         api = get_api(symname);
291         if (!api) {
292                 ast_log(LOG_ERROR, "%s: Allocation failed\n", symname);
293                 ast_do_crash();
294                 return;
295         }
296
297         user = optional_api_user_create(optional_ref, stub, module);
298         if (!user) {
299                 ast_log(LOG_ERROR, "%s: Allocation failed\n", symname);
300                 ast_do_crash();
301                 return;
302         }
303
304         /* Add user to the API */
305         if (api->users_len + 1 > api->users_maxlen) {
306                 size_t new_maxlen = api->users_maxlen ? 2 * api->users_maxlen : 1;
307                 struct optional_api_user **new_list;
308
309                 new_list = ast_std_realloc(api->users, new_maxlen * sizeof(*new_list));
310                 if (!new_list) {
311                         optional_api_user_destroy(user);
312                         ast_log(LOG_ERROR, "Failed to allocate api list\n");
313                         ast_do_crash();
314                         return;
315                 }
316
317                 api->users_maxlen = new_maxlen;
318                 api->users = new_list;
319         }
320
321         api->users[api->users_len++] = user;
322
323         optional_api_user_relink(user, api);
324 }
325
326 void ast_optional_api_unuse(const char *symname, ast_optional_fn *optional_ref,
327         const char *module)
328 {
329         struct optional_api *api;
330         size_t i;
331
332         api = get_api(symname);
333         if (!api) {
334                 ast_log(LOG_ERROR, "%s: Could not find api\n", symname);
335                 ast_do_crash();
336                 return;
337         }
338
339         for (i = 0; i < api->users_len; ++i) {
340                 struct optional_api_user *user = api->users[i];
341
342                 if (user->optional_ref == optional_ref) {
343                         if (*user->optional_ref != user->stub) {
344                                 ast_verb(4, "%s: stubbing for %s\n", symname,
345                                         module);
346                                 *user->optional_ref = user->stub;
347                         }
348
349                         /* Remove from the list */
350                         api->users[i] = api->users[--api->users_len];
351
352                         optional_api_user_destroy(user);
353                         return;
354                 }
355         }
356
357         ast_log(LOG_ERROR, "%s: Could not find user %s\n", symname, module);
358 }
359
360 #endif /* defined(OPTIONAL_API) */