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