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
 317 /*! \brief Interface for a sorcery object type observer */
 318 struct ast_sorcery_observer {
 319         /*! \brief Callback for when an object is created */
 320         void (*created)(const void *object);
 321
 322         /*! \brief Callback for when an object is updated */
 323         void (*updated)(const void *object);
 324
 325         /*! \brief Callback for when an object is deleted */
 326         void (*deleted)(const void *object);
 327
 328         /*! \brief Callback for when an object type is loaded/reloaded */
 329         void (*loaded)(const char *object_type);
 330 };
 331
 332 /*! \brief Opaque structure for internal sorcery object */
 333 struct ast_sorcery_object;
 334
 335 /*! \brief Structure which contains details about a sorcery object */
 336 struct ast_sorcery_object_details {
 337         /*! \brief Pointer to internal sorcery object information */
 338         struct ast_sorcery_object *object;
 339 };
 340
 341 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
 342 #define SORCERY_OBJECT(details)                    \
 343 struct {                                           \
 344         struct ast_sorcery_object_details details; \
 345 }                                                  \
 346
 347 /*!
 348  * \brief Initialize the sorcery API
 349  *
 350  * \retval 0 success
 351  * \retval -1 failure
 352  */
 353 int ast_sorcery_init(void);
 354
 355 /*!
 356  * \brief Register a sorcery wizard
 357  *
 358  * \param interface Pointer to a wizard interface
 359  * \param module Pointer to the module implementing the interface
 360  *
 361  * \retval 0 success
 362  * \retval -1 failure
 363  */
 364 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
 365
 366 /*!
 367  * \brief See \ref __ast_sorcery_wizard_register()
 368  */
 369 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, AST_MODULE_SELF)
 370
 371 /*!
 372  * \brief Unregister a sorcery wizard
 373  *
 374  * \param interface Pointer to the wizard interface
 375  *
 376  * \retval 0 success
 377  * \retval -1 failure
 378  */
 379 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
 380
 381 /*!
 382  * \brief Open a new sorcery structure
 383  *
 384  * \param module The module name (AST_MODULE)
 385  *
 386  * When called, this will automatically also call __ast_sorcery_apply_config()
 387  * with the module name as the configuration section.
 388  *
 389  * \retval non-NULL success
 390  * \retval NULL if allocation failed
 391  */
 392 struct ast_sorcery *__ast_sorcery_open(const char *module);
 393
 394 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE)
 395
 396 /*!
 397  * \brief Retrieves an existing sorcery instance by module name
 398  *
 399  * \param module The module name
 400  *
 401  * \retval non-NULL success
 402  * \retval NULL if no instance was found
 403  *
 404  * \note The returned instance has its reference count incremented.  The caller
 405  * must decrement the count when they're finished with it.
 406  *
 407  */
 408 struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
 409
 410 enum ast_sorcery_apply_result {
 411         /*! Sorcery wizard failed to apply. */
 412         AST_SORCERY_APPLY_FAIL = -1,
 413         /*! Sorcery wizard applied successfully. */
 414         AST_SORCERY_APPLY_SUCCESS = 0,
 415         /*! Sorcery wizard has already been applied to the object type. */
 416         AST_SORCERY_APPLY_DUPLICATE = 1,
 417         /*! Default sorcery wizard is unnecessary since a wizard has already been applied to the object type. */
 418         AST_SORCERY_APPLY_DEFAULT_UNNECESSARY = 2,
 419         /*! No sorcery.conf configuration file was found to apply. */
 420         AST_SORCERY_APPLY_NO_CONFIGURATION = 3,
 421 };
 422
 423 /*!
 424  * \brief Apply configured wizard mappings
 425  *
 426  * \param sorcery Pointer to a sorcery structure
 427  * \param name Name of the category to use within the configuration file, normally the module name
 428  * \param module The module name (AST_MODULE)
 429  *
 430  * This function is called automatically by __ast_sorcery_open() using the module name as the
 431  * configuration category. The only reason you should call this function is if your module
 432  * wishes to apply configuration from additional sections of sorcery.conf.
 433  *
 434  * If a configuration section attempts to apply the same sorcery wizard to an object type
 435  * more than once, the wizard will only be applied one time.
 436  *
 437  * \return What happened when attempting to apply the config.
 438  */
 439 enum ast_sorcery_apply_result __ast_sorcery_apply_config(struct ast_sorcery *sorcery,
 440                 const char *name, const char *module);
 441
 442 #define ast_sorcery_apply_config(sorcery, name) \
 443         __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
 444
 445 /*!
 446  * \brief Apply default object wizard mappings
 447  *
 448  * \param sorcery Pointer to a sorcery structure
 449  * \param type Type of object to apply to
 450  * \param module The name of the module, typically AST_MODULE
 451  * \param name Name of the wizard to use
 452  * \param data Data to be passed to wizard
 453  *
 454  * \return What occurred when applying the default
 455  *
 456  * \note This should be called *after* applying configuration sourced mappings
 457  *
 458  * \note Only a single default can exist per object type
 459  */
 460 enum ast_sorcery_apply_result __ast_sorcery_apply_default(struct ast_sorcery *sorcery,
 461                 const char *type, const char *module, const char *name, const char *data);
 462
 463 #define ast_sorcery_apply_default(sorcery, type, name, data) \
 464         __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
 465
 466
 467 /*!
 468  * \brief Apply additional object wizard mappings
 469  *
 470  * \param sorcery Pointer to a sorcery structure
 471  * \param type Type of object to apply to
 472  * \param module The name of the module, typically AST_MODULE
 473  * \param name Name of the wizard to use
 474  * \param data Data to be passed to wizard
 475  * \param caching Wizard should cache
 476  *
 477  * \return What occurred when applying the mapping
 478  *
 479  * \note This should be called *after* applying default mappings
 480  */
 481 enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping(struct ast_sorcery *sorcery,
 482                 const char *type, const char *module, const char *name, const char *data, unsigned int caching);
 483
 484 /*!
 485  * \brief Apply additional object wizard mappings
 486  *
 487  * \param sorcery Pointer to a sorcery structure
 488  * \param type Type of object to apply to
 489  * \param module The name of the module, typically AST_MODULE
 490  * \param name Name of the wizard to use
 491  * \param data Data to be passed to wizard
 492  *
 493  * \return What occurred when applying the mapping
 494  *
 495  * \note This should be called *after* applying default mappings
 496  */
 497 #define ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching) \
 498         __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching));
 499
 500
 501 /*!
 502  * \brief Pre-defined locations to insert at
 503  */
 504 enum ast_sorcery_wizard_position {
 505         AST_SORCERY_WIZARD_POSITION_LAST = -1,
 506         AST_SORCERY_WIZARD_POSITION_FIRST = 0,
 507 };
 508
 509 /*!
 510  * \brief Insert an additional object wizard mapping at a specific position
 511  * in the wizard list
 512  *
 513  * \param sorcery Pointer to a sorcery structure
 514  * \param type Type of object to apply to
 515  * \param module The name of the module, typically AST_MODULE
 516  * \param name Name of the wizard to use
 517  * \param data Data to be passed to wizard
 518  * \param caching Wizard should cache
 519  * \param position An index to insert to or one of ast_sorcery_wizard_position
 520  *
 521  * \return What occurred when applying the mapping
 522  *
 523  * \note This should be called *after* applying default mappings
 524  * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count
 525  * and iterating over them using ast_sorcery_get_wizard_mapping.
 526  *
 527  * \since 13.4.0
 528  */
 529 enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sorcery *sorcery,
 530         const char *type, const char *module, const char *name, const char *data,
 531         unsigned int caching, int position);
 532
 533 /*!
 534  * \brief Insert an additional object wizard mapping at a specific position
 535  * in the wizard list
 536  *
 537  * \param sorcery Pointer to a sorcery structure
 538  * \param type Type of object to apply to
 539  * \param module The name of the module, typically AST_MODULE
 540  * \param name Name of the wizard to use
 541  * \param data Data to be passed to wizard
 542  * \param position One of ast_sorcery_wizard_position
 543  *
 544  * \return What occurred when applying the mapping
 545  *
 546  * \note This should be called *after* applying default mappings
 547  * \since 13.4.0
 548  */
 549 #define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \
 550         __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \
 551                 (caching), (position))
 552
 553 /*!
 554  * \brief Remove an object wizard mapping
 555  *
 556  * \param sorcery Pointer to a sorcery structure
 557  * \param type Type of object to remove from
 558  * \param module The name of the module, typically AST_MODULE
 559  * \param name The name of the wizard to remove
 560  *
 561  * \retval 0 success
 562  * \retval -1 failure
 563  *
 564  * \since 13.4.0
 565  */
 566 int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery,
 567         const char *type, const char *module, const char *name);
 568
 569 /*!
 570  * \brief Remove an object wizard mapping
 571  *
 572  * \param sorcery Pointer to a sorcery structure
 573  * \param type Type of object to remove from
 574  * \param name The name of the wizard to remove
 575  *
 576  * \retval 0 success
 577  * \retval -1 failure
 578  *
 579  * \since 13.4.0
 580  */
 581 #define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \
 582         __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name))
 583
 584 /*!
 585  * \brief Return the number of wizards mapped to an object type
 586  *
 587  * \param sorcery Pointer to a sorcery structure
 588  * \param type Type of object
 589  *
 590  * \return Number of wizards or -1 for error
 591  * \since 13.4.0
 592  */
 593 int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery,
 594         const char *type);
 595
 596 /*!
 597  * \brief By index, return a wizard mapped to an object type
 598  *
 599  * \param sorcery Pointer to a sorcery structure
 600  * \param type Type of object
 601  * \param index Index of the wizard
 602  * \param wizard A pointer to receive the wizard pointer
 603  * \param data A pointer to receive the data pointer
 604  *
 605  * \retval 0 success
 606  * \retval -1 failure
 607  *
 608  * \warning The wizard will have its reference count bumped so you must
 609  * call ao2_cleanup when you're done with it.
 610  *
 611  * \note The wizard and data returned are valid only for this object type
 612  * and only while the wizard is applied to the object type.
 613  *
 614  * \since 13.4.0
 615  */
 616 int ast_sorcery_get_wizard_mapping(struct ast_sorcery *sorcery,
 617         const char *type, int index, struct ast_sorcery_wizard **wizard, void **data);
 618
 619 /*!
 620  * \brief Register an object type
 621  *
 622  * \param sorcery Pointer to a sorcery structure
 623  * \param type Type of object
 624  * \param hidden All objects of this type are internal and should not be manipulated by users
 625  * \param reloadable All objects of this type are reloadable
 626  * \param alloc Required object allocation callback
 627  * \param transform Optional transformation callback
 628  * \param apply Optional object set apply callback
 629  *
 630  * \note In general, this function should not be used directly. One of the various
 631  * macro'd versions should be used instead.
 632  *
 633  * \retval 0 success
 634  * \retval -1 failure
 635  */
 636 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);
 637
 638 /*!
 639  * \brief Register an object type
 640  *
 641  * \param sorcery Pointer to a sorcery structure
 642  * \param type Type of object
 643  * \param alloc Required object allocation callback
 644  * \param transform Optional transformation callback
 645  * \param apply Optional object set apply callback
 646  *
 647  * \retval 0 success
 648  * \retval -1 failure
 649  */
 650 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
 651         __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
 652
 653 /*!
 654  * \brief Register an object type that is not reloadable
 655  *
 656  * \param sorcery Pointer to a sorcery structure
 657  * \param type Type of object
 658  * \param alloc Required object allocation callback
 659  * \param transform Optional transformation callback
 660  * \param apply Optional object set apply callback
 661  *
 662  * \retval 0 success
 663  * \retval -1 failure
 664  */
 665 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
 666         __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
 667
 668 /*!
 669  * \brief Register an internal, hidden object type
 670  *
 671  * \param sorcery Pointer to a sorcery structure
 672  * \param type Type of object
 673  * \param alloc Required object allocation callback
 674  * \param transform Optional transformation callback
 675  * \param apply Optional object set apply callback
 676  *
 677  * \retval 0 success
 678  * \retval -1 failure
 679  */
 680 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
 681         __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
 682
 683 /*!
 684  * \brief Set the copy handler for an object type
 685  *
 686  * \param sorcery Pointer to a sorcery structure
 687  * \param type Type of object
 688  * \param copy Copy handler
 689  */
 690 void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
 691
 692 /*!
 693  * \brief Set the diff handler for an object type
 694  *
 695  * \param sorcery Pointer to a sorcery structure
 696  * \param type Type of object
 697  * \param diff Diff handler
 698  */
 699 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
 700
 701 /*!
 702  * \brief Register a regex for multiple fields within an object
 703  *
 704  * \param sorcery Pointer to a sorcery structure
 705  * \param type Type of object
 706  * \param regex A regular expression pattern for the fields
 707  * \param config_handler A custom handler for translating the string representation of the fields
 708  * \param sorcery_handler A custom handler for translating the native representation of the fields
 709  *
 710  * \retval 0 success
 711  * \retval -1 failure
 712  */
 713 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
 714                                                                            sorcery_fields_handler sorcery_handler);
 715
 716 /*!
 717  * \brief Register a field within an object
 718  *
 719  * \param sorcery Pointer to a sorcery structure
 720  * \param type Type of object
 721  * \param name Name of the field
 722  * \param default_val Default value of the field
 723  * \param config_handler A custom handler for translating the string representation of the fields
 724  * \param sorcery_handler A custom handler for translating the native representation of the fields
 725  * \param multiple_handler A custom handler for translating the native representation of the fields
 726  * \param opt_type Option type
 727  * \param flags Option type specific flags
 728  * \param no_doc Field should not be documented
 729  * \param alias Interpret and apply field value only
 730  *
 731  * \retval 0 success
 732  * \retval -1 failure
 733  */
 734 int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type,
 735         const char *name, const char *default_val, enum aco_option_type opt_type,
 736         aco_option_handler config_handler, sorcery_field_handler sorcery_handler,
 737         sorcery_fields_handler multiple_handler, unsigned int flags, unsigned int no_doc,
 738         unsigned int alias, size_t argc, ...);
 739
 740 /*!
 741  * \brief Register a field within an object
 742  *
 743  * \param sorcery Pointer to a sorcery structure
 744  * \param type Type of object
 745  * \param name Name of the field
 746  * \param default_val Default value of the field
 747  * \param opt_type Option type
 748  * \param flags Option type specific flags
 749  *
 750  * \retval 0 success
 751  * \retval -1 failure
 752  */
 753 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
 754     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 0, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 755
 756 /*!
 757  * \brief Register a field within an object as an alias
 758  *
 759  * \param sorcery Pointer to a sorcery structure
 760  * \param type Type of object
 761  * \param name Name of the field
 762  * \param default_val Default value of the field
 763  * \param opt_type Option type
 764  * \param flags Option type specific flags
 765  *
 766  * \retval 0 success
 767  * \retval -1 failure
 768  */
 769 #define ast_sorcery_object_field_register_alias(sorcery, type, name, default_val, opt_type, flags, ...) \
 770     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 771
 772 /*!
 773  * \brief Register a field within an object without documentation
 774  *
 775  * \param sorcery Pointer to a sorcery structure
 776  * \param type Type of object
 777  * \param name Name of the field
 778  * \param default_val Default value of the field
 779  * \param opt_type Option type
 780  * \param flags Option type specific flags
 781  *
 782  * \retval 0 success
 783  * \retval -1 failure
 784  */
 785 #define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
 786     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, NULL, flags, 1, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 787
 788 /*!
 789  * \brief Register a field within an object with custom handlers
 790  *
 791  * \param sorcery Pointer to a sorcery structure
 792  * \param type Type of object
 793  * \param name Name of the field
 794  * \param default_val Default value of the field
 795  * \param config_handler Custom configuration handler
 796  * \param sorcery_handler Custom sorcery handler
 797  * \param multiple_handler Custom multiple handler
 798  * \param flags Option type specific flags
 799  *
 800  * \retval 0 success
 801  * \retval -1 failure
 802  */
 803 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
 804     __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__);
 805
 806 /*!
 807  * \brief Register a field within an object with custom handlers as an alias
 808  *
 809  * \param sorcery Pointer to a sorcery structure
 810  * \param type Type of object
 811  * \param name Name of the field
 812  * \param default_val Default value of the field
 813  * \param config_handler Custom configuration handler
 814  * \param sorcery_handler Custom sorcery handler
 815  * \param flags Option type specific flags
 816  *
 817  * \retval 0 success
 818  * \retval -1 failure
 819  */
 820 #define ast_sorcery_object_field_register_custom_alias(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
 821     __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__);
 822
 823 /*!
 824  * \brief Register a field within an object with custom handlers without documentation
 825  *
 826  * \param sorcery Pointer to a sorcery structure
 827  * \param type Type of object
 828  * \param name Name of the field
 829  * \param default_val Default value of the field
 830  * \param config_handler Custom configuration handler
 831  * \param sorcery_handler Custom sorcery handler
 832  * \param multiple_handler Custom multiple handler
 833  * \param flags Option type specific flags
 834  *
 835  * \retval 0 success
 836  * \retval -1 failure
 837  */
 838 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, multiple_handler, flags, ...) \
 839     __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__);
 840
 841 /*!
 842  * \brief Inform any wizards to load persistent objects
 843  *
 844  * \param sorcery Pointer to a sorcery structure
 845  */
 846 void ast_sorcery_load(const struct ast_sorcery *sorcery);
 847
 848 /*!
 849  * \brief Inform any wizards of a specific object type to load persistent objects
 850  *
 851  * \param sorcery Pointer to a sorcery structure
 852  * \param type Name of the object type to load
 853  */
 854 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
 855
 856 /*!
 857  * \brief Inform any wizards to reload persistent objects
 858  *
 859  * \param sorcery Pointer to a sorcery structure
 860  */
 861 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
 862
 863 /*!
 864  * \brief Inform any wizards of a specific object type to reload persistent objects
 865  *
 866  * \param sorcery Pointer to a sorcery structure
 867  * \param type Name of the object type to reload
 868  */
 869 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
 870
 871 /*!
 872  * \brief Increase the reference count of a sorcery structure
 873  *
 874  * \param sorcery Pointer to a sorcery structure
 875  */
 876 void ast_sorcery_ref(struct ast_sorcery *sorcery);
 877
 878
 879 /*!
 880  * \brief Create an object set (KVP list) for an object
 881  *
 882  * \param sorcery Pointer to a sorcery structure
 883  * \param object Pointer to a sorcery object
 884  * \param flags Flags indicating which handler to use and in what order.
 885  *
 886  * \retval non-NULL success
 887  * \retval NULL if error occurred
 888  *
 889  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
 890  */
 891 struct ast_variable *ast_sorcery_objectset_create2(const struct ast_sorcery *sorcery,
 892         const void *object, enum ast_sorcery_field_handler_flags flags);
 893
 894 /*!
 895  * \brief Create an object set (KVP list) for an object
 896  *
 897  * \param sorcery Pointer to a sorcery structure
 898  * \param object Pointer to a sorcery object
 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  * \note This function attempts to use a field's sorcery_fields_handler first and if that
 906  * doesn't exist or fails, a field's sorcery_field_handler is used.  The difference is
 907  * that the former may return multiple list entries for the same field and the latter will only
 908  * return 1.  It's up to the field itself to determine what the appropriate content is.
 909  */
 910 #define ast_sorcery_objectset_create(sorcery, object) \
 911         ast_sorcery_objectset_create2(sorcery, object, AST_HANDLER_PREFER_LIST)
 912
 913 /*!
 914  * \brief Create an object set in JSON format for an object
 915  *
 916  * \param sorcery Pointer to a sorcery structure
 917  * \param object Pointer to a sorcery object
 918  *
 919  * \retval non-NULL success
 920  * \retval NULL if error occurred
 921  *
 922  * \note The returned ast_json object must be unreferenced using ast_json_unref
 923  */
 924 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
 925
 926 /*!
 927  * \brief Apply an object set (KVP list) to an object
 928  *
 929  * \param sorcery Pointer to a sorcery structure
 930  * \param object Pointer to a sorcery object
 931  * \param objectset Object set itself
 932  *
 933  * \retval 0 success
 934  * \retval -1 failure
 935  *
 936  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
 937  *       applied object set.
 938  */
 939 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
 940
 941 /*!
 942  * \brief Create a changeset given two object sets
 943  *
 944  * \param original Original object set
 945  * \param modified Modified object set
 946  * \param changes Pointer to hold any changes between the object sets
 947  *
 948  * \retval 0 success
 949  * \retval -1 failure
 950  *
 951  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
 952  */
 953 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
 954
 955 /*!
 956  * \brief Allocate a generic sorcery capable object
 957  *
 958  * \param size Size of the object
 959  * \param destructor Optional destructor function
 960  *
 961  * \retval non-NULL success
 962  * \retval NULL failure
 963  */
 964 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
 965
 966 /*!
 967  * \brief Allocate an object
 968  *
 969  * \param sorcery Pointer to a sorcery structure
 970  * \param type Type of object to allocate
 971  * \param id Optional unique identifier, if none is provided one will be generated
 972  *
 973  * \retval non-NULL success
 974  * \retval NULL failure
 975  */
 976 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
 977
 978 /*!
 979  * \brief Create a copy of an object
 980  *
 981  * \param sorcery Pointer to a sorcery structure
 982  * \param object Existing object
 983  *
 984  * \retval non-NULL success
 985  * \retval NULL failure
 986  */
 987 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
 988
 989 /*!
 990  * \brief Create a changeset of two objects
 991  *
 992  * \param sorcery Pointer to a sorcery structure
 993  * \param original Original object
 994  * \param modified Modified object
 995  * \param changes Pointer which will be populated with changes if any exist
 996  *
 997  * \retval 0 success
 998  * \retval -1 failure
 999  *
1000  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
1001  *
1002  * \note While the objects must be of the same type they do not have to be the same object
1003  */
1004 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
1005
1006 /*!
1007  * \brief Add a global observer to sorcery
1008  *
1009  * \param callbacks Implementation of the global observer interface
1010  *
1011  * \retval 0 success
1012  * \retval -1 failure
1013  *
1014  * \note You must be ready to accept observer invocations before this function is called
1015  */
1016 int ast_sorcery_global_observer_add(const struct ast_sorcery_global_observer *callbacks);
1017
1018 /*!
1019  * \brief Remove a global observer from sorcery.
1020  *
1021  * A global observer is notified...
1022  * After a new wizard is registered.
1023  * After a new sorcery instance is opened.
1024  * Before an instance is destroyed.
1025  * Before a wizard is unregistered.
1026  *
1027  * \param callbacks Implementation of the global observer interface
1028  */
1029 void ast_sorcery_global_observer_remove(const struct ast_sorcery_global_observer *callbacks);
1030
1031 /*!
1032  * \brief Add an observer to a sorcery instance
1033  *
1034  * \param sorcery Pointer to a sorcery structure
1035  * \param callbacks Implementation of the instance observer interface
1036  *
1037  * An instance observer is notified...
1038  * Before an instance is loaded or reloaded.
1039  * After an instance is loaded or reloaded.
1040  * After a wizard is mapped to an object type.
1041  * After an object type is registered.
1042  * Before an object type is loaded or reloaded.
1043  * After an object type is loaded or reloaded.
1044  *
1045  * \retval 0 success
1046  * \retval -1 failure
1047  *
1048  * \note You must be ready to accept observer invocations before this function is called
1049  */
1050 int ast_sorcery_instance_observer_add(struct ast_sorcery *sorcery,
1051         const struct ast_sorcery_instance_observer *callbacks);
1052
1053 /*!
1054  * \brief Remove an observer from a sorcery instance
1055  *
1056  * \param sorcery Pointer to a sorcery structure
1057  * \param callbacks Implementation of the instance observer interface
1058  */
1059 void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery,
1060         const struct ast_sorcery_instance_observer *callbacks);
1061
1062 /*!
1063  * \brief Add an observer to a sorcery wizard
1064  *
1065  * \param sorcery Pointer to a previously registered wizard structure
1066  * \param callbacks Implementation of the wizard observer interface
1067  *
1068  * A wizard observer is notified...
1069  * Before a wizard is loaded or reloaded.
1070  * After a wizard is loaded or reloaded.
1071  *
1072  * \retval 0 success
1073  * \retval -1 failure
1074  *
1075  * \note You must be ready to accept observer invocations before this function is called
1076  */
1077 int ast_sorcery_wizard_observer_add(struct ast_sorcery_wizard *wizard,
1078         const struct ast_sorcery_wizard_observer *callbacks);
1079
1080 /*!
1081  * \brief Remove an observer from a sorcery wizard.
1082  *
1083  * \param sorcery Pointer to a sorcery structure
1084  * \param callbacks Implementation of the wizard observer interface
1085  */
1086 void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *wizard,
1087         const struct ast_sorcery_wizard_observer *callbacks);
1088
1089 /*!
1090  * \brief Add an observer to a specific object type
1091  *
1092  * \param sorcery Pointer to a sorcery structure
1093  * \param type Type of object that should be observed
1094  * \param callbacks Implementation of the observer interface
1095  *
1096  * \retval 0 success
1097  * \retval -1 failure
1098  *
1099  * \note You must be ready to accept observer invocations before this function is called
1100  */
1101 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1102
1103 /*!
1104  * \brief Remove an observer from a specific object type
1105  *
1106  * \param sorcery Pointer to a sorcery structure
1107  * \param type Type of object that should no longer be observed
1108  * \param callbacks Implementation of the observer interface
1109  *
1110  * \retval 0 success
1111  * \retval -1 failure
1112  */
1113 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
1114
1115 /*!
1116  * \brief Create and potentially persist an object using an available wizard
1117  *
1118  * \param sorcery Pointer to a sorcery structure
1119  * \param object Pointer to a sorcery object
1120  *
1121  * \retval 0 success
1122  * \retval -1 failure
1123  */
1124 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
1125
1126 /*!
1127  * \brief Retrieve an object using its unique identifier
1128  *
1129  * \param sorcery Pointer to a sorcery structure
1130  * \param type Type of object to retrieve
1131  * \param id Unique object identifier
1132  *
1133  * \retval non-NULL if found
1134  * \retval NULL if not found
1135  */
1136 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
1137
1138 /*!
1139  * \brief Retrieve an object or multiple objects using specific fields
1140  *
1141  * \param sorcery Pointer to a sorcery structure
1142  * \param type Type of object to retrieve
1143  * \param flags Flags to control behavior
1144  * \param fields Optional object fields and values to match against
1145  *
1146  * \retval non-NULL if found
1147  * \retval NULL if not found
1148  *
1149  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
1150  *       ao2_container that must be unreferenced after use.
1151  *
1152  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
1153  *       of the given type.
1154  */
1155 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
1156
1157 /*!
1158  * \brief Retrieve multiple objects using a regular expression on their id
1159  *
1160  * \param sorcery Pointer to a sorcery structure
1161  * \param type Type of object to retrieve
1162  * \param regex Regular expression
1163  *
1164  * \retval non-NULL if error occurs
1165  * \retval NULL success
1166  *
1167  * \note The provided regex is treated as extended case sensitive.
1168  */
1169 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
1170
1171 /*!
1172  * \brief Update an object
1173  *
1174  * \param sorcery Pointer to a sorcery structure
1175  * \param object Pointer to a sorcery object
1176  *
1177  * \retval 0 success
1178  * \retval -1 failure
1179  */
1180 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
1181
1182 /*!
1183  * \brief Delete an object
1184  *
1185  * \param sorcery Pointer to a sorcery structure
1186  * \param object Pointer to a sorcery object
1187  *
1188  * \retval 0 success
1189  * \retval -1 failure
1190  */
1191 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
1192
1193 /*!
1194  * \brief Decrease the reference count of a sorcery structure
1195  *
1196  * \param sorcery Pointer to a sorcery structure
1197  */
1198 void ast_sorcery_unref(struct ast_sorcery *sorcery);
1199
1200 /*!
1201  * \brief Get the unique identifier of a sorcery object
1202  *
1203  * \param object Pointer to a sorcery object
1204  *
1205  * \retval unique identifier
1206  */
1207 const char *ast_sorcery_object_get_id(const void *object);
1208
1209 /*!
1210  * \brief Get the type of a sorcery object
1211  *
1212  * \param object Pointer to a sorcery object
1213  *
1214  * \retval type of object
1215  */
1216 const char *ast_sorcery_object_get_type(const void *object);
1217
1218 /*!
1219  * \brief Get an extended field value from a sorcery object
1220  *
1221  * \param object Pointer to a sorcery object
1222  * \param name Name of the extended field value
1223  *
1224  * \retval non-NULL if found
1225  * \retval NULL if not found
1226  *
1227  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
1228  */
1229 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
1230
1231 /*!
1232  * \brief Set an extended field value on a sorcery object
1233  *
1234  * \param object Pointer to a sorcery object
1235  * \param name Name of the extended field
1236  * \param value Value of the extended field
1237  *
1238  * \retval 0 success
1239  * \retval -1 failure
1240  *
1241  * \note The field name MUST begin with '@' to indicate it is an extended field.
1242  * \note If the extended field already exists it will be overwritten with the new value.
1243  */
1244 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
1245
1246 /*!
1247  * \brief ao2 object comparator based on sorcery id.
1248  */
1249 int ast_sorcery_object_id_compare(void *obj, void *arg, int flags);
1250
1251 /*!
1252  * \brief ao2 object sorter based on sorcery id.
1253  */
1254 int ast_sorcery_object_id_sort(const void *obj, const void *arg, int flags);
1255
1256 /*!
1257  * \brief ao2 object hasher based on sorcery id.
1258  */
1259 int ast_sorcery_object_id_hash(const void *obj, int flags);
1260
1261 /*!
1262  * \brief Get the sorcery object type given a type name.
1263  *
1264  * \param sorcery The sorcery from which to retrieve the object type
1265  * \param type The type name
1266  */
1267 struct ast_sorcery_object_type *ast_sorcery_get_object_type(const struct ast_sorcery *sorcery,
1268                 const char *type);
1269
1270 /*!
1271  * \brief Determine if a particular object field has been registered with sorcery
1272  *
1273  * \param object_type The object type to check against
1274  * \param field_name The name of the field to check
1275  *
1276  * \retval 0 The field is not registered for this sorcery type
1277  * \retval 1 The field is registered for this sorcery type
1278  */
1279 int ast_sorcery_is_object_field_registered(const struct ast_sorcery_object_type *object_type,
1280                 const char *field_name);
1281
1282 /*!
1283  * \brief Get the module that has opened the provided sorcery instance.
1284  *
1285  * \param sorcery The sorcery instance
1286  *
1287  * \return The module
1288  */
1289 const char *ast_sorcery_get_module(const struct ast_sorcery *sorcery);
1290
1291 #if defined(__cplusplus) || defined(c_plusplus)
1292 }
1293 #endif
1294
1295 #endif /* _ASTERISK_SORCERY_H */