Asterisk - The Open Source Telephony Project GIT-master-25686a5
sorcery.h
Go to the documentation of this file.
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)
100extern "C" {
101#endif
102
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 */
116 /*! \brief Default retrieval flags */
118
119 /*! \brief Return all matching objects */
121
122 /*! \brief Perform no matching, return all objects */
124};
125
126/*!
127 * \brief Field handler flags
128 */
130 /*! \brief Try both handlers, string first */
132
133 /*! \brief Try both handlers, list first */
135
136 /*! \brief Use string handler only */
138
139 /*! \brief Use list handler only */
141};
142
143
144/*! \brief Forward declaration for the sorcery main structure and wizard structure */
145struct ast_sorcery;
146struct 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 */
158typedef 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 */
169typedef 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 */
181typedef 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 */
194typedef 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 */
205typedef 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 * \retval 0 success
215 * \retval -1 failure
216 */
217typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
218
219/*! \brief Interface for the global sorcery 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 */
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 */
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 */
277 /*! \brief Name of the wizard */
278 const char *name;
279
280 /*! \brief Pointer to the Asterisk module this wizard is implemented by */
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 multiple objects by matching their id with a prefix */
302 void (*retrieve_prefix)(const struct ast_sorcery *sorcery,
303 void *data,
304 const char *type,
305 struct ao2_container *objects,
306 const char *prefix,
307 const size_t prefix_len);
308
309 /*! \brief Optional callback for retrieving an object using fields */
310 void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
311
312 /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
313 void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
314
315 /*! \brief Callback for updating an object */
316 int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
317
318 /*! \brief Callback for deleting an object */
319 int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
320
321 /*! \brief Callback for closing a wizard */
322 void (*close)(void *data);
323
324 /*! \brief Callback for whether or not the wizard believes the object is stale */
325 int (*is_stale)(const struct ast_sorcery *sorcery, void *data, void *object);
326
327 /*! \brief Optional callback for forcing a reload to occur, even if wizard has determined no changes */
328 void (*force_reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
329};
330
331/*! \brief Interface for a sorcery object type observer */
333 /*! \brief Callback for when an object is created */
334 void (*created)(const void *object);
335
336 /*! \brief Callback for when an object is updated */
337 void (*updated)(const void *object);
338
339 /*! \brief Callback for when an object is deleted */
340 void (*deleted)(const void *object);
341
342 /*! \brief Callback for when an object type is loaded/reloaded */
343 void (*loaded)(const char *object_type);
344};
345
346/*! \brief Opaque structure for internal sorcery object */
347struct ast_sorcery_object;
348
349/*! \brief Structure which contains details about a sorcery object */
351 /*! \brief Pointer to internal sorcery object information */
353};
354
355/*! \brief Macro which must be used at the beginning of each sorcery capable object */
356#define SORCERY_OBJECT(details) \
357struct { \
358 struct ast_sorcery_object_details details; \
359} \
360
361/*!
362 * \brief Initialize the sorcery API
363 *
364 * \retval 0 success
365 * \retval -1 failure
366 */
367int ast_sorcery_init(void);
368
369/*!
370 * \brief Register a sorcery wizard
371 *
372 * \param interface Pointer to a wizard interface
373 * \param module Pointer to the module implementing the interface
374 *
375 * \retval 0 success
376 * \retval -1 failure
377 */
378int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
379
380/*!
381 * \brief See \ref __ast_sorcery_wizard_register()
382 */
383#define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)
384
385/*!
386 * \brief Unregister a sorcery wizard
387 *
388 * \param interface Pointer to the wizard interface
389 *
390 * \retval 0 success
391 * \retval -1 failure
392 */
393int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
394
395/*!
396 * \brief Open a new sorcery structure
397 *
398 * \param module The module name (AST_MODULE)
399 *
400 * When called, this will automatically also call __ast_sorcery_apply_config()
401 * with the module name as the configuration section.
402 *
403 * \retval non-NULL success
404 * \retval NULL if allocation failed
405 */
406#define ast_sorcery_open() __ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)
407struct ast_sorcery *__ast_sorcery_open(const char *module, const char *file, int line, const char *func);
408
409/*!
410 * \brief Retrieves an existing sorcery instance by module name
411 *
412 * \param module_name The module name
413 *
414 * \retval non-NULL success
415 * \retval NULL if no instance was found
416 *
417 * \note The returned instance has its reference count incremented. The caller
418 * must decrement the count when they're finished with it.
419 *
420 */
422
424 /*! Sorcery wizard failed to apply. */
426 /*! Sorcery wizard applied successfully. */
428 /*! Sorcery wizard has already been applied to the object type. */
430 /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
432 /*! No sorcery.conf configuration file was found to apply. */
434};
435
436/*!
437 * \brief Apply configured wizard mappings
438 *
439 * \param sorcery Pointer to a sorcery structure
440 * \param name Name of the category to use within the configuration file, normally the module name
441 * \param module The module name (AST_MODULE)
442 *
443 * This function is called automatically by __ast_sorcery_open() using the module name as the
444 * configuration category. The only reason you should call this function is if your module
445 * wishes to apply configuration from additional sections of sorcery.conf.
446 *
447 * If a configuration section attempts to apply the same sorcery wizard to an object type
448 * more than once, the wizard will only be applied one time.
449 *
450 * \return What happened when attempting to apply the config.
451 */
453 const char *name, const char *module);
454
455#define ast_sorcery_apply_config(sorcery, name) \
456 __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
457
458/*!
459 * \brief Apply default object wizard mappings
460 *
461 * \param sorcery Pointer to a sorcery structure
462 * \param type Type of object to apply to
463 * \param module The name of the module, typically AST_MODULE
464 * \param name Name of the wizard to use
465 * \param data Data to be passed to wizard
466 *
467 * \return What occurred when applying the default
468 *
469 * \note This should be called *after* applying configuration sourced mappings
470 *
471 * \note Only a single default can exist per object type
472 */
474 const char *type, const char *module, const char *name, const char *data);
475
476#define ast_sorcery_apply_default(sorcery, type, name, data) \
477 __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
478
479
480/*!
481 * \brief Apply additional object wizard mappings
482 *
483 * \param sorcery Pointer to a sorcery structure
484 * \param type Type of object to apply to
485 * \param module The name of the module, typically AST_MODULE
486 * \param name Name of the wizard to use
487 * \param data Data to be passed to wizard
488 * \param caching Wizard should cache
489 *
490 * \return What occurred when applying the mapping
491 *
492 * \note This should be called *after* applying default mappings
493 */
495 const char *type, const char *module, const char *name, const char *data, unsigned int caching);
496
497/*!
498 * \brief Apply additional object wizard mappings
499 *
500 * \param sorcery Pointer to a sorcery structure
501 * \param type Type of object to apply to
502 * \param name Name of the wizard to use
503 * \param data Data to be passed to wizard
504 * \param caching Wizard should cache
505 *
506 * \return What occurred when applying the mapping
507 *
508 * \note This should be called *after* applying default mappings
509 */
510#define ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching) \
511 __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));
512
513
514/*!
515 * \brief Pre-defined locations to insert at
516 */
520};
521
522/*!
523 * \brief Insert an additional object wizard mapping at a specific position
524 * in the wizard list
525 *
526 * \param sorcery Pointer to a sorcery structure
527 * \param type Type of object to apply to
528 * \param module The name of the module, typically AST_MODULE
529 * \param name Name of the wizard to use
530 * \param data Data to be passed to wizard
531 * \param caching Wizard should cache
532 * \param position An index to insert to or one of ast_sorcery_wizard_position
533 *
534 * \return What occurred when applying the mapping
535 *
536 * \note This should be called *after* applying default mappings
537 * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count
538 * and iterating over them using ast_sorcery_get_wizard_mapping.
539 *
540 * \since 13.4.0
541 */
543 const char *type, const char *module, const char *name, const char *data,
544 unsigned int caching, int position);
545
546/*!
547 * \brief Insert an additional object wizard mapping at a specific position
548 * in the wizard list
549 *
550 * \param sorcery Pointer to a sorcery structure
551 * \param type Type of object to apply to
552 * \param name Name of the wizard to use
553 * \param data Data to be passed to wizard
554 * \param caching Wizard should cache
555 * \param position One of ast_sorcery_wizard_position
556 *
557 * \return What occurred when applying the mapping
558 *
559 * \note This should be called *after* applying default mappings
560 * \since 13.4.0
561 */
562#define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \
563 __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
564 (caching), (position))
565
566/*!
567 * \brief Wizard Apply Flags
568 *
569 * These flags apply only to a wizard/object-type combination.
570 * The same wizard may be applied to a different object-type with
571 * different flags and behavior. If ALLOW_DUPLICATE is set
572 * the wizard could even be applied to the same object-type
573 * with different flags.
574 */
576 /*! Apply no special behavior */
578 /*! This wizard will cache this object type's entries */
580 /*! This wizard won't allow Create, Update or Delete operations on this object type */
582 /*! This wizard will allow other instances of itself on the same object type */
585
586/*!
587 * \brief Insert an additional object wizard mapping at a specific position
588 * in the wizard list returning wizard information
589 * \since 13.26.0
590 * \since 16.3.0
591 *
592 * \param sorcery Pointer to a sorcery structure
593 * \param object_type_name Name of the object type to apply to
594 * \param module The name of the module, typically AST_MODULE
595 * \param wizard_type_name Name of the wizard type to use
596 * \param wizard_args Opaque string to be passed to the wizard
597 * May be NULL but see note below
598 * \param flags One or more of enum ast_sorcery_wizard_apply_flags
599 * \param position An index to insert to or one of ast_sorcery_wizard_position
600 * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
601 * May be NULL if not needed.
602 * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
603 * May be NULL if not needed.
604 *
605 * \return What occurred when applying the mapping
606 *
607 * \note This should be called *after* applying default mappings
608 *
609 * \note Although \p wizard_args is an optional parameter it is highly
610 * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
611 * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
612 * to remove specific instances of a wizard type.
613 */
615 const char *object_type_name, const char *module, const char *wizard_type_name,
616 const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position,
617 struct ast_sorcery_wizard **wizard, void **wizard_data);
618
619/*!
620 * \brief Insert an additional object wizard mapping at a specific position
621 * in the wizard list returning wizard information
622 * \since 13.26.0
623 * \since 16.3.0
624 *
625 * \param sorcery Pointer to a sorcery structure
626 * \param object_type_name Name of the object type to apply to
627 * \param wizard_type_name Name of the wizard type to use
628 * \param wizard_args Opaque string to be passed to the wizard
629 * May be NULL but see note below
630 * \param flags One or more of enum ast_sorcery_wizard_apply_flags
631 * \param position An index to insert to or one of ast_sorcery_wizard_position
632 * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
633 * May be NULL if not needed.
634 * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
635 * May be NULL if not needed.
636 *
637 * \return What occurred when applying the mapping
638 *
639 * \note This should be called *after* applying default mappings
640 *
641 * \note Although \p wizard_args is an optional parameter it is highly
642 * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
643 * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
644 * to remove specific instances.
645 */
646#define ast_sorcery_object_type_insert_wizard(sorcery, \
647 object_type_name, wizard_type_name, wizard_args, flags, \
648 position, wizard, wizard_data) \
649 __ast_sorcery_object_type_insert_wizard((sorcery), \
650 (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
651 position, (wizard), (wizard_data))
652
653/*!
654 * \brief Apply additional object wizard mappings returning wizard information
655 * \since 13.26.0
656 * \since 16.3.0
657 *
658 * \param sorcery Pointer to a sorcery structure
659 * \param object_type_name Name of the object type to apply to
660 * \param wizard_type_name Name of the wizard type to use
661 * \param wizard_args Opaque string to be passed to the wizard
662 * May be NULL but see note below
663 * \param flags One or more of enum ast_sorcery_wizard_apply_flags
664 * \param[out] wizard A variable to receive a pointer to the ast_sorcery_wizard structure.
665 * May be NULL if not needed.
666 * \param[out] wizard_data A variable to receive a pointer to the wizard's internal data.
667 * May be NULL if not needed.
668 *
669 * \return What occurred when applying the mapping
670 *
671 * \note This should be called *after* applying default mappings
672 *
673 * \note Although \p wizard_args is an optional parameter it is highly
674 * recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
675 * flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
676 * to remove specific instances.
677 */
678#define ast_sorcery_object_type_apply_wizard(sorcery, \
679 object_type_name, wizard_type_name, wizard_args, flags, \
680 wizard, wizard_data) \
681 __ast_sorcery_object_type_insert_wizard((sorcery), \
682 (object_type_name), AST_MODULE, (wizard_type_name), (wizard_args), (flags), \
683 AST_SORCERY_WIZARD_POSITION_LAST, (wizard), (wizard_data))
684
685/*!
686 * \brief Remove an object wizard mapping
687 * \since 13.26.0
688 * \since 16.3.0
689 *
690 * \param sorcery Pointer to a sorcery structure
691 * \param object_type_name Name of the object type to remove from
692 * \param module The name of the module, typically AST_MODULE
693 * \param wizard_type_name The name of the of the wizard type to remove
694 * \param wizard_args Opaque string originally passed to the wizard
695 *
696 * \retval 0 success
697 * \retval -1 failure
698 *
699 * \note If there were multiple instances of the same wizard type
700 * added to this object type without using \p wizard_args, then
701 * only the first wizard matching wizard_type will be removed.
702 */
704 const char *object_type_name, const char *module, const char *wizard_type_name,
705 const char *wizard_args);
706
707/*!
708 * \brief Remove an object wizard mapping
709 * \since 13.26.0
710 * \since 16.3.0
711 *
712 * \param sorcery Pointer to a sorcery structure
713 * \param object_type_name Name of the object type to remove from
714 * \param wizard_type_name The name of the of the wizard type to remove
715 * \param wizard_args Opaque string originally passed to the wizard
716 *
717 * \retval 0 success
718 * \retval -1 failure
719 *
720 * \note If there were multiple instances of the same wizard type
721 * added to this object type without using \p wizard_args, then
722 * only the first wizard matching wizard_type will be removed.
723 */
724#define ast_sorcery_object_type_remove_wizard(sorcery, object_type_name, \
725 wizard_type_name, wizard_args) \
726 __ast_sorcery_object_type_remove_wizard((sorcery), (object_type_name), \
727 AST_MODULE, (wizard_type_name), (wizard_args))
728
729/*!
730 * \brief Remove an object wizard mapping
731 *
732 * \param sorcery Pointer to a sorcery structure
733 * \param type Type of object to remove from
734 * \param module The name of the module, typically AST_MODULE
735 * \param name The name of the wizard to remove
736 *
737 * \retval 0 success
738 * \retval -1 failure
739 *
740 * \since 13.4.0
741 */
743 const char *type, const char *module, const char *name);
744
745/*!
746 * \brief Remove an object wizard mapping
747 *
748 * \param sorcery Pointer to a sorcery structure
749 * \param type Type of object to remove from
750 * \param name The name of the wizard to remove
751 *
752 * \retval 0 success
753 * \retval -1 failure
754 *
755 * \since 13.4.0
756 */
757#define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
758 __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
759
760/*!
761 * \brief Return the number of wizards mapped to an object type
762 *
763 * \param sorcery Pointer to a sorcery structure
764 * \param type Type of object
765 *
766 * \return Number of wizards or -1 for error
767 * \since 13.4.0
768 */
770 const char *type);
771
772/*!
773 * \brief By index, return a wizard mapped to an object type
774 *
775 * \param sorcery Pointer to a sorcery structure
776 * \param type Type of object
777 * \param index Index of the wizard
778 * \param wizard A pointer to receive the wizard pointer
779 * \param data A pointer to receive the data pointer
780 *
781 * \retval 0 success
782 * \retval -1 failure
783 *
784 * \warning The wizard will have its reference count bumped so you must
785 * call ao2_cleanup when you're done with it.
786 *
787 * \note The wizard and data returned are valid only for this object type
788 * and only while the wizard is applied to the object type.
789 *
790 * \since 13.4.0
791 */
793 const char *type, int index, struct ast_sorcery_wizard **wizard, void **data);
794
795/*!
796 * \brief Unregister an object type
797 *
798 * \param sorcery Pointer to a sorcery structure
799 * \param type Type of object
800 *
801 * \retval 0 success
802 * \retval -1 failure
803 */
804int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type);
805
806/*!
807 * \brief Register an object type
808 *
809 * \param sorcery Pointer to a sorcery structure
810 * \param type Type of object
811 * \param hidden All objects of this type are internal and should not be manipulated by users
812 * \param reloadable All objects of this type are reloadable
813 * \param alloc Required object allocation callback
814 * \param transform Optional transformation callback
815 * \param apply Optional object set apply callback
816 *
817 * \note In general, this function should not be used directly. One of the various
818 * macro'd versions should be used instead.
819 *
820 * \retval 0 success
821 * \retval -1 failure
822 */
823int __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);
824
825/*!
826 * \brief Register an object type
827 *
828 * \param sorcery Pointer to a sorcery structure
829 * \param type Type of object
830 * \param alloc Required object allocation callback
831 * \param transform Optional transformation callback
832 * \param apply Optional object set apply callback
833 *
834 * \retval 0 success
835 * \retval -1 failure
836 */
837#define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
838 __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
839
840/*!
841 * \brief Register an object type that is not reloadable
842 *
843 * \param sorcery Pointer to a sorcery structure
844 * \param type Type of object
845 * \param alloc Required object allocation callback
846 * \param transform Optional transformation callback
847 * \param apply Optional object set apply callback
848 *
849 * \retval 0 success
850 * \retval -1 failure
851 */
852#define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
853 __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
854
855/*!
856 * \brief Register an internal, hidden object type
857 *
858 * \param sorcery Pointer to a sorcery structure
859 * \param type Type of object
860 * \param alloc Required object allocation callback
861 * \param transform Optional transformation callback
862 * \param apply Optional object set apply callback
863 *
864 * \retval 0 success
865 * \retval -1 failure
866 */
867#define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
868 __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
869
870/*!
871 * \brief Set the high and low alert water marks of the sorcery object type.
872 * \since 13.10.0
873 *
874 * \param sorcery Pointer to a sorcery structure
875 * \param type Type of object
876 * \param low_water New queue low water mark. (-1 to set as 90% of high_water)
877 * \param high_water New queue high water mark.
878 *
879 * \retval 0 on success.
880 * \retval -1 on error (water marks not changed).
881 */
882int ast_sorcery_object_set_congestion_levels(struct ast_sorcery *sorcery, const char *type, long low_water, long high_water);
883
884/*!
885 * \brief Set the copy handler for an object type
886 *
887 * \param sorcery Pointer to a sorcery structure
888 * \param type Type of object
889 * \param copy Copy handler
890 */
892
893/*!
894 * \brief Set the diff handler for an object type
895 *
896 * \param sorcery Pointer to a sorcery structure
897 * \param type Type of object
898 * \param diff Diff handler
899 */
901
902/*!
903 * \brief Register a regex for multiple fields within an object
904 *
905 * \param sorcery Pointer to a sorcery structure
906 * \param type Type of object
907 * \param regex A regular expression pattern for the fields
908 * \param config_handler A custom handler for translating the string representation of the fields
909 * \param sorcery_handler A custom handler for translating the native representation of the fields
910 *
911 * \retval 0 success
912 * \retval -1 failure
913 */
914int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
915 sorcery_fields_handler sorcery_handler);
916
917/*!
918 * \brief Register a field within an object
919 *
920 * \param sorcery Pointer to a sorcery structure
921 * \param type Type of object
922 * \param name Name of the field
923 * \param default_val Default value of the field
924 * \param config_handler A custom handler for translating the string representation of the fields
925 * \param sorcery_handler A custom handler for translating the native representation of the fields
926 * \param multiple_handler A custom handler for translating the native representation of the fields
927 * \param opt_type Option type
928 * \param flags Option type specific flags
929 * \param no_doc Field should not be documented
930 * \param alias Interpret and apply field value only
931 * \param argc
932 *
933 * \retval 0 success
934 * \retval -1 failure
935 */
937 const char *name, const char *default_val, enum aco_option_type opt_type,
938 aco_option_handler config_handler, sorcery_field_handler sorcery_handler,
939 sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc,
940 unsigned int alias, size_t argc, ...);
941
942/*!
943 * \brief Register a field within an object
944 *
945 * \param sorcery Pointer to a sorcery structure
946 * \param type Type of object
947 * \param name Name of the field
948 * \param default_val Default value of the field
949 * \param opt_type Option type
950 * \param flags Option type specific flags
951 *
952 * \retval 0 success
953 * \retval -1 failure
954 */
955#define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
956 __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
957
958/*!
959 * \brief Register a field within an object as an alias
960 *
961 * \param sorcery Pointer to a sorcery structure
962 * \param type Type of object
963 * \param name Name of the field
964 * \param default_val Default value of the field
965 * \param opt_type Option type
966 * \param flags Option type specific flags
967 *
968 * \retval 0 success
969 * \retval -1 failure
970 */
971#define ast_sorcery_object_field_register_alias(sorcery, type, name, default_val, opt_type, flags, ...) \
972 __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
973
974/*!
975 * \brief Register a field within an object without documentation
976 *
977 * \param sorcery Pointer to a sorcery structure
978 * \param type Type of object
979 * \param name Name of the field
980 * \param default_val Default value of the field
981 * \param opt_type Option type
982 * \param flags Option type specific flags
983 *
984 * \retval 0 success
985 * \retval -1 failure
986 */
987#define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
988 __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
989
990/*!
991 * \brief Register a field within an object with custom handlers
992 *
993 * \param sorcery Pointer to a sorcery structure
994 * \param type Type of object
995 * \param name Name of the field
996 * \param default_val Default value of the field
997 * \param config_handler Custom configuration handler
998 * \param sorcery_handler Custom sorcery handler
999 * \param multiple_handler Custom multiple handler
1000 * \param flags Option type specific flags
1001 *
1002 * \retval 0 success
1003 * \retval -1 failure
1004 */
1005#define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1006 __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__);
1007
1008/*!
1009 * \brief Register a field within an object with custom handlers as an alias
1010 *
1011 * \param sorcery Pointer to a sorcery structure
1012 * \param type Type of object
1013 * \param name Name of the field
1014 * \param default_val Default value of the field
1015 * \param config_handler Custom configuration handler
1016 * \param sorcery_handler Custom sorcery handler
1017 * \param multiple_handler Custom multiple handler
1018 * \param flags Option type specific flags
1019 *
1020 * \retval 0 success
1021 * \retval -1 failure
1022 */
1023#define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1024 __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__);
1025
1026/*!
1027 * \brief Register a field within an object with custom handlers without documentation
1028 *
1029 * \param sorcery Pointer to a sorcery structure
1030 * \param type Type of object
1031 * \param name Name of the field
1032 * \param default_val Default value of the field
1033 * \param config_handler Custom configuration handler
1034 * \param sorcery_handler Custom sorcery handler
1035 * \param multiple_handler Custom multiple handler
1036 * \param flags Option type specific flags
1037 *
1038 * \retval 0 success
1039 * \retval -1 failure
1040 */
1041#define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
1042 __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__);
1043
1044/*!
1045 * \brief Inform any wizards to load persistent objects
1046 *
1047 * \param sorcery Pointer to a sorcery structure
1048 */
1049void ast_sorcery_load(const struct ast_sorcery *sorcery);
1050
1051/*!
1052 * \brief Inform any wizards of a specific object type to load persistent objects
1053 *
1054 * \param sorcery Pointer to a sorcery structure
1055 * \param type Name of the object type to load
1056 */
1057void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
1058
1059/*!
1060 * \brief Inform any wizards to reload persistent objects
1061 *
1062 * \param sorcery Pointer to a sorcery structure
1063 */
1064void ast_sorcery_reload(const struct ast_sorcery *sorcery);
1065
1066/*!
1067 * \brief Inform any wizards to reload persistent objects, even if no changes determined
1068 *
1069 * \param sorcery Pointer to a sorcery structure
1070 *
1071 * \since 13.32.0
1072 * \since 16.9.0
1073 * \since 17.3.0
1074 */
1075void ast_sorcery_force_reload(const struct ast_sorcery *sorcery);
1076
1077/*!
1078 * \brief Inform any wizards of a specific object type to reload persistent objects
1079 *
1080 * \param sorcery Pointer to a sorcery structure
1081 * \param type Name of the object type to reload
1082 */
1083void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
1084
1085/*!
1086 * \brief Inform any wizards of a specific object type to reload persistent objects
1087 * even if no changes determined
1088 *
1089 * \param sorcery Pointer to a sorcery structure
1090 * \param type Name of the object type to reload
1091 *
1092 * \since 13.32.0
1093 * \since 16.9.0
1094 * \since 17.3.0
1095 */
1096void ast_sorcery_force_reload_object(const struct ast_sorcery *sorcery, const char *type);
1097
1098/*!
1099 * \brief Increase the reference count of a sorcery structure
1100 *
1101 * \param sorcery Pointer to a sorcery structure
1102 */
1103void ast_sorcery_ref(struct ast_sorcery *sorcery);
1104
1105
1106/*!
1107 * \brief Create an object set (KVP list) for an object
1108 *
1109 * \param sorcery Pointer to a sorcery structure
1110 * \param object Pointer to a sorcery object
1111 * \param flags Flags indicating which handler to use and in what order.
1112 *
1113 * \retval non-NULL success
1114 * \retval NULL if error occurred
1115 *
1116 * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1117 */
1119 const void *object, enum ast_sorcery_field_handler_flags flags);
1120
1121/*!
1122 * \brief Create an object set (KVP list) for an object
1123 *
1124 * \param sorcery Pointer to a sorcery structure
1125 * \param object Pointer to a sorcery object
1126 *
1127 * \retval non-NULL success
1128 * \retval NULL if error occurred
1129 *
1130 * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1131 *
1132 * \note This function attempts to use a field's sorcery_fields_handler first and if that
1133 * doesn't exist or fails, a field's sorcery_field_handler is used. The difference is
1134 * that the former may return multiple list entries for the same field and the latter will only
1135 * return 1. It's up to the field itself to determine what the appropriate content is.
1136 */
1137#define ast_sorcery_objectset_create(sorcery, object) \
1138 ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
1139
1140/*!
1141 * \brief Create an object set in JSON format for an object
1142 *
1143 * \param sorcery Pointer to a sorcery structure
1144 * \param object Pointer to a sorcery object
1145 *
1146 * \retval non-NULL success
1147 * \retval NULL if error occurred
1148 *
1149 * \note The returned ast_json object must be unreferenced using ast_json_unref
1150 */
1151struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
1152
1153/*!
1154 * \brief Apply an object set (KVP list) to an object
1155 *
1156 * \param sorcery Pointer to a sorcery structure
1157 * \param object Pointer to a sorcery object
1158 * \param objectset Object set itself
1159 *
1160 * \retval 0 success
1161 * \retval -1 failure
1162 *
1163 * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
1164 * applied object set.
1165 */
1166int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
1167
1168/*!
1169 * \brief Create a changeset given two object sets
1170 *
1171 * \param original Original object set
1172 * \param modified Modified object set
1173 * \param changes Pointer to hold any changes between the object sets
1174 *
1175 * \retval 0 success
1176 * \retval -1 failure
1177 *
1178 * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1179 */
1180int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
1181
1182/*!
1183 * \brief Allocate a generic sorcery capable object
1184 *
1185 * \param size Size of the object
1186 * \param destructor Optional destructor function
1187 *
1188 * \retval non-NULL success
1189 * \retval NULL failure
1190 *
1191 * \note The returned object does not support AO2 locking.
1192 */
1193void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
1194
1195/*!
1196 * \since 14.1.0
1197 * \brief Allocate a generic sorcery capable object with locking.
1198 *
1199 * \details Sorcery objects may be replaced with new allocations during reloads.
1200 * If locking is required on sorcery objects it must be shared between the old
1201 * object and the new one. lockobj can be any AO2 object with locking enabled,
1202 * but in most cases named locks should be used to provide stable locking.
1203 *
1204 * \param size Size of the object
1205 * \param destructor Optional destructor function
1206 * \param lockobj An AO2 object that will provide locking.
1207 *
1208 * \retval non-NULL success
1209 * \retval NULL failure
1210 */
1211void *ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj);
1212
1213/*!
1214 * \brief Allocate an object
1215 *
1216 * \param sorcery Pointer to a sorcery structure
1217 * \param type Type of object to allocate
1218 * \param id Optional unique identifier, if none is provided one will be generated
1219 *
1220 * \retval non-NULL success
1221 * \retval NULL failure
1222 */
1223void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
1224
1225/*!
1226 * \brief Create a copy of an object
1227 *
1228 * \param sorcery Pointer to a sorcery structure
1229 * \param object Existing object
1230 *
1231 * \retval non-NULL success
1232 * \retval NULL failure
1233 */
1234void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
1235
1236/*!
1237 * \brief Create a changeset of two objects
1238 *
1239 * \param sorcery Pointer to a sorcery structure
1240 * \param original Original object
1241 * \param modified Modified object
1242 * \param changes Pointer which will be populated with changes if any exist
1243 *
1244 * \retval 0 success
1245 * \retval -1 failure
1246 *
1247 * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1248 *
1249 * \note While the objects must be of the same type they do not have to be the same object
1250 */
1251int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
1252
1253/*!
1254 * \brief Add a global observer to sorcery
1255 *
1256 * \param callbacks Implementation of the global observer interface
1257 *
1258 * \retval 0 success
1259 * \retval -1 failure
1260 *
1261 * \note You must be ready to accept observer invocations before this function is called
1262 */
1264
1265/*!
1266 * \brief Remove a global observer from sorcery.
1267 *
1268 * A global observer is notified...
1269 * After a new wizard is registered.
1270 * After a new sorcery instance is opened.
1271 * Before an instance is destroyed.
1272 * Before a wizard is unregistered.
1273 *
1274 * \param callbacks Implementation of the global observer interface
1275 */
1277
1278/*!
1279 * \brief Add an observer to a sorcery instance
1280 *
1281 * \param sorcery Pointer to a sorcery structure
1282 * \param callbacks Implementation of the instance observer interface
1283 *
1284 * An instance observer is notified...
1285 * Before an instance is loaded or reloaded.
1286 * After an instance is loaded or reloaded.
1287 * After a wizard is mapped to an object type.
1288 * After an object type is registered.
1289 * Before an object type is loaded or reloaded.
1290 * After an object type is loaded or reloaded.
1291 *
1292 * \retval 0 success
1293 * \retval -1 failure
1294 *
1295 * \note You must be ready to accept observer invocations before this function is called
1296 */
1299
1300/*!
1301 * \brief Remove an observer from a sorcery instance
1302 *
1303 * \param sorcery Pointer to a sorcery structure
1304 * \param callbacks Implementation of the instance observer interface
1305 */
1308
1309/*!
1310 * \brief Add an observer to a sorcery wizard
1311 *
1312 * \param wizard Pointer to a previously registered wizard structure
1313 * \param callbacks Implementation of the wizard observer interface
1314 *
1315 * A wizard observer is notified...
1316 * Before a wizard is loaded or reloaded.
1317 * After a wizard is loaded or reloaded.
1318 *
1319 * \retval 0 success
1320 * \retval -1 failure
1321 *
1322 * \note You must be ready to accept observer invocations before this function is called
1323 */
1326
1327/*!
1328 * \brief Remove an observer from a sorcery wizard.
1329 *
1330 * \param interface Pointer to a sorcery structure
1331 * \param callbacks Implementation of the wizard observer interface
1332 */
1335
1336/*!
1337 * \brief Add an observer to a specific object type
1338 *
1339 * \param sorcery Pointer to a sorcery structure
1340 * \param type Type of object that should be observed
1341 * \param callbacks Implementation of the observer interface
1342 *
1343 * \retval 0 success
1344 * \retval -1 failure
1345 *
1346 * \note You must be ready to accept observer invocations before this function is called
1347 */
1348int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1349
1350/*!
1351 * \brief Remove an observer from a specific object type
1352 *
1353 * \param sorcery Pointer to a sorcery structure
1354 * \param type Type of object that should no longer be observed
1355 * \param callbacks Implementation of the observer interface
1356 */
1357void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1358
1359/*!
1360 * \brief Create and potentially persist an object using an available wizard
1361 *
1362 * \param sorcery Pointer to a sorcery structure
1363 * \param object Pointer to a sorcery object
1364 *
1365 * \retval 0 success
1366 * \retval -1 failure
1367 */
1368int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
1369
1370/*!
1371 * \brief Retrieve an object using its unique identifier
1372 *
1373 * \param sorcery Pointer to a sorcery structure
1374 * \param type Type of object to retrieve
1375 * \param id Unique object identifier
1376 *
1377 * \retval non-NULL if found
1378 * \retval NULL if not found
1379 */
1380void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
1381
1382/*!
1383 * \brief Retrieve an object or multiple objects using specific fields
1384 * \since 13.9.0
1385 *
1386 * \param sorcery Pointer to a sorcery structure
1387 * \param type Type of object to retrieve
1388 * \param flags Flags to control behavior
1389 * \param fields Optional object fields and values to match against
1390 *
1391 * \retval non-NULL if found
1392 * \retval NULL if not found
1393 *
1394 * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
1395 * ao2_container that must be unreferenced after use.
1396 *
1397 * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
1398 * of the given type.
1399 *
1400 * \note The fields parameter can contain realtime-style expressions in variable->name.
1401 * All operators defined for ast_strings_match can be used except for regex as
1402 * there's no common support for regex in the realtime backends at this time.
1403 * If multiple variables are in the fields list, all must match for an object to
1404 * be returned. See ast_strings_match for more information.
1405 *
1406 * Example:
1407 *
1408 * The following code can be significantly faster when a realtime backend is in use
1409 * because the expression "qualify_frequency > 0" is passed to the database to limit
1410 * the number of rows returned.
1411 *
1412 * struct ast_variable *var = ast_variable_new("qualify_frequency >", "0", "");
1413 * struct ao2_container *aors;
1414 *
1415 * if (!var) {
1416 * return;
1417 * }
1418 *
1419 * aors = ast_sorcery_retrieve_by_fields(ast_sip_get_sorcery(),
1420 * "aor", AST_RETRIEVE_FLAG_MULTIPLE, var);
1421 *
1422 */
1423void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
1424
1425/*!
1426 * \brief Retrieve multiple objects using a regular expression on their id
1427 *
1428 * \param sorcery Pointer to a sorcery structure
1429 * \param type Type of object to retrieve
1430 * \param regex Regular expression
1431 *
1432 * \retval non-NULL if error occurs
1433 * \retval NULL success
1434 *
1435 * \note The provided regex is treated as extended case sensitive.
1436 */
1437struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
1438
1439/*!
1440 * \brief Retrieve multiple objects whose id begins with the specified prefix
1441 * \since 13.19.0
1442 *
1443 * \param sorcery Pointer to a sorcery structure
1444 * \param type Type of object to retrieve
1445 * \param prefix Object id prefix
1446 * \param prefix_len The length of prefix in bytes
1447 *
1448 * \retval non-NULL if error occurs
1449 * \retval NULL success
1450 *
1451 * \note The prefix is matched in a case sensitive manner.
1452 */
1453struct ao2_container *ast_sorcery_retrieve_by_prefix(const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len);
1454
1455/*!
1456 * \brief Update an object
1457 *
1458 * \param sorcery Pointer to a sorcery structure
1459 * \param object Pointer to a sorcery object
1460 *
1461 * \retval 0 success
1462 * \retval -1 failure
1463 */
1464int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
1465
1466/*!
1467 * \brief Delete an object
1468 *
1469 * \param sorcery Pointer to a sorcery structure
1470 * \param object Pointer to a sorcery object
1471 *
1472 * \retval 0 success
1473 * \retval -1 failure
1474 */
1475int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
1476
1477/*!
1478 * \brief Determine if a sorcery object is stale with respect to its backing datastore
1479 * \since 14.0.0
1480 *
1481 * This function will query the wizard(s) backing the particular sorcery object to
1482 * determine if the in-memory object is now stale. No action is taken to update
1483 * the object. Callers of this function may use one of the ast_sorcery_retrieve
1484 * functions to obtain a new instance of the object if desired.
1485 *
1486 * \retval 0 the object is not stale
1487 * \retval 1 the object is stale
1488 */
1489int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
1490
1491/*!
1492 * \brief Decrease the reference count of a sorcery structure
1493 *
1494 * \param sorcery Pointer to a sorcery structure
1495 *
1496 * \note Prior to 16.0.0 this was a function which had to be used.
1497 * Now you can use any variant of ao2_cleanup or ao2_ref to
1498 * release a reference.
1499 */
1500#define ast_sorcery_unref(sorcery) \
1501 ao2_cleanup(sorcery)
1502
1503/*!
1504 * \brief Get the unique identifier of a sorcery object
1505 *
1506 * \param object Pointer to a sorcery object
1507 *
1508 * \return unique identifier
1509 */
1510const char *ast_sorcery_object_get_id(const void *object);
1511
1512/*!
1513 * \since 14.0.0
1514 * \brief Get when the sorcery object was created
1515 *
1516 * \param object Pointer to a sorcery object
1517 *
1518 * \return The time when the object was created
1519 */
1520const struct timeval ast_sorcery_object_get_created(const void *object);
1521
1522/*!
1523 * \brief Get the type of a sorcery object
1524 *
1525 * \param object Pointer to a sorcery object
1526 *
1527 * \return type of object
1528 */
1529const char *ast_sorcery_object_get_type(const void *object);
1530
1531/*!
1532 * \brief Get an extended field value from a sorcery object
1533 *
1534 * \param object Pointer to a sorcery object
1535 * \param name Name of the extended field value
1536 *
1537 * \retval non-NULL if found
1538 * \retval NULL if not found
1539 *
1540 * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
1541 */
1542const char *ast_sorcery_object_get_extended(const void *object, const char *name);
1543
1544/*!
1545 * \brief Set an extended field value on a sorcery object
1546 *
1547 * \param object Pointer to a sorcery object
1548 * \param name Name of the extended field
1549 * \param value Value of the extended field
1550 *
1551 * \retval 0 success
1552 * \retval -1 failure
1553 *
1554 * \note The field name MUST begin with '@' to indicate it is an extended field.
1555 * \note If the extended field already exists it will be overwritten with the new value.
1556 */
1557int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
1558
1559/*!
1560 * \brief Get whether an object contains dynamic contents or not
1561 *
1562 * \param object Pointer to a sorcery object
1563 *
1564 * \since 19
1565 * \since 18.3.0
1566 * \since 16.17.0
1567 */
1568unsigned int ast_sorcery_object_has_dynamic_contents(const void *object);
1569
1570/*!
1571 * \brief Set the dynamic contents flag on a sorcery object
1572 *
1573 * \param object Pointer to a sorcery object
1574 *
1575 * \since 19
1576 * \since 18.3.0
1577 * \since 16.17.0
1578 */
1579void ast_sorcery_object_set_has_dynamic_contents(const void *object);
1580
1581/*!
1582 * \brief ao2 object comparator based on sorcery id.
1583 */
1584int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
1585
1586/*!
1587 * \brief ao2 object sorter based on sorcery id.
1588 */
1589int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
1590
1591/*!
1592 * \brief ao2 object hasher based on sorcery id.
1593 */
1594int ast_sorcery_object_id_hash(const void *obj, int flags);
1595
1596/*!
1597 * \brief Get the sorcery object type given a type name.
1598 *
1599 * \param sorcery The sorcery from which to retrieve the object type
1600 * \param type The type name
1601 */
1603 const char *type);
1604
1605/*!
1606 * \brief Determine if a particular object field has been registered with sorcery
1607 *
1608 * \param object_type The object type to check against
1609 * \param field_name The name of the field to check
1610 *
1611 * \retval 0 The field is not registered for this sorcery type
1612 * \retval 1 The field is registered for this sorcery type
1613 */
1615 const char *field_name);
1616
1617/*!
1618 * \brief Get the module that has opened the provided sorcery instance.
1619 *
1620 * \param sorcery The sorcery instance
1621 *
1622 * \return The module
1623 */
1624const char *ast_sorcery_get_module(const struct ast_sorcery *sorcery);
1625
1626#if defined(__cplusplus) || defined(c_plusplus)
1627}
1628#endif
1629
1630#endif /* _ASTERISK_SORCERY_H */
enum queue_result id
Definition: app_queue.c:1638
static int copy(char *infile, char *outfile)
Utility function to copy a file.
void(* ao2_destructor_fn)(void *vdoomed)
Typedef for an object destructor.
Definition: astobj2.h:358
static const char type[]
Definition: chan_ooh323.c:109
Configuration option-handling.
int(* aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj)
A callback function for handling a particular option.
aco_option_type
The option types.
void *(* aco_type_item_alloc)(const char *category)
Allocate a configurable ao2 object.
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
static int set(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
Definition: func_logic.c:238
static int regex(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
static char prefix[MAX_PREFIX]
Definition: http.c:144
static struct ast_sorcery * sorcery
struct @468 callbacks
const char * ast_sorcery_object_get_extended(const void *object, const char *name)
Get an extended field value from a sorcery object.
Definition: sorcery.c:2335
const char * ast_sorcery_object_get_id(const void *object)
Get the unique identifier of a sorcery object.
Definition: sorcery.c:2317
int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface)
Unregister a sorcery wizard.
Definition: sorcery.c:474
void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks)
Remove an observer from a specific object type.
Definition: sorcery.c:2423
int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler, sorcery_fields_handler sorcery_handler)
Register a regex for multiple fields within an object.
Definition: sorcery.c:1160
int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value)
Set an extended field value on a sorcery object.
Definition: sorcery.c:2349
void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
Remove an observer from a sorcery instance.
Definition: sorcery.c:537
enum ast_sorcery_apply_result __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data)
Apply default object wizard mappings.
Definition: sorcery.c:1031
struct ast_variable *(* sorcery_transform_handler)(struct ast_variable *set)
A callback function for performing a transformation on an object set.
Definition: sorcery.h:181
ast_sorcery_retrieve_flags
Retrieval flags.
Definition: sorcery.h:115
@ AST_RETRIEVE_FLAG_MULTIPLE
Return all matching objects.
Definition: sorcery.h:120
@ AST_RETRIEVE_FLAG_DEFAULT
Default retrieval flags.
Definition: sorcery.h:117
@ AST_RETRIEVE_FLAG_ALL
Perform no matching, return all objects.
Definition: sorcery.h:123
void ast_sorcery_load(const struct ast_sorcery *sorcery)
Inform any wizards to load persistent objects.
Definition: sorcery.c:1377
void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *interface, const struct ast_sorcery_wizard_observer *callbacks)
Remove an observer from a sorcery wizard.
Definition: sorcery.c:568
const char * ast_sorcery_get_module(const struct ast_sorcery *sorcery)
Get the module that has opened the provided sorcery instance.
Definition: sorcery.c:2536
const char * ast_sorcery_object_get_type(const void *object)
Get the type of a sorcery object.
Definition: sorcery.c:2329
int(* sorcery_fields_handler)(const void *obj, struct ast_variable **fields)
A callback function for translating multiple values into an ast_variable list.
Definition: sorcery.h:169
void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy)
Set the copy handler for an object type.
Definition: sorcery.c:1128
void ast_sorcery_object_set_has_dynamic_contents(const void *object)
Set the dynamic contents flag on a sorcery object.
Definition: sorcery.c:2384
int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object)
Create and potentially persist an object using an available wizard.
Definition: sorcery.c:2062
struct ast_sorcery_object_type * ast_sorcery_get_object_type(const struct ast_sorcery *sorcery, const char *type)
Get the sorcery object type given a type name.
Definition: sorcery.c:2494
int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes)
Create a changeset of two objects.
Definition: sorcery.c:1805
void * ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id)
Retrieve an object using its unique identifier.
Definition: sorcery.c:1853
struct ast_sorcery * __ast_sorcery_open(const char *module, const char *file, int line, const char *func)
Definition: sorcery.c:601
void ast_sorcery_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects.
Definition: sorcery.c:1408
int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery, const char *type)
Return the number of wizards mapped to an object type.
Definition: sorcery.c:778
struct ao2_container * ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex)
Retrieve multiple objects using a regular expression on their id.
Definition: sorcery.c:1954
int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module)
Register a sorcery wizard.
Definition: sorcery.c:432
int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks)
Add an observer to a specific object type.
Definition: sorcery.c:2391
enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching, int position)
Insert an additional object wizard mapping at a specific position in the wizard list.
Definition: sorcery.c:967
void ast_sorcery_force_reload(const struct ast_sorcery *sorcery)
Inform any wizards to reload persistent objects, even if no changes determined.
Definition: sorcery.c:1425
void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type)
Inform any wizards of a specific object type to load persistent objects.
Definition: sorcery.c:1393
int(* sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj)
A callback function for when an object set is successfully applied to an object.
Definition: sorcery.h:194
void * ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor)
Allocate a generic sorcery capable object.
Definition: sorcery.c:1728
int ast_sorcery_object_unregister(struct ast_sorcery *sorcery, const char *type)
Unregister an object type.
Definition: sorcery.c:1061
int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name)
Remove an object wizard mapping.
Definition: sorcery.c:850
int(* sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes)
A callback function for generating a changeset between two objects.
Definition: sorcery.h:217
int ast_sorcery_object_id_compare(void *obj, void *arg, int flags)
ao2 object comparator based on sorcery id.
Definition: sorcery.c:2464
int(* sorcery_copy_handler)(const void *src, void *dst)
A callback function for copying the contents of one object to another.
Definition: sorcery.h:205
unsigned int ast_sorcery_object_has_dynamic_contents(const void *object)
Get whether an object contains dynamic contents or not.
Definition: sorcery.c:2377
void ast_sorcery_ref(struct ast_sorcery *sorcery)
Increase the reference count of a sorcery structure.
Definition: sorcery.c:1473
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, aco_option_handler config_handler, sorcery_field_handler sorcery_handler, sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc, unsigned int alias, size_t argc,...)
Register a field within an object.
Definition: sorcery.c:1192
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)
Register an object type.
Definition: sorcery.c:1080
int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes)
Create a changeset given two object sets.
Definition: sorcery.c:1663
ast_sorcery_wizard_position
Pre-defined locations to insert at.
Definition: sorcery.h:517
@ AST_SORCERY_WIZARD_POSITION_FIRST
Definition: sorcery.h:519
@ AST_SORCERY_WIZARD_POSITION_LAST
Definition: sorcery.h:518
enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module)
Apply configured wizard mappings.
Definition: sorcery.c:985
int ast_sorcery_is_object_field_registered(const struct ast_sorcery_object_type *object_type, const char *field_name)
Determine if a particular object field has been registered with sorcery.
Definition: sorcery.c:2514
void * ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id)
Allocate an object.
Definition: sorcery.c:1744
int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags)
ao2 object sorter based on sorcery id.
Definition: sorcery.c:2440
const struct timeval ast_sorcery_object_get_created(const void *object)
Get when the sorcery object was created.
Definition: sorcery.c:2323
void * ast_sorcery_lockable_alloc(size_t size, ao2_destructor_fn destructor, void *lockobj)
Allocate a generic sorcery capable object with locking.
Definition: sorcery.c:1712
int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object)
Update an object.
Definition: sorcery.c:2150
int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset)
Apply an object set (KVP list) to an object.
Definition: sorcery.c:1632
int ast_sorcery_get_wizard_mapping(struct ast_sorcery *sorcery, const char *type, int index, struct ast_sorcery_wizard **wizard, void **data)
By index, return a wizard mapped to an object type.
Definition: sorcery.c:790
ast_sorcery_field_handler_flags
Field handler flags.
Definition: sorcery.h:129
@ AST_HANDLER_PREFER_STRING
Try both handlers, string first.
Definition: sorcery.h:131
@ AST_HANDLER_PREFER_LIST
Try both handlers, list first.
Definition: sorcery.h:134
@ AST_HANDLER_ONLY_LIST
Use list handler only.
Definition: sorcery.h:140
@ AST_HANDLER_ONLY_STRING
Use string handler only.
Definition: sorcery.h:137
void ast_sorcery_force_reload_object(const struct ast_sorcery *sorcery, const char *type)
Inform any wizards of a specific object type to reload persistent objects even if no changes determin...
Definition: sorcery.c:1457
int(* sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf)
A callback function for translating a value into a string.
Definition: sorcery.h:158
enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data, unsigned int caching)
Apply additional object wizard mappings.
Definition: sorcery.c:977
int __ast_sorcery_object_type_remove_wizard(struct ast_sorcery *sorcery, const char *object_type_name, const char *module, const char *wizard_type_name, const char *wizard_args)
Remove an object wizard mapping.
Definition: sorcery.c:820
int ast_sorcery_wizard_observer_add(struct ast_sorcery_wizard *wizard, const struct ast_sorcery_wizard_observer *callbacks)
Add an observer to a sorcery wizard.
Definition: sorcery.c:543
void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks)
Remove a global observer from sorcery.
Definition: sorcery.c:514
struct ast_json * ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object)
Create an object set in JSON format for an object.
Definition: sorcery.c:1565
int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks)
Add a global observer to sorcery.
Definition: sorcery.c:498
void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type)
Inform any wizards of a specific object type to reload persistent objects.
Definition: sorcery.c:1442
struct ast_variable * ast_sorcery_objectset_create2(const struct ast_sorcery *sorcery, const void *object, enum ast_sorcery_field_handler_flags flags)
Create an object set (KVP list) for an object.
Definition: sorcery.c:1511
int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object)
Determine if a sorcery object is stale with respect to its backing datastore.
Definition: sorcery.c:2288
int ast_sorcery_instance_observer_add(struct ast_sorcery *sorcery, const struct ast_sorcery_instance_observer *callbacks)
Add an observer to a sorcery instance.
Definition: sorcery.c:520
int ast_sorcery_object_id_hash(const void *obj, int flags)
ao2 object hasher based on sorcery id.
Definition: sorcery.c:2475
void * ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields)
Retrieve an object or multiple objects using specific fields.
Definition: sorcery.c:1897
int ast_sorcery_object_set_congestion_levels(struct ast_sorcery *sorcery, const char *type, long low_water, long high_water)
Set the high and low alert water marks of the sorcery object type.
Definition: sorcery.c:1114
struct ast_sorcery * ast_sorcery_retrieve_by_module_name(const char *module_name)
Retrieves an existing sorcery instance by module name.
Definition: sorcery.c:672
int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object)
Delete an object.
Definition: sorcery.c:2238
void * ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object)
Create a copy of an object.
Definition: sorcery.c:1778
ast_sorcery_wizard_apply_flags
Wizard Apply Flags.
Definition: sorcery.h:575
@ AST_SORCERY_WIZARD_APPLY_NONE
Definition: sorcery.h:577
@ AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
Definition: sorcery.h:583
@ AST_SORCERY_WIZARD_APPLY_READONLY
Definition: sorcery.h:581
@ AST_SORCERY_WIZARD_APPLY_CACHING
Definition: sorcery.h:579
struct ao2_container * ast_sorcery_retrieve_by_prefix(const struct ast_sorcery *sorcery, const char *type, const char *prefix, const size_t prefix_len)
Retrieve multiple objects whose id begins with the specified prefix.
Definition: sorcery.c:1989
int ast_sorcery_init(void)
Initialize the sorcery API.
Definition: sorcery.c:387
enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast_sorcery *sorcery, const char *object_type_name, const char *module, const char *wizard_type_name, const char *wizard_args, enum ast_sorcery_wizard_apply_flags flags, int position, struct ast_sorcery_wizard **wizard, void **wizard_data)
Insert an additional object wizard mapping at a specific position in the wizard list returning wizard...
Definition: sorcery.c:869
ast_sorcery_apply_result
Definition: sorcery.h:423
@ AST_SORCERY_APPLY_SUCCESS
Definition: sorcery.h:427
@ AST_SORCERY_APPLY_NO_CONFIGURATION
Definition: sorcery.h:433
@ AST_SORCERY_APPLY_FAIL
Definition: sorcery.h:425
@ AST_SORCERY_APPLY_DUPLICATE
Definition: sorcery.h:429
@ AST_SORCERY_APPLY_DEFAULT_UNNECESSARY
Definition: sorcery.h:431
void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff)
Set the diff handler for an object type.
Definition: sorcery.c:1139
Generic container type.
Abstract JSON element (object, array, string, int, ...).
Interface for the global sorcery observer.
Definition: sorcery.h:220
void(* wizard_unregistering)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback before a wizard is unregistered.
Definition: sorcery.h:232
void(* instance_destroying)(const char *name, struct ast_sorcery *sorcery)
Callback before an instance is destroyed.
Definition: sorcery.h:229
void(* wizard_registered)(const char *name, const struct ast_sorcery_wizard *wizard)
Callback after an wizard is registered.
Definition: sorcery.h:225
void(* instance_created)(const char *name, struct ast_sorcery *sorcery)
Callback after an instance is created.
Definition: sorcery.h:222
Interface for the sorcery instance observer.
Definition: sorcery.h:237
void(* instance_loaded)(const char *name, const struct ast_sorcery *sorcery, int reloaded)
Callback after instance is loaded/reloaded.
Definition: sorcery.h:243
void(* object_type_registered)(const char *name, struct ast_sorcery *sorcery, const char *object_type)
Callback after any object_type is registered.
Definition: sorcery.h:252
void(* object_type_loaded)(const char *name, const struct ast_sorcery *sorcery, const char *object_type, int reloaded)
Callback after any object_type is loaded/reloaded.
Definition: sorcery.h:260
void(* wizard_mapped)(const char *name, struct ast_sorcery *sorcery, const char *object_type, struct ast_sorcery_wizard *wizard, const char *wizard_args, void *wizard_data)
Callback after a wizard is mapped to an object_type.
Definition: sorcery.h:247
void(* object_type_loading)(const char *name, const struct ast_sorcery *sorcery, const char *object_type, int reloaded)
Callback before any object_type is loaded/reloaded.
Definition: sorcery.h:256
void(* instance_loading)(const char *name, const struct ast_sorcery *sorcery, int reloaded)
Callback before instance is loaded/reloaded.
Definition: sorcery.h:239
Structure which contains details about a sorcery object.
Definition: sorcery.h:350
struct ast_sorcery_object * object
Pointer to internal sorcery object information.
Definition: sorcery.h:352
Structure for registered object type.
Definition: sorcery.c:148
Structure for internal sorcery object information.
Definition: sorcery.c:127
Interface for a sorcery object type observer.
Definition: sorcery.h:332
void(* loaded)(const char *object_type)
Callback for when an object type is loaded/reloaded.
Definition: sorcery.h:343
void(* deleted)(const void *object)
Callback for when an object is deleted.
Definition: sorcery.h:340
void(* created)(const void *object)
Callback for when an object is created.
Definition: sorcery.h:334
void(* updated)(const void *object)
Callback for when an object is updated.
Definition: sorcery.h:337
Interface for the sorcery wizard observer.
Definition: sorcery.h:265
void(* wizard_loading)(const char *name, const struct ast_sorcery_wizard *wizard, const char *object_type, int reloaded)
Callback before a wizard is loaded/reloaded for any type.
Definition: sorcery.h:267
void(* wizard_loaded)(const char *name, const struct ast_sorcery_wizard *wizard, const char *object_type, int reloaded)
Callback after a wizard is loaded/reloaded for any type.
Definition: sorcery.h:271
Interface for a sorcery wizard.
Definition: sorcery.h:276
void(* close)(void *data)
Callback for closing a wizard.
Definition: sorcery.h:322
void(* retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields)
Optional callback for retrieving multiple objects using some optional field criteria.
Definition: sorcery.h:313
struct ast_module * module
Pointer to the Asterisk module this wizard is implemented by.
Definition: sorcery.h:281
const char * name
Name of the wizard.
Definition: sorcery.h:278
void(* load)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for loading persistent objects.
Definition: sorcery.h:287
int(* create)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for creating an object.
Definition: sorcery.h:293
int(* is_stale)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for whether or not the wizard believes the object is stale.
Definition: sorcery.h:325
void(* retrieve_prefix)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *prefix, const size_t prefix_len)
Optional callback for retrieving multiple objects by matching their id with a prefix.
Definition: sorcery.h:302
void(* force_reload)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for forcing a reload to occur, even if wizard has determined no changes.
Definition: sorcery.h:328
void(* retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex)
Callback for retrieving multiple objects using a regex on their id.
Definition: sorcery.h:299
int(* update)(const struct ast_sorcery *sorcery, void *data, void *object)
Callback for updating an object.
Definition: sorcery.h:316
void(* reload)(void *data, const struct ast_sorcery *sorcery, const char *type)
Optional callback for reloading persistent objects.
Definition: sorcery.h:290
Full structure for sorcery.
Definition: sorcery.c:230
char * module_name
Pointer to module_name in the associated sorcery_proxy.
Definition: sorcery.c:238
Structure for variables, used for configurations and for channel variables.
int value
Definition: syslog.c:37
const char * args
Universally unique identifier support.