d681ebb5abf51f43d2eb4160f0aaccc05ee272b3
[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. \ref ast_sorcery_open will automatically call \ref ast_sorcery_apply_config to allow
43  * for configuration of objects using the same category name as the module that is opening the
44  * sorcery instance. Direct calls to \ref ast_sorcery_apply_config should only be performed if a
45  * module wishes to allow for additional configuration sections in sorcery.conf to be used.
46  * If the storage of the object types are such that a default wizard can be used this can
47  * be applied using the \ref ast_sorcery_apply_default API call. Note that the default mappings will not
48  * override configured mappings. They are only used in the case where no configured mapping exists.
49  *
50  * Configuring object mappings implicitly creates a basic version of an object type. The object type
51  * must be fully registered, however, using the \ref ast_sorcery_object_register API call before any
52  * objects of the type can be allocated, created, or retrieved.
53  *
54  * Once the object type itself has been fully registered the individual fields within the object must
55  * be registered using the \ref ast_sorcery_object_field_register API call. Note that not all fields *need*
56  * be registered. Only fields that should be accessible using the sorcery API have to be registered.
57  *
58  * \par Creating Objects
59  *
60  * Before an object can be created within the sorcery API it must first be allocated using the
61  * \ref ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific
62  * details, and applies default values to the object. A unique identifier can optionally be specified
63  * when allocating an object. If it is not provided one will be automatically generated. Allocating
64  * an object does not create it within any object storage mechanisms that are configured for the
65  * object type. Creation must explicitly be done using the \ref ast_sorcery_create API call. This API call
66  * passes the object to each configured object storage mechanism for the object type until one
67  * successfully persists the object.
68  *
69  * \par Retrieving Objects
70  *
71  * To retrieve a single object using its unique identifier the \ref ast_sorcery_retrieve_by_id API call
72  * can be used.
73  *
74  * To retrieve potentially multiple objects using specific fields the \ref ast_sorcery_retrieve_by_fields
75  * API call can be used. The behavior of this API call is controlled using different flags. If the
76  * AST_RETRIEVE_FLAG_MULTIPLE flag is used a container will be returned which contains all matching objects.
77  * To retrieve all objects the AST_RETRIEVE_FLAG_ALL flag can be specified. Note that when specifying this flag
78  * you do not need to pass any fields.
79  *
80  * Both API calls return shared objects. Modification of the object can not occur until it has been copied.
81  *
82  * \par Updating Objects
83  *
84  * As retrieved objects may be shared the first step to updating the object with new details is creating a
85  * copy using the \ref ast_sorcery_copy API call. This will return a new object which is specific to the caller.
86  * Any field within the object may be modified as needed. Once changes are done the changes can be committed
87  * using the \ref ast_sorcery_update API call. Note that as the copied object is specific to the caller it must
88  * be unreferenced after use.
89  *
90  * \par Deleting Objects
91  *
92  * To delete an object simply call the \ref ast_sorcery_delete API call with an object retrieved using the
93  * ast_sorcery_retrieve_by_* API calls or a copy returned from \ref ast_sorcery_copy.
94  */
95
96 #ifndef _ASTERISK_SORCERY_H
97 #define _ASTERISK_SORCERY_H
98
99 #if defined(__cplusplus) || defined(c_plusplus)
100 extern "C" {
101 #endif
102
103 #include "asterisk/config_options.h"
104 #include "asterisk/uuid.h"
105
106 /*! \brief Maximum size of an object type */
107 #define MAX_OBJECT_TYPE 64
108
109 /*! \brief Maximum length of an object field name */
110 #define MAX_OBJECT_FIELD 128
111
112 /*!
113  * \brief Retrieval flags
114  */
115 enum ast_sorcery_retrieve_flags {
116         /*! \brief Default retrieval flags */
117         AST_RETRIEVE_FLAG_DEFAULT = 0,
118
119         /*! \brief Return all matching objects */
120         AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
121
122         /*! \brief Perform no matching, return all objects */
123         AST_RETRIEVE_FLAG_ALL = (1 << 1),
124 };
125
126 /*!
127  * \brief Field handler flags
128  */
129 enum ast_sorcery_field_handler_flags {
130         /*! \brief Try both handlers, string first */
131         AST_HANDLER_PREFER_STRING,
132
133         /*! \brief Try both handlers, list first */
134         AST_HANDLER_PREFER_LIST,
135
136         /*! \brief Use string handler only */
137         AST_HANDLER_ONLY_STRING,
138
139         /*! \brief Use list handler only */
140         AST_HANDLER_ONLY_LIST,
141 };
142
143
144 /*! \brief Forward declaration for the sorcery main structure and wizard structure */
145 struct ast_sorcery;
146 struct ast_sorcery_wizard;
147
148 /*!
149  * \brief A callback function for translating a value into a string
150  *
151  * \param obj Object to get value from
152  * \param args Where the field is
153  * \param buf Pointer to the buffer that the handler has created which contains the field value
154  *
155  * \retval 0 success
156  * \retval -1 failure
157  */
158 typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
159
160 /*!
161  * \brief A callback function for translating multiple values into an ast_variable list
162  *
163  * \param obj Object to get values from
164  * \param fields Pointer to store the list of fields
165  *
166  * \retval 0 success
167  * \retval -1 failure
168  */
169 typedef int (*sorcery_fields_handler)(const void *obj, struct ast_variable **fields);
170
171 /*!
172  * \brief A callback function for performing a transformation on an object set
173  *
174  * \param set The existing object set
175  *
176  * \retval non-NULL new object set if changed
177  * \retval NULL if no changes present
178  *
179  * \note The returned ast_variable list must be *new*. You can not return the input set.
180  */
181 typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
182
183 /*!
184  * \brief A callback function for when an object set is successfully applied to an object
185  *
186  * \note On a failure return, the state of the object is left undefined. It is a bad
187  * idea to try to use this object.
188  *
189  * \param sorcery Sorcery structure in use
190  * \param obj The object itself
191  * \retval 0 Success
192  * \retval non-zero Failure
193  */
194 typedef int (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
195
196 /*!
197  * \brief A callback function for copying the contents of one object to another
198  *
199  * \param src The source object
200  * \param dst The destination object
201  *
202  * \retval 0 success
203  * \retval -1 failure
204  */
205 typedef int (*sorcery_copy_handler)(const void *src, void *dst);
206
207 /*!
208  * \brief A callback function for generating a changeset between two objects
209  *
210  * \param original The original object
211  * \param modified The modified object
212  * \param changes The changeset
213  *
214  * \param 0 success
215  * \param -1 failure
216  */
217 typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
218
219 /*! \brief Interface for the global sorcery observer */
220 struct ast_sorcery_global_observer {
221         /*! \brief Callback after an instance is created */
222         void (*instance_created)(const char *name, struct ast_sorcery *sorcery);
223
224         /*! \brief Callback after an wizard is registered */
225         void (*wizard_registered)(const char *name,
226                 const struct ast_sorcery_wizard *wizard);
227
228         /*! \brief Callback before an instance is destroyed */
229         void (*instance_destroying)(const char *name, struct ast_sorcery *sorcery);
230
231         /*! \brief Callback before a wizard is unregistered */
232         void (*wizard_unregistering)(const char *name,
233                 const struct ast_sorcery_wizard *wizard);
234 };
235
236 /*! \brief Interface for the sorcery instance observer */
237 struct ast_sorcery_instance_observer {
238         /*! \brief Callback before instance is loaded/reloaded */
239         void (*instance_loading)(const char *name, const struct ast_sorcery *sorcery,
240                 int reloaded);
241
242         /*! \brief Callback after instance is loaded/reloaded */
243         void (*instance_loaded)(const char *name, const struct ast_sorcery *sorcery,
244                 int reloaded);
245
246         /*! \brief Callback after a wizard is mapped to an object_type */
247         void (*wizard_mapped)(const char *name, struct ast_sorcery *sorcery,
248                 const char *object_type, struct ast_sorcery_wizard *wizard,
249                 const char *wizard_args, void *wizard_data);
250
251         /*! \brief Callback after any object_type is registered */
252         void (*object_type_registered)(const char *name, struct ast_sorcery *sorcery,
253                 const char *object_type);
254
255         /*! \brief Callback before any object_type is loaded/reloaded */
256         void (*object_type_loading)(const char *name, const struct ast_sorcery *sorcery,
257                 const char *object_type, int reloaded);
258
259         /*! \brief Callback after any object_type is loaded/reloaded */
260         void (*object_type_loaded)(const char *name, const struct ast_sorcery *sorcery,
261                 const char *object_type, int reloaded);
262 };
263
264 /*! \brief Interface for the sorcery wizard observer */
265 struct ast_sorcery_wizard_observer {
266         /*! \brief Callback before a wizard is loaded/reloaded for any type */
267         void (*wizard_loading)(const char *name, const struct ast_sorcery_wizard *wizard,
268                 const char *object_type, int reloaded);
269
270         /*! \brief Callback after a wizard is loaded/reloaded for any type */
271         void (*wizard_loaded)(const char *name, const struct ast_sorcery_wizard *wizard,
272                 const char *object_type, int reloaded);
273 };
274
275 /*! \brief Interface for a sorcery wizard */
276 struct ast_sorcery_wizard {
277         /*! \brief Name of the wizard */
278         const char *name;
279
280         /*! \brief Pointer to the Asterisk module this wizard is implemented by */
281         struct ast_module *module;
282
283         /*! \brief Callback for opening a wizard */
284         void *(*open)(const char *data);
285
286         /*! \brief Optional callback for loading persistent objects */
287         void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
288
289         /*! \brief Optional callback for reloading persistent objects */
290         void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
291
292         /*! \brief Callback for creating an object */
293         int (*create)(const struct ast_sorcery *sorcery, void *data, void *object);
294
295         /*! \brief Callback for retrieving an object using an id */
296         void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
297
298         /*! \brief Callback for retrieving multiple objects using a regex on their id */
299         void (*retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
300
301         /*! \brief Optional callback for retrieving an object using fields */
302         void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
303
304         /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
305         void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
306
307         /*! \brief Callback for updating an object */
308         int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
309
310         /*! \brief Callback for deleting an object */
311         int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
312
313         /*! \brief Callback for closing a wizard */
314         void (*close)(void *data);
315
316         /* \brief Callback for whether or not the wizard believes the object is stale */
317         int (*is_stale)(const struct ast_sorcery *sorcery, void *data, void *object);
318 };
319
320 /*! \brief Interface for a sorcery object type observer */
321 struct ast_sorcery_observer {
322         /*! \brief Callback for when an object is created */
323         void (*created)(const void *object);
324
325         /*! \brief Callback for when an object is updated */
326         void (*updated)(const void *object);
327
328         /*! \brief Callback for when an object is deleted */
329         void (*deleted)(const void *object);
330
331         /*! \brief Callback for when an object type is loaded/reloaded */
332         void (*loaded)(const char *object_type);
333 };
334
335 /*! \brief Opaque structure for internal sorcery object */
336 struct ast_sorcery_object;
337
338 /*! \brief Structure which contains details about a sorcery object */
339 struct ast_sorcery_object_details {
340         /*! \brief Pointer to internal sorcery object information */
341         struct ast_sorcery_object *object;
342 };
343
344 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
345 #define SORCERY_OBJECT(details)                    \
346 struct {                                           \
347         struct ast_sorcery_object_details details; \
348 }                                                  \
349
350 /*!
351  * \brief Initialize the sorcery API
352  *
353  * \retval 0 success
354  * \retval -1 failure
355  */
356 int ast_sorcery_init(void);
357
358 /*!
359  * \brief Register a sorcery wizard
360  *
361  * \param interface Pointer to a wizard interface
362  * \param module Pointer to the module implementing the interface
363  *
364  * \retval 0 success
365  * \retval -1 failure
366  */
367 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
368
369 /*!
370  * \brief See \ref __ast_sorcery_wizard_register()
371  */
372 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)
373
374 /*!
375  * \brief Unregister a sorcery wizard
376  *
377  * \param interface Pointer to the wizard interface
378  *
379  * \retval 0 success
380  * \retval -1 failure
381  */
382 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
383
384 /*!
385  * \brief Open a new sorcery structure
386  *
387  * \param module The module name (AST_MODULE)
388  *
389  * When called, this will automatically also call __ast_sorcery_apply_config()
390  * with the module name as the configuration section.
391  *
392  * \retval non-NULL success
393  * \retval NULL if allocation failed
394  */
395 struct ast_sorcery *__ast_sorcery_open(const char *module);
396
397 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE)
398
399 /*!
400  * \brief Retrieves an existing sorcery instance by module name
401  *
402  * \param module The module name
403  *
404  * \retval non-NULL success
405  * \retval NULL if no instance was found
406  *
407  * \note The returned instance has its reference count incremented.  The caller
408  * must decrement the count when they're finished with it.
409  *
410  */
411 struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
412
413 enum ast_sorcery_apply_result {
414         /*! Sorcery wizard failed to apply. */
415         AST_SORCERY_APPLY_FAIL = -1,
416         /*! Sorcery wizard applied successfully. */
417         AST_SORCERY_APPLY_SUCCESS = 0,
418         /*! Sorcery wizard has already been applied to the object type. */
419         AST_SORCERY_APPLY_DUPLICATE = 1,
420         /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
421         AST_SORCERY_APPLY_DEFAULT_UNNECESSARY = 2,
422         /*! No sorcery.conf configuration file was found to apply. */
423         AST_SORCERY_APPLY_NO_CONFIGURATION = 3,
424 };
425
426 /*!
427  * \brief Apply configured wizard mappings
428  *
429  * \param sorcery Pointer to a sorcery structure
430  * \param name Name of the category to use within the configuration file, normally the module name
431  * \param module The module name (AST_MODULE)
432  *
433  * This function is called automatically by __ast_sorcery_open() using the module name as the
434  * configuration category. The only reason you should call this function is if your module
435  * wishes to apply configuration from additional sections of sorcery.conf.
436  *
437  * If a configuration section attempts to apply the same sorcery wizard to an object type
438  * more than once, the wizard will only be applied one time.
439  *
440  * \return What happened when attempting to apply the config.
441  */
442 enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery,
443                 const char *name, const char *module);
444
445 #define ast_sorcery_apply_config(sorcery, name) \
446         __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
447
448 /*!
449  * \brief Apply default object wizard mappings
450  *
451  * \param sorcery Pointer to a sorcery structure
452  * \param type Type of object to apply to
453  * \param module The name of the module, typically AST_MODULE
454  * \param name Name of the wizard to use
455  * \param data Data to be passed to wizard
456  *
457  * \return What occurred when applying the default
458  *
459  * \note This should be called *after* applying configuration sourced mappings
460  *
461  * \note Only a single default can exist per object type
462  */
463 enum ast_sorcery_apply_result __ast_sorcery_apply_default(struct ast_sorcery *sorcery,
464                 const char *type, const char *module, const char *name, const char *data);
465
466 #define ast_sorcery_apply_default(sorcery, type, name, data) \
467         __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
468
469
470 /*!
471  * \brief Apply additional object wizard mappings
472  *
473  * \param sorcery Pointer to a sorcery structure
474  * \param type Type of object to apply to
475  * \param module The name of the module, typically AST_MODULE
476  * \param name Name of the wizard to use
477  * \param data Data to be passed to wizard
478  * \param caching Wizard should cache
479  *
480  * \return What occurred when applying the mapping
481  *
482  * \note This should be called *after* applying default mappings
483  */
484 enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping(struct ast_sorcery *sorcery,
485                 const char *type, const char *module, const char *name, const char *data, unsigned int caching);
486
487 /*!
488  * \brief Apply additional object wizard mappings
489  *
490  * \param sorcery Pointer to a sorcery structure
491  * \param type Type of object to apply to
492  * \param module The name of the module, typically AST_MODULE
493  * \param name Name of the wizard to use
494  * \param data Data to be passed to wizard
495  *
496  * \return What occurred when applying the mapping
497  *
498  * \note This should be called *after* applying default mappings
499  */
500 #define ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching) \
501         __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));
502
503
504 /*!
505  * \brief Pre-defined locations to insert at
506  */
507 enum ast_sorcery_wizard_position {
508         AST_SORCERY_WIZARD_POSITION_LAST = -1,
509         AST_SORCERY_WIZARD_POSITION_FIRST = 0,
510 };
511
512 /*!
513  * \brief Insert an additional object wizard mapping at a specific position
514  * in the wizard list
515  *
516  * \param sorcery Pointer to a sorcery structure
517  * \param type Type of object to apply to
518  * \param module The name of the module, typically AST_MODULE
519  * \param name Name of the wizard to use
520  * \param data Data to be passed to wizard
521  * \param caching Wizard should cache
522  * \param position An index to insert to or one of ast_sorcery_wizard_position
523  *
524  * \return What occurred when applying the mapping
525  *
526  * \note This should be called *after* applying default mappings
527  * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count
528  * and iterating over them using ast_sorcery_get_wizard_mapping.
529  *
530  * \since 13.4.0
531  */
532 enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sorcery *sorcery,
533         const char *type, const char *module, const char *name, const char *data,
534         unsigned int caching, int position);
535
536 /*!
537  * \brief Insert an additional object wizard mapping at a specific position
538  * in the wizard list
539  *
540  * \param sorcery Pointer to a sorcery structure
541  * \param type Type of object to apply to
542  * \param module The name of the module, typically AST_MODULE
543  * \param name Name of the wizard to use
544  * \param data Data to be passed to wizard
545  * \param position One of ast_sorcery_wizard_position
546  *
547  * \return What occurred when applying the mapping
548  *
549  * \note This should be called *after* applying default mappings
550  * \since 13.4.0
551  */
552 #define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \
553         __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
554                 (caching), (position))
555
556 /*!
557  * \brief Remove an object wizard mapping
558  *
559  * \param sorcery Pointer to a sorcery structure
560  * \param type Type of object to remove from
561  * \param module The name of the module, typically AST_MODULE
562  * \param name The name of the wizard to remove
563  *
564  * \retval 0 success
565  * \retval -1 failure
566  *
567  * \since 13.4.0
568  */
569 int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery,
570         const char *type, const char *module, const char *name);
571
572 /*!
573  * \brief Remove an object wizard mapping
574  *
575  * \param sorcery Pointer to a sorcery structure
576  * \param type Type of object to remove from
577  * \param name The name of the wizard to remove
578  *
579  * \retval 0 success
580  * \retval -1 failure
581  *
582  * \since 13.4.0
583  */
584 #define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
585         __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
586
587 /*!
588  * \brief Return the number of wizards mapped to an object type
589  *
590  * \param sorcery Pointer to a sorcery structure
591  * \param type Type of object
592  *
593  * \return Number of wizards or -1 for error
594  * \since 13.4.0
595  */
596 int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery,
597         const char *type);
598
599 /*!
600  * \brief By index, return a wizard mapped to an object type
601  *
602  * \param sorcery Pointer to a sorcery structure
603  * \param type Type of object
604  * \param index Index of the wizard
605  * \param wizard A pointer to receive the wizard pointer
606  * \param data A pointer to receive the data pointer
607  *
608  * \retval 0 success
609  * \retval -1 failure
610  *
611  * \warning The wizard will have its reference count bumped so you must
612  * call ao2_cleanup when you're done with it.
613  *
614  * \note The wizard and data returned are valid only for this object type
615  * and only while the wizard is applied to the object type.
616  *
617  * \since 13.4.0
618  */
619 int ast_sorcery_get_wizard_mapping(struct ast_sorcery *sorcery,
620         const char *type, int index, struct ast_sorcery_wizard **wizard, void **data);
621
622 /*!
623  * \brief Unregister an object type
624  *
625  * \param sorcery Pointer to a sorcery structure
626  * \param type Type of object
627  *
628  * \retval 0 success
629  * \retval -1 failure
630  */
631 int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type);
632
633 /*!
634  * \brief Register an object type
635  *
636  * \param sorcery Pointer to a sorcery structure
637  * \param type Type of object
638  * \param hidden All objects of this type are internal and should not be manipulated by users
639  * \param reloadable All objects of this type are reloadable
640  * \param alloc Required object allocation callback
641  * \param transform Optional transformation callback
642  * \param apply Optional object set apply callback
643  *
644  * \note In general, this function should not be used directly. One of the various
645  * macro'd versions should be used instead.
646  *
647  * \retval 0 success
648  * \retval -1 failure
649  */
650 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);
651
652 /*!
653  * \brief Register an object type
654  *
655  * \param sorcery Pointer to a sorcery structure
656  * \param type Type of object
657  * \param alloc Required object allocation callback
658  * \param transform Optional transformation callback
659  * \param apply Optional object set apply callback
660  *
661  * \retval 0 success
662  * \retval -1 failure
663  */
664 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
665         __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
666
667 /*!
668  * \brief Register an object type that is not reloadable
669  *
670  * \param sorcery Pointer to a sorcery structure
671  * \param type Type of object
672  * \param alloc Required object allocation callback
673  * \param transform Optional transformation callback
674  * \param apply Optional object set apply callback
675  *
676  * \retval 0 success
677  * \retval -1 failure
678  */
679 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
680         __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
681
682 /*!
683  * \brief Register an internal, hidden object type
684  *
685  * \param sorcery Pointer to a sorcery structure
686  * \param type Type of object
687  * \param alloc Required object allocation callback
688  * \param transform Optional transformation callback
689  * \param apply Optional object set apply callback
690  *
691  * \retval 0 success
692  * \retval -1 failure
693  */
694 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
695         __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
696
697 /*!
698  * \brief Set the copy handler for an object type
699  *
700  * \param sorcery Pointer to a sorcery structure
701  * \param type Type of object
702  * \param copy Copy handler
703  */
704 void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
705
706 /*!
707  * \brief Set the diff handler for an object type
708  *
709  * \param sorcery Pointer to a sorcery structure
710  * \param type Type of object
711  * \param diff Diff handler
712  */
713 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
714
715 /*!
716  * \brief Register a regex for multiple fields within an object
717  *
718  * \param sorcery Pointer to a sorcery structure
719  * \param type Type of object
720  * \param regex A regular expression pattern for the fields
721  * \param config_handler A custom handler for translating the string representation of the fields
722  * \param sorcery_handler A custom handler for translating the native representation of the fields
723  *
724  * \retval 0 success
725  * \retval -1 failure
726  */
727 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
728                                                                            sorcery_fields_handler sorcery_handler);
729
730 /*!
731  * \brief Register a field within an object
732  *
733  * \param sorcery Pointer to a sorcery structure
734  * \param type Type of object
735  * \param name Name of the field
736  * \param default_val Default value of the field
737  * \param config_handler A custom handler for translating the string representation of the fields
738  * \param sorcery_handler A custom handler for translating the native representation of the fields
739  * \param multiple_handler A custom handler for translating the native representation of the fields
740  * \param opt_type Option type
741  * \param flags Option type specific flags
742  * \param no_doc Field should not be documented
743  * \param alias Interpret and apply field value only
744  *
745  * \retval 0 success
746  * \retval -1 failure
747  */
748 int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type,
749         const char *name, const char *default_val, enum aco_option_type opt_type,
750         aco_option_handler config_handler, sorcery_field_handler sorcery_handler,
751         sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc,
752         unsigned int alias, size_t argc, ...);
753
754 /*!
755  * \brief Register a field within an object
756  *
757  * \param sorcery Pointer to a sorcery structure
758  * \param type Type of object
759  * \param name Name of the field
760  * \param default_val Default value of the field
761  * \param opt_type Option type
762  * \param flags Option type specific flags
763  *
764  * \retval 0 success
765  * \retval -1 failure
766  */
767 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
768     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
769
770 /*!
771  * \brief Register a field within an object as an alias
772  *
773  * \param sorcery Pointer to a sorcery structure
774  * \param type Type of object
775  * \param name Name of the field
776  * \param default_val Default value of the field
777  * \param opt_type Option type
778  * \param flags Option type specific flags
779  *
780  * \retval 0 success
781  * \retval -1 failure
782  */
783 #define ast_sorcery_object_field_register_alias(sorcery, type, name, default_val, opt_type, flags, ...) \
784     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
785
786 /*!
787  * \brief Register a field within an object without documentation
788  *
789  * \param sorcery Pointer to a sorcery structure
790  * \param type Type of object
791  * \param name Name of the field
792  * \param default_val Default value of the field
793  * \param opt_type Option type
794  * \param flags Option type specific flags
795  *
796  * \retval 0 success
797  * \retval -1 failure
798  */
799 #define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
800     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
801
802 /*!
803  * \brief Register a field within an object with custom handlers
804  *
805  * \param sorcery Pointer to a sorcery structure
806  * \param type Type of object
807  * \param name Name of the field
808  * \param default_val Default value of the field
809  * \param config_handler Custom configuration handler
810  * \param sorcery_handler Custom sorcery handler
811  * \param multiple_handler Custom multiple handler
812  * \param flags Option type specific flags
813  *
814  * \retval 0 success
815  * \retval -1 failure
816  */
817 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
818     __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__);
819
820 /*!
821  * \brief Register a field within an object with custom handlers as an alias
822  *
823  * \param sorcery Pointer to a sorcery structure
824  * \param type Type of object
825  * \param name Name of the field
826  * \param default_val Default value of the field
827  * \param config_handler Custom configuration handler
828  * \param sorcery_handler Custom sorcery handler
829  * \param flags Option type specific flags
830  *
831  * \retval 0 success
832  * \retval -1 failure
833  */
834 #define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
835     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
836
837 /*!
838  * \brief Register a field within an object with custom handlers without documentation
839  *
840  * \param sorcery Pointer to a sorcery structure
841  * \param type Type of object
842  * \param name Name of the field
843  * \param default_val Default value of the field
844  * \param config_handler Custom configuration handler
845  * \param sorcery_handler Custom sorcery handler
846  * \param multiple_handler Custom multiple handler
847  * \param flags Option type specific flags
848  *
849  * \retval 0 success
850  * \retval -1 failure
851  */
852 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
853     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, multiple_handler, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
854
855 /*!
856  * \brief Inform any wizards to load persistent objects
857  *
858  * \param sorcery Pointer to a sorcery structure
859  */
860 void ast_sorcery_load(const struct ast_sorcery *sorcery);
861
862 /*!
863  * \brief Inform any wizards of a specific object type to load persistent objects
864  *
865  * \param sorcery Pointer to a sorcery structure
866  * \param type Name of the object type to load
867  */
868 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
869
870 /*!
871  * \brief Inform any wizards to reload persistent objects
872  *
873  * \param sorcery Pointer to a sorcery structure
874  */
875 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
876
877 /*!
878  * \brief Inform any wizards of a specific object type to reload persistent objects
879  *
880  * \param sorcery Pointer to a sorcery structure
881  * \param type Name of the object type to reload
882  */
883 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
884
885 /*!
886  * \brief Increase the reference count of a sorcery structure
887  *
888  * \param sorcery Pointer to a sorcery structure
889  */
890 void ast_sorcery_ref(struct ast_sorcery *sorcery);
891
892
893 /*!
894  * \brief Create an object set (KVP list) for an object
895  *
896  * \param sorcery Pointer to a sorcery structure
897  * \param object Pointer to a sorcery object
898  * \param flags Flags indicating which handler to use and in what order.
899  *
900  * \retval non-NULL success
901  * \retval NULL if error occurred
902  *
903  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
904  */
905 struct ast_variable *ast_sorcery_objectset_create2(const struct ast_sorcery *sorcery,
906         const void *object, enum ast_sorcery_field_handler_flags flags);
907
908 /*!
909  * \brief Create an object set (KVP list) for an object
910  *
911  * \param sorcery Pointer to a sorcery structure
912  * \param object Pointer to a sorcery object
913  *
914  * \retval non-NULL success
915  * \retval NULL if error occurred
916  *
917  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
918  *
919  * \note This function attempts to use a field's sorcery_fields_handler first and if that
920  * doesn't exist or fails, a field's sorcery_field_handler is used.  The difference is
921  * that the former may return multiple list entries for the same field and the latter will only
922  * return 1.  It's up to the field itself to determine what the appropriate content is.
923  */
924 #define ast_sorcery_objectset_create(sorcery, object) \
925         ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
926
927 /*!
928  * \brief Create an object set in JSON format for an object
929  *
930  * \param sorcery Pointer to a sorcery structure
931  * \param object Pointer to a sorcery object
932  *
933  * \retval non-NULL success
934  * \retval NULL if error occurred
935  *
936  * \note The returned ast_json object must be unreferenced using ast_json_unref
937  */
938 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
939
940 /*!
941  * \brief Apply an object set (KVP list) to an object
942  *
943  * \param sorcery Pointer to a sorcery structure
944  * \param object Pointer to a sorcery object
945  * \param objectset Object set itself
946  *
947  * \retval 0 success
948  * \retval -1 failure
949  *
950  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
951  *       applied object set.
952  */
953 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
954
955 /*!
956  * \brief Create a changeset given two object sets
957  *
958  * \param original Original object set
959  * \param modified Modified object set
960  * \param changes Pointer to hold any changes between the object sets
961  *
962  * \retval 0 success
963  * \retval -1 failure
964  *
965  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
966  */
967 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
968
969 /*!
970  * \brief Allocate a generic sorcery capable object
971  *
972  * \param size Size of the object
973  * \param destructor Optional destructor function
974  *
975  * \retval non-NULL success
976  * \retval NULL failure
977  */
978 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
979
980 /*!
981  * \brief Allocate an object
982  *
983  * \param sorcery Pointer to a sorcery structure
984  * \param type Type of object to allocate
985  * \param id Optional unique identifier, if none is provided one will be generated
986  *
987  * \retval non-NULL success
988  * \retval NULL failure
989  */
990 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
991
992 /*!
993  * \brief Create a copy of an object
994  *
995  * \param sorcery Pointer to a sorcery structure
996  * \param object Existing object
997  *
998  * \retval non-NULL success
999  * \retval NULL failure
1000  */
1001 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
1002
1003 /*!
1004  * \brief Create a changeset of two objects
1005  *
1006  * \param sorcery Pointer to a sorcery structure
1007  * \param original Original object
1008  * \param modified Modified object
1009  * \param changes Pointer which will be populated with changes if any exist
1010  *
1011  * \retval 0 success
1012  * \retval -1 failure
1013  *
1014  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1015  *
1016  * \note While the objects must be of the same type they do not have to be the same object
1017  */
1018 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
1019
1020 /*!
1021  * \brief Add a global observer to sorcery
1022  *
1023  * \param callbacks Implementation of the global observer interface
1024  *
1025  * \retval 0 success
1026  * \retval -1 failure
1027  *
1028  * \note You must be ready to accept observer invocations before this function is called
1029  */
1030 int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks);
1031
1032 /*!
1033  * \brief Remove a global observer from sorcery.
1034  *
1035  * A global observer is notified...
1036  * After a new wizard is registered.
1037  * After a new sorcery instance is opened.
1038  * Before an instance is destroyed.
1039  * Before a wizard is unregistered.
1040  *
1041  * \param callbacks Implementation of the global observer interface
1042  */
1043 void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks);
1044
1045 /*!
1046  * \brief Add an observer to a sorcery instance
1047  *
1048  * \param sorcery Pointer to a sorcery structure
1049  * \param callbacks Implementation of the instance observer interface
1050  *
1051  * An instance observer is notified...
1052  * Before an instance is loaded or reloaded.
1053  * After an instance is loaded or reloaded.
1054  * After a wizard is mapped to an object type.
1055  * After an object type is registered.
1056  * Before an object type is loaded or reloaded.
1057  * After an object type is loaded or reloaded.
1058  *
1059  * \retval 0 success
1060  * \retval -1 failure
1061  *
1062  * \note You must be ready to accept observer invocations before this function is called
1063  */
1064 int ast_sorcery_instance_observer_add(struct ast_sorcery *sorcery,
1065         const struct ast_sorcery_instance_observer *callbacks);
1066
1067 /*!
1068  * \brief Remove an observer from a sorcery instance
1069  *
1070  * \param sorcery Pointer to a sorcery structure
1071  * \param callbacks Implementation of the instance observer interface
1072  */
1073 void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery,
1074         const struct ast_sorcery_instance_observer *callbacks);
1075
1076 /*!
1077  * \brief Add an observer to a sorcery wizard
1078  *
1079  * \param sorcery Pointer to a previously registered wizard structure
1080  * \param callbacks Implementation of the wizard observer interface
1081  *
1082  * A wizard observer is notified...
1083  * Before a wizard is loaded or reloaded.
1084  * After a wizard is loaded or reloaded.
1085  *
1086  * \retval 0 success
1087  * \retval -1 failure
1088  *
1089  * \note You must be ready to accept observer invocations before this function is called
1090  */
1091 int ast_sorcery_wizard_observer_add(struct ast_sorcery_wizard *wizard,
1092         const struct ast_sorcery_wizard_observer *callbacks);
1093
1094 /*!
1095  * \brief Remove an observer from a sorcery wizard.
1096  *
1097  * \param sorcery Pointer to a sorcery structure
1098  * \param callbacks Implementation of the wizard observer interface
1099  */
1100 void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *wizard,
1101         const struct ast_sorcery_wizard_observer *callbacks);
1102
1103 /*!
1104  * \brief Add an observer to a specific object type
1105  *
1106  * \param sorcery Pointer to a sorcery structure
1107  * \param type Type of object that should be observed
1108  * \param callbacks Implementation of the observer interface
1109  *
1110  * \retval 0 success
1111  * \retval -1 failure
1112  *
1113  * \note You must be ready to accept observer invocations before this function is called
1114  */
1115 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1116
1117 /*!
1118  * \brief Remove an observer from a specific object type
1119  *
1120  * \param sorcery Pointer to a sorcery structure
1121  * \param type Type of object that should no longer be observed
1122  * \param callbacks Implementation of the observer interface
1123  *
1124  * \retval 0 success
1125  * \retval -1 failure
1126  */
1127 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1128
1129 /*!
1130  * \brief Create and potentially persist an object using an available wizard
1131  *
1132  * \param sorcery Pointer to a sorcery structure
1133  * \param object Pointer to a sorcery object
1134  *
1135  * \retval 0 success
1136  * \retval -1 failure
1137  */
1138 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
1139
1140 /*!
1141  * \brief Retrieve an object using its unique identifier
1142  *
1143  * \param sorcery Pointer to a sorcery structure
1144  * \param type Type of object to retrieve
1145  * \param id Unique object identifier
1146  *
1147  * \retval non-NULL if found
1148  * \retval NULL if not found
1149  */
1150 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
1151
1152 /*!
1153  * \brief Retrieve an object or multiple objects using specific fields
1154  *
1155  * \param sorcery Pointer to a sorcery structure
1156  * \param type Type of object to retrieve
1157  * \param flags Flags to control behavior
1158  * \param fields Optional object fields and values to match against
1159  *
1160  * \retval non-NULL if found
1161  * \retval NULL if not found
1162  *
1163  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
1164  *       ao2_container that must be unreferenced after use.
1165  *
1166  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
1167  *       of the given type.
1168  */
1169 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
1170
1171 /*!
1172  * \brief Retrieve multiple objects using a regular expression on their id
1173  *
1174  * \param sorcery Pointer to a sorcery structure
1175  * \param type Type of object to retrieve
1176  * \param regex Regular expression
1177  *
1178  * \retval non-NULL if error occurs
1179  * \retval NULL success
1180  *
1181  * \note The provided regex is treated as extended case sensitive.
1182  */
1183 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
1184
1185 /*!
1186  * \brief Update an object
1187  *
1188  * \param sorcery Pointer to a sorcery structure
1189  * \param object Pointer to a sorcery object
1190  *
1191  * \retval 0 success
1192  * \retval -1 failure
1193  */
1194 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
1195
1196 /*!
1197  * \brief Delete an object
1198  *
1199  * \param sorcery Pointer to a sorcery structure
1200  * \param object Pointer to a sorcery object
1201  *
1202  * \retval 0 success
1203  * \retval -1 failure
1204  */
1205 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
1206
1207 /*!
1208  * \brief Determine if a sorcery object is stale with respect to its backing datastore
1209  * \since 14.0.0
1210  *
1211  * This function will query the wizard(s) backing the particular sorcery object to
1212  * determine if the in-memory object is now stale. No action is taken to update
1213  * the object. Callers of this function may use one of the ast_sorcery_retrieve
1214  * functions to obtain a new instance of the object if desired.
1215  *
1216  * \retval 0 the object is not stale
1217  * \retval 1 the object is stale
1218  */
1219 int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
1220
1221 /*!
1222  * \brief Decrease the reference count of a sorcery structure
1223  *
1224  * \param sorcery Pointer to a sorcery structure
1225  */
1226 void ast_sorcery_unref(struct ast_sorcery *sorcery);
1227
1228 /*!
1229  * \brief Get the unique identifier of a sorcery object
1230  *
1231  * \param object Pointer to a sorcery object
1232  *
1233  * \retval unique identifier
1234  */
1235 const char *ast_sorcery_object_get_id(const void *object);
1236
1237 /*!
1238  * \since 14.0.0
1239  * \brief Get when the socery object was created
1240  *
1241  * \param object Pointer to a sorcery object
1242  *
1243  * \retval The time when the object was created
1244  */
1245 const struct timeval ast_sorcery_object_get_created(const void *object);
1246
1247 /*!
1248  * \brief Get the type of a sorcery object
1249  *
1250  * \param object Pointer to a sorcery object
1251  *
1252  * \retval type of object
1253  */
1254 const char *ast_sorcery_object_get_type(const void *object);
1255
1256 /*!
1257  * \brief Get an extended field value from a sorcery object
1258  *
1259  * \param object Pointer to a sorcery object
1260  * \param name Name of the extended field value
1261  *
1262  * \retval non-NULL if found
1263  * \retval NULL if not found
1264  *
1265  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
1266  */
1267 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
1268
1269 /*!
1270  * \brief Set an extended field value on a sorcery object
1271  *
1272  * \param object Pointer to a sorcery object
1273  * \param name Name of the extended field
1274  * \param value Value of the extended field
1275  *
1276  * \retval 0 success
1277  * \retval -1 failure
1278  *
1279  * \note The field name MUST begin with '@' to indicate it is an extended field.
1280  * \note If the extended field already exists it will be overwritten with the new value.
1281  */
1282 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
1283
1284 /*!
1285  * \brief ao2 object comparator based on sorcery id.
1286  */
1287 int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
1288
1289 /*!
1290  * \brief ao2 object sorter based on sorcery id.
1291  */
1292 int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
1293
1294 /*!
1295  * \brief ao2 object hasher based on sorcery id.
1296  */
1297 int ast_sorcery_object_id_hash(const void *obj, int flags);
1298
1299 /*!
1300  * \brief Get the sorcery object type given a type name.
1301  *
1302  * \param sorcery The sorcery from which to retrieve the object type
1303  * \param type The type name
1304  */
1305 struct ast_sorcery_object_type *ast_sorcery_get_object_type(const struct ast_sorcery *sorcery,
1306                 const char *type);
1307
1308 /*!
1309  * \brief Determine if a particular object field has been registered with sorcery
1310  *
1311  * \param object_type The object type to check against
1312  * \param field_name The name of the field to check
1313  *
1314  * \retval 0 The field is not registered for this sorcery type
1315  * \retval 1 The field is registered for this sorcery type
1316  */
1317 int ast_sorcery_is_object_field_registered(const struct ast_sorcery_object_type *object_type,
1318                 const char *field_name);
1319
1320 /*!
1321  * \brief Get the module that has opened the provided sorcery instance.
1322  *
1323  * \param sorcery The sorcery instance
1324  *
1325  * \return The module
1326  */
1327 const char *ast_sorcery_get_module(const struct ast_sorcery *sorcery);
1328
1329 #if defined(__cplusplus) || defined(c_plusplus)
1330 }
1331 #endif
1332
1333 #endif /* _ASTERISK_SORCERY_H */