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. If the storage of the object types are such that a default wizard can be used this can
  43  * be applied using the \ref ast_sorcery_apply_default API call. Note that the default mappings will not
  44  * override configured mappings. They are only used in the case where no configured mapping exists.
  45  *
  46  * Configuring object mappings implicitly creates a basic version of an object type. The object type
  47  * must be fully registered, however, using the \ref ast_sorcery_object_register API call before any
  48  * objects of the type can be allocated, created, or retrieved.
  49  *
  50  * Once the object type itself has been fully registered the individual fields within the object must
  51  * be registered using the \ref ast_sorcery_object_field_register API call. Note that not all fields *need*
  52  * be registered. Only fields that should be accessible using the sorcery API have to be registered.
  53  *
  54  * \par Creating Objects
  55  *
  56  * Before an object can be created within the sorcery API it must first be allocated using the
  57  * \ref ast_sorcery_alloc API call. This allocates a new instance of the object, sets sorcery specific
  58  * details, and applies default values to the object. A unique identifier can optionally be specified
  59  * when allocating an object. If it is not provided one will be automatically generated. Allocating
  60  * an object does not create it within any object storage mechanisms that are configured for the
  61  * object type. Creation must explicitly be done using the \ref ast_sorcery_create API call. This API call
  62  * passes the object to each configured object storage mechanism for the object type until one
  63  * successfully persists the object.
  64  *
  65  * \par Retrieving Objects
  66  *
  67  * To retrieve a single object using its unique identifier the \ref ast_sorcery_retrieve_by_id API call
  68  * can be used.
  69  *
  70  * To retrieve potentially multiple objects using specific fields the \ref ast_sorcery_retrieve_by_fields
  71  * API call can be used. The behavior of this API call is controlled using different flags. If the
  72  * AST_RETRIEVE_FLAG_MULTIPLE flag is used a container will be returned which contains all matching objects.
  73  * To retrieve all objects the AST_RETRIEVE_FLAG_ALL flag can be specified. Note that when specifying this flag
  74  * you do not need to pass any fields.
  75  *
  76  * Both API calls return shared objects. Modification of the object can not occur until it has been copied.
  77  *
  78  * \par Updating Objects
  79  *
  80  * As retrieved objects may be shared the first step to updating the object with new details is creating a
  81  * copy using the \ref ast_sorcery_copy API call. This will return a new object which is specific to the caller.
  82  * Any field within the object may be modified as needed. Once changes are done the changes can be committed
  83  * using the \ref ast_sorcery_update API call. Note that as the copied object is specific to the caller it must
  84  * be unreferenced after use.
  85  *
  86  * \par Deleting Objects
  87  *
  88  * To delete an object simply call the \ref ast_sorcery_delete API call with an object retrieved using the
  89  * ast_sorcery_retrieve_by_* API calls or a copy returned from \ref ast_sorcery_copy.
  90  */
  91
  92 #ifndef _ASTERISK_SORCERY_H
  93 #define _ASTERISK_SORCERY_H
  94
  95 #if defined(__cplusplus) || defined(c_plusplus)
  96 extern "C" {
  97 #endif
  98
  99 #include "asterisk/config_options.h"
 100 #include "asterisk/uuid.h"
 101
 102 /*! \brief Maximum size of an object type */
 103 #define MAX_OBJECT_TYPE 64
 104
 105 /*! \brief Maximum length of an object field name */
 106 #define MAX_OBJECT_FIELD 128
 107
 108 /*!
 109  * \brief Retrieval flags
 110  */
 111 enum ast_sorcery_retrieve_flags {
 112         /*! \brief Default retrieval flags */
 113         AST_RETRIEVE_FLAG_DEFAULT = 0,
 114
 115         /*! \brief Return all matching objects */
 116         AST_RETRIEVE_FLAG_MULTIPLE = (1 << 0),
 117
 118         /*! \brief Perform no matching, return all objects */
 119         AST_RETRIEVE_FLAG_ALL = (1 << 1),
 120 };
 121
 122 /*! \brief Forward declaration for the sorcery main structure */
 123 struct ast_sorcery;
 124
 125 /*!
 126  * \brief A callback function for translating a value into a string
 127  *
 128  * \param obj Object to get value from
 129  * \param args Where the field is
 130  * \param buf Pointer to the buffer that the handler has created which contains the field value
 131  *
 132  * \retval 0 success
 133  * \retval -1 failure
 134  */
 135 typedef int (*sorcery_field_handler)(const void *obj, const intptr_t *args, char **buf);
 136
 137 /*!
 138  * \brief A callback function for translating multiple values into an ast_variable list
 139  *
 140  * \param obj Object to get values from
 141  * \param fields Pointer to store the list of fields
 142  *
 143  * \retval 0 success
 144  * \retval -1 failure
 145  */
 146 typedef int (*sorcery_fields_handler)(const void *obj, struct ast_variable **fields);
 147
 148 /*!
 149  * \brief A callback function for performing a transformation on an object set
 150  *
 151  * \param set The existing object set
 152  *
 153  * \retval non-NULL new object set if changed
 154  * \retval NULL if no changes present
 155  *
 156  * \note The returned ast_variable list must be *new*. You can not return the input set.
 157  */
 158 typedef struct ast_variable *(*sorcery_transform_handler)(struct ast_variable *set);
 159
 160 /*!
 161  * \brief A callback function for when an object set is successfully applied to an object
 162  *
 163  * \note On a failure return, the state of the object is left undefined. It is a bad
 164  * idea to try to use this object.
 165  *
 166  * \param sorcery Sorcery structure in use
 167  * \param obj The object itself
 168  * \retval 0 Success
 169  * \retval non-zero Failure
 170  */
 171 typedef int (*sorcery_apply_handler)(const struct ast_sorcery *sorcery, void *obj);
 172
 173 /*!
 174  * \brief A callback function for copying the contents of one object to another
 175  *
 176  * \param src The source object
 177  * \param dst The destination object
 178  *
 179  * \retval 0 success
 180  * \retval -1 failure
 181  */
 182 typedef int (*sorcery_copy_handler)(const void *src, void *dst);
 183
 184 /*!
 185  * \brief A callback function for generating a changeset between two objects
 186  *
 187  * \param original The original object
 188  * \param modified The modified object
 189  * \param changes The changeset
 190  *
 191  * \param 0 success
 192  * \param -1 failure
 193  */
 194 typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
 195
 196 /*! \brief Interface for a sorcery wizard */
 197 struct ast_sorcery_wizard {
 198         /*! \brief Name of the wizard */
 199         const char *name;
 200
 201         /*! \brief Pointer to the Asterisk module this wizard is implemented by */
 202         struct ast_module *module;
 203
 204         /*! \brief Callback for opening a wizard */
 205         void *(*open)(const char *data);
 206
 207         /*! \brief Optional callback for loading persistent objects */
 208         void (*load)(void *data, const struct ast_sorcery *sorcery, const char *type);
 209
 210         /*! \brief Optional callback for reloading persistent objects */
 211         void (*reload)(void *data, const struct ast_sorcery *sorcery, const char *type);
 212
 213         /*! \brief Callback for creating an object */
 214         int (*create)(const struct ast_sorcery *sorcery, void *data, void *object);
 215
 216         /*! \brief Callback for retrieving an object using an id */
 217         void *(*retrieve_id)(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
 218
 219         /*! \brief Callback for retrieving multiple objects using a regex on their id */
 220         void (*retrieve_regex)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
 221
 222         /*! \brief Optional callback for retrieving an object using fields */
 223         void *(*retrieve_fields)(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
 224
 225         /*! \brief Optional callback for retrieving multiple objects using some optional field criteria */
 226         void (*retrieve_multiple)(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields);
 227
 228         /*! \brief Callback for updating an object */
 229         int (*update)(const struct ast_sorcery *sorcery, void *data, void *object);
 230
 231         /*! \brief Callback for deleting an object */
 232         int (*delete)(const struct ast_sorcery *sorcery, void *data, void *object);
 233
 234         /*! \brief Callback for closing a wizard */
 235         void (*close)(void *data);
 236 };
 237
 238 /*! \brief Interface for a sorcery object type observer */
 239 struct ast_sorcery_observer {
 240         /*! \brief Callback for when an object is created */
 241         void (*created)(const void *object);
 242
 243         /*! \brief Callback for when an object is updated */
 244         void (*updated)(const void *object);
 245
 246         /*! \brief Callback for when an object is deleted */
 247         void (*deleted)(const void *object);
 248
 249         /*! \brief Callback for when an object type is loaded/reloaded */
 250         void (*loaded)(const char *object_type);
 251 };
 252
 253 /*! \brief Opaque structure for internal sorcery object */
 254 struct ast_sorcery_object;
 255
 256 /*! \brief Structure which contains details about a sorcery object */
 257 struct ast_sorcery_object_details {
 258         /*! \brief Pointer to internal sorcery object information */
 259         struct ast_sorcery_object *object;
 260 };
 261
 262 /*! \brief Macro which must be used at the beginning of each sorcery capable object */
 263 #define SORCERY_OBJECT(details)                    \
 264 struct {                                           \
 265         struct ast_sorcery_object_details details; \
 266 }                                                  \
 267
 268 /*!
 269  * \brief Initialize the sorcery API
 270  *
 271  * \retval 0 success
 272  * \retval -1 failure
 273  */
 274 int ast_sorcery_init(void);
 275
 276 /*!
 277  * \brief Register a sorcery wizard
 278  *
 279  * \param interface Pointer to a wizard interface
 280  * \param module Pointer to the module implementing the interface
 281  *
 282  * \retval 0 success
 283  * \retval -1 failure
 284  */
 285 int __ast_sorcery_wizard_register(const struct ast_sorcery_wizard *interface, struct ast_module *module);
 286
 287 /*!
 288  * \brief See \ref __ast_sorcery_wizard_register()
 289  */
 290 #define ast_sorcery_wizard_register(interface) __ast_sorcery_wizard_register(interface, ast_module_info ? ast_module_info->self : NULL)
 291
 292 /*!
 293  * \brief Unregister a sorcery wizard
 294  *
 295  * \param interface Pointer to the wizard interface
 296  *
 297  * \retval 0 success
 298  * \retval -1 failure
 299  */
 300 int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
 301
 302 /*!
 303  * \brief Open a new sorcery structure
 304  *
 305  * \param module The module name (AST_MODULE)
 306  *
 307  * \retval non-NULL success
 308  * \retval NULL if allocation failed
 309  */
 310 struct ast_sorcery *__ast_sorcery_open(const char *module);
 311
 312 #define ast_sorcery_open() __ast_sorcery_open(AST_MODULE)
 313
 314 /*!
 315  * \brief Retrieves an existing sorcery instance by module name
 316  *
 317  * \param module The module name
 318  *
 319  * \retval non-NULL success
 320  * \retval NULL if no instance was found
 321  *
 322  * \note The returned instance has its reference count incremented.  The caller
 323  * must decrement the count when they're finished with it.
 324  *
 325  */
 326 struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
 327
 328 /*!
 329  * \brief Apply configured wizard mappings
 330  *
 331  * \param sorcery Pointer to a sorcery structure
 332  * \param name Name of the category to use within the configuration file, normally the module name
 333  * \param module The module name (AST_MODULE)
 334  *
 335  * \retval 0 success
 336  * \retval -1 failure
 337  */
 338 int __ast_sorcery_apply_config(struct ast_sorcery *sorcery, const char *name, const char *module);
 339
 340 #define ast_sorcery_apply_config(sorcery, name) \
 341         __ast_sorcery_apply_config((sorcery), (name), AST_MODULE)
 342
 343 /*!
 344  * \brief Apply default object wizard mappings
 345  *
 346  * \param sorcery Pointer to a sorcery structure
 347  * \param type Type of object to apply to
 348  * \param module The name of the module, typically AST_MODULE
 349  * \param name Name of the wizard to use
 350  * \param data Data to be passed to wizard
 351  *
 352  * \retval 0 success
 353  * \retval -1 failure
 354  *
 355  * \note This should be called *after* applying configuration sourced mappings
 356  *
 357  * \note Only a single default can exist per object type
 358  */
 359 int __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, const char *module, const char *name, const char *data);
 360
 361 #define ast_sorcery_apply_default(sorcery, type, name, data) \
 362         __ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))
 363
 364 /*!
 365  * \brief Register an object type
 366  *
 367  * \param sorcery Pointer to a sorcery structure
 368  * \param type Type of object
 369  * \param hidden All objects of this type are internal and should not be manipulated by users
 370  * \param reloadable All objects of this type are reloadable
 371  * \param alloc Required object allocation callback
 372  * \param transform Optional transformation callback
 373  * \param apply Optional object set apply callback
 374  *
 375  * \note In general, this function should not be used directly. One of the various
 376  * macro'd versions should be used instead.
 377  *
 378  * \retval 0 success
 379  * \retval -1 failure
 380  */
 381 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);
 382
 383 /*!
 384  * \brief Register an object type
 385  *
 386  * \param sorcery Pointer to a sorcery structure
 387  * \param type Type of object
 388  * \param alloc Required object allocation callback
 389  * \param transform Optional transformation callback
 390  * \param apply Optional object set apply callback
 391  *
 392  * \retval 0 success
 393  * \retval -1 failure
 394  */
 395 #define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
 396         __ast_sorcery_object_register((sorcery), (type), 0, 1, (alloc), (transform), (apply))
 397
 398 /*!
 399  * \brief Register an object type that is not reloadable
 400  *
 401  * \param sorcery Pointer to a sorcery structure
 402  * \param type Type of object
 403  * \param alloc Required object allocation callback
 404  * \param transform Optional transformation callback
 405  * \param apply Optional object set apply callback
 406  *
 407  * \retval 0 success
 408  * \retval -1 failure
 409  */
 410 #define ast_sorcery_object_register_no_reload(sorcery, type, alloc, transform, apply) \
 411         __ast_sorcery_object_register((sorcery), (type), 0, 0, (alloc), (transform), (apply))
 412
 413 /*!
 414  * \brief Register an internal, hidden object type
 415  *
 416  * \param sorcery Pointer to a sorcery structure
 417  * \param type Type of object
 418  * \param alloc Required object allocation callback
 419  * \param transform Optional transformation callback
 420  * \param apply Optional object set apply callback
 421  *
 422  * \retval 0 success
 423  * \retval -1 failure
 424  */
 425 #define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
 426         __ast_sorcery_object_register((sorcery), (type), 1, 1, (alloc), (transform), (apply))
 427
 428 /*!
 429  * \brief Set the copy handler for an object type
 430  *
 431  * \param sorcery Pointer to a sorcery structure
 432  * \param type Type of object
 433  * \param copy Copy handler
 434  */
 435 void ast_sorcery_object_set_copy_handler(struct ast_sorcery *sorcery, const char *type, sorcery_copy_handler copy);
 436
 437 /*!
 438  * \brief Set the diff handler for an object type
 439  *
 440  * \param sorcery Pointer to a sorcery structure
 441  * \param type Type of object
 442  * \param diff Diff handler
 443  */
 444 void ast_sorcery_object_set_diff_handler(struct ast_sorcery *sorcery, const char *type, sorcery_diff_handler diff);
 445
 446 /*!
 447  * \brief Register a regex for multiple fields within an object
 448  *
 449  * \param sorcery Pointer to a sorcery structure
 450  * \param type Type of object
 451  * \param regex A regular expression pattern for the fields
 452  * \param config_handler A custom handler for translating the string representation of the fields
 453  * \param sorcery_handler A custom handler for translating the native representation of the fields
 454  *
 455  * \retval 0 success
 456  * \retval -1 failure
 457  */
 458 int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *type, const char *regex, aco_option_handler config_handler,
 459                                                                            sorcery_fields_handler sorcery_handler);
 460
 461 /*!
 462  * \brief Register a field within an object
 463  *
 464  * \param sorcery Pointer to a sorcery structure
 465  * \param type Type of object
 466  * \param name Name of the field
 467  * \param default_val Default value of the field
 468  * \param opt_type Option type
 469  * \param flags Option type specific flags
 470  *
 471  * \retval 0 success
 472  * \retval -1 failure
 473  */
 474 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,
 475                                         aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, unsigned int no_doc,
 476                                         size_t argc, ...);
 477
 478 /*!
 479  * \brief Register a field within an object
 480  *
 481  * \param sorcery Pointer to a sorcery structure
 482  * \param type Type of object
 483  * \param name Name of the field
 484  * \param default_val Default value of the field
 485  * \param opt_type Option type
 486  * \param flags Option type specific flags
 487  *
 488  * \retval 0 success
 489  * \retval -1 failure
 490  */
 491 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
 492     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 493
 494 /*!
 495  * \brief Register a field within an object without documentation
 496  *
 497  * \param sorcery Pointer to a sorcery structure
 498  * \param type Type of object
 499  * \param name Name of the field
 500  * \param default_val Default value of the field
 501  * \param opt_type Option type
 502  * \param flags Option type specific flags
 503  *
 504  * \retval 0 success
 505  * \retval -1 failure
 506  */
 507 #define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
 508     __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
 509
 510 /*!
 511  * \brief Register a field within an object with custom handlers
 512  *
 513  * \param sorcery Pointer to a sorcery structure
 514  * \param type Type of object
 515  * \param name Name of the field
 516  * \param default_val Default value of the field
 517  * \param config_handler Custom configuration handler
 518  * \param sorcery_handler Custom sorcery handler
 519  * \param flags Option type specific flags
 520  *
 521  * \retval 0 success
 522  * \retval -1 failure
 523  */
 524 #define ast_sorcery_object_field_register_custom(sorcery, type, name, default_val, config_handler, sorcery_handler, flags, ...) \
 525     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
 526
 527 /*!
 528  * \brief Register a field within an object with custom handlers without documentation
 529  *
 530  * \param sorcery Pointer to a sorcery structure
 531  * \param type Type of object
 532  * \param name Name of the field
 533  * \param default_val Default value of the field
 534  * \param config_handler Custom configuration handler
 535  * \param sorcery_handler Custom sorcery handler
 536  * \param flags Option type specific flags
 537  *
 538  * \retval 0 success
 539  * \retval -1 failure
 540  */
 541 #define ast_sorcery_object_field_register_custom_nodoc(sorcery, type, name, default_val, config_handler, sorcery_handler, flags, ...) \
 542     __ast_sorcery_object_field_register(sorcery, type, name, default_val, OPT_CUSTOM_T, config_handler, sorcery_handler, flags, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
 543
 544 /*!
 545  * \brief Inform any wizards to load persistent objects
 546  *
 547  * \param sorcery Pointer to a sorcery structure
 548  */
 549 void ast_sorcery_load(const struct ast_sorcery *sorcery);
 550
 551 /*!
 552  * \brief Inform any wizards of a specific object type to load persistent objects
 553  *
 554  * \param sorcery Pointer to a sorcery structure
 555  * \param type Name of the object type to load
 556  */
 557 void ast_sorcery_load_object(const struct ast_sorcery *sorcery, const char *type);
 558
 559 /*!
 560  * \brief Inform any wizards to reload persistent objects
 561  *
 562  * \param sorcery Pointer to a sorcery structure
 563  */
 564 void ast_sorcery_reload(const struct ast_sorcery *sorcery);
 565
 566 /*!
 567  * \brief Inform any wizards of a specific object type to reload persistent objects
 568  *
 569  * \param sorcery Pointer to a sorcery structure
 570  * \param type Name of the object type to reload
 571  */
 572 void ast_sorcery_reload_object(const struct ast_sorcery *sorcery, const char *type);
 573
 574 /*!
 575  * \brief Increase the reference count of a sorcery structure
 576  *
 577  * \param sorcery Pointer to a sorcery structure
 578  */
 579 void ast_sorcery_ref(struct ast_sorcery *sorcery);
 580
 581 /*!
 582  * \brief Create an object set (KVP list) for an object
 583  *
 584  * \param sorcery Pointer to a sorcery structure
 585  * \param object Pointer to a sorcery object
 586  *
 587  * \retval non-NULL success
 588  * \retval NULL if error occurred
 589  *
 590  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
 591  */
 592 struct ast_variable *ast_sorcery_objectset_create(const struct ast_sorcery *sorcery, const void *object);
 593
 594 /*!
 595  * \brief Create an object set in JSON format for an object
 596  *
 597  * \param sorcery Pointer to a sorcery structure
 598  * \param object Pointer to a sorcery object
 599  *
 600  * \retval non-NULL success
 601  * \retval NULL if error occurred
 602  *
 603  * \note The returned ast_json object must be unreferenced using ast_json_unref
 604  */
 605 struct ast_json *ast_sorcery_objectset_json_create(const struct ast_sorcery *sorcery, const void *object);
 606
 607 /*!
 608  * \brief Apply an object set (KVP list) to an object
 609  *
 610  * \param sorcery Pointer to a sorcery structure
 611  * \param object Pointer to a sorcery object
 612  * \param objectset Object set itself
 613  *
 614  * \retval 0 success
 615  * \retval -1 failure
 616  *
 617  * \note This operation is *not* atomic. If this fails it is possible for the object to be left with a partially
 618  *       applied object set.
 619  */
 620 int ast_sorcery_objectset_apply(const struct ast_sorcery *sorcery, void *object, struct ast_variable *objectset);
 621
 622 /*!
 623  * \brief Create a changeset given two object sets
 624  *
 625  * \param original Original object set
 626  * \param modified Modified object set
 627  * \param changes Pointer to hold any changes between the object sets
 628  *
 629  * \retval 0 success
 630  * \retval -1 failure
 631  *
 632  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
 633  */
 634 int ast_sorcery_changeset_create(const struct ast_variable *original, const struct ast_variable *modified, struct ast_variable **changes);
 635
 636 /*!
 637  * \brief Allocate a generic sorcery capable object
 638  *
 639  * \param size Size of the object
 640  * \param destructor Optional destructor function
 641  *
 642  * \retval non-NULL success
 643  * \retval NULL failure
 644  */
 645 void *ast_sorcery_generic_alloc(size_t size, ao2_destructor_fn destructor);
 646
 647 /*!
 648  * \brief Allocate an object
 649  *
 650  * \param sorcery Pointer to a sorcery structure
 651  * \param type Type of object to allocate
 652  * \param id Optional unique identifier, if none is provided one will be generated
 653  *
 654  * \retval non-NULL success
 655  * \retval NULL failure
 656  */
 657 void *ast_sorcery_alloc(const struct ast_sorcery *sorcery, const char *type, const char *id);
 658
 659 /*!
 660  * \brief Create a copy of an object
 661  *
 662  * \param sorcery Pointer to a sorcery structure
 663  * \param object Existing object
 664  *
 665  * \retval non-NULL success
 666  * \retval NULL failure
 667  */
 668 void *ast_sorcery_copy(const struct ast_sorcery *sorcery, const void *object);
 669
 670 /*!
 671  * \brief Create a changeset of two objects
 672  *
 673  * \param sorcery Pointer to a sorcery structure
 674  * \param original Original object
 675  * \param modified Modified object
 676  * \param changes Pointer which will be populated with changes if any exist
 677  *
 678  * \retval 0 success
 679  * \retval -1 failure
 680  *
 681  * \note The returned ast_variable list must be destroyed using ast_variables_destroy
 682  *
 683  * \note While the objects must be of the same type they do not have to be the same object
 684  */
 685 int ast_sorcery_diff(const struct ast_sorcery *sorcery, const void *original, const void *modified, struct ast_variable **changes);
 686
 687 /*!
 688  * \brief Add an observer to a specific object type
 689  *
 690  * \param sorcery Pointer to a sorcery structure
 691  * \param type Type of object that should be observed
 692  * \param callbacks Implementation of the observer interface
 693  *
 694  * \retval 0 success
 695  * \retval -1 failure
 696  *
 697  * \note You must be ready to accept observer invocations before this function is called
 698  */
 699 int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
 700
 701 /*!
 702  * \brief Remove an observer from a specific object type
 703  *
 704  * \param sorcery Pointer to a sorcery structure
 705  * \param type Type of object that should no longer be observed
 706  * \param callbacks Implementation of the observer interface
 707  *
 708  * \retval 0 success
 709  * \retval -1 failure
 710  */
 711 void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
 712
 713 /*!
 714  * \brief Create and potentially persist an object using an available wizard
 715  *
 716  * \param sorcery Pointer to a sorcery structure
 717  * \param object Pointer to a sorcery object
 718  *
 719  * \retval 0 success
 720  * \retval -1 failure
 721  */
 722 int ast_sorcery_create(const struct ast_sorcery *sorcery, void *object);
 723
 724 /*!
 725  * \brief Retrieve an object using its unique identifier
 726  *
 727  * \param sorcery Pointer to a sorcery structure
 728  * \param type Type of object to retrieve
 729  * \param id Unique object identifier
 730  *
 731  * \retval non-NULL if found
 732  * \retval NULL if not found
 733  */
 734 void *ast_sorcery_retrieve_by_id(const struct ast_sorcery *sorcery, const char *type, const char *id);
 735
 736 /*!
 737  * \brief Retrieve an object or multiple objects using specific fields
 738  *
 739  * \param sorcery Pointer to a sorcery structure
 740  * \param type Type of object to retrieve
 741  * \param flags Flags to control behavior
 742  * \param fields Optional object fields and values to match against
 743  *
 744  * \retval non-NULL if found
 745  * \retval NULL if not found
 746  *
 747  * \note If the AST_RETRIEVE_FLAG_MULTIPLE flag is specified the returned value will be an
 748  *       ao2_container that must be unreferenced after use.
 749  *
 750  * \note If the AST_RETRIEVE_FLAG_ALL flag is used you may omit fields to retrieve all objects
 751  *       of the given type.
 752  */
 753 void *ast_sorcery_retrieve_by_fields(const struct ast_sorcery *sorcery, const char *type, unsigned int flags, struct ast_variable *fields);
 754
 755 /*!
 756  * \brief Retrieve multiple objects using a regular expression on their id
 757  *
 758  * \param sorcery Pointer to a sorcery structure
 759  * \param type Type of object to retrieve
 760  * \param regex Regular expression
 761  *
 762  * \retval non-NULL if error occurs
 763  * \retval NULL success
 764  *
 765  * \note The provided regex is treated as extended case sensitive.
 766  */
 767 struct ao2_container *ast_sorcery_retrieve_by_regex(const struct ast_sorcery *sorcery, const char *type, const char *regex);
 768
 769 /*!
 770  * \brief Update an object
 771  *
 772  * \param sorcery Pointer to a sorcery structure
 773  * \param object Pointer to a sorcery object
 774  *
 775  * \retval 0 success
 776  * \retval -1 failure
 777  */
 778 int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
 779
 780 /*!
 781  * \brief Delete an object
 782  *
 783  * \param sorcery Pointer to a sorcery structure
 784  * \param object Pointer to a sorcery object
 785  *
 786  * \retval 0 success
 787  * \retval -1 failure
 788  */
 789 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
 790
 791 /*!
 792  * \brief Decrease the reference count of a sorcery structure
 793  *
 794  * \param sorcery Pointer to a sorcery structure
 795  */
 796 void ast_sorcery_unref(struct ast_sorcery *sorcery);
 797
 798 /*!
 799  * \brief Get the unique identifier of a sorcery object
 800  *
 801  * \param object Pointer to a sorcery object
 802  *
 803  * \retval unique identifier
 804  */
 805 const char *ast_sorcery_object_get_id(const void *object);
 806
 807 /*!
 808  * \brief Get the type of a sorcery object
 809  *
 810  * \param object Pointer to a sorcery object
 811  *
 812  * \retval type of object
 813  */
 814 const char *ast_sorcery_object_get_type(const void *object);
 815
 816 /*!
 817  * \brief Get an extended field value from a sorcery object
 818  *
 819  * \param object Pointer to a sorcery object
 820  * \param name Name of the extended field value
 821  *
 822  * \retval non-NULL if found
 823  * \retval NULL if not found
 824  *
 825  * \note The returned string does NOT need to be freed and is guaranteed to remain valid for the lifetime of the object
 826  */
 827 const char *ast_sorcery_object_get_extended(const void *object, const char *name);
 828
 829 /*!
 830  * \brief Set an extended field value on a sorcery object
 831  *
 832  * \param object Pointer to a sorcery object
 833  * \param name Name of the extended field
 834  * \param value Value of the extended field
 835  *
 836  * \retval 0 success
 837  * \retval -1 failure
 838  *
 839  * \note The field name MUST begin with '@' to indicate it is an extended field.
 840  * \note If the extended field already exists it will be overwritten with the new value.
 841  */
 842 int ast_sorcery_object_set_extended(const void *object, const char *name, const char *value);
 843
 844 /*!
 845  * \brief Sorcery object comparator based on id.
 846  */
 847 int ast_sorcery_object_id_compare(const void *obj_left, const void *obj_right, int flags);
 848
 849
 850 #if defined(__cplusplus) || defined(c_plusplus)
 851 }
 852 #endif
 853
 854 #endif /* _ASTERISK_SORCERY_H */