include/asterisk/bridging_features.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2009, 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 Channel Bridging API
  21  * \author Joshua Colp <jcolp@digium.com>
  22  */
  23
  24 #ifndef _ASTERISK_BRIDGING_FEATURES_H
  25 #define _ASTERISK_BRIDGING_FEATURES_H
  26
  27 #if defined(__cplusplus) || defined(c_plusplus)
  28 extern "C" {
  29 #endif
  30
  31 /*! \brief Flags used for bridge features */
  32 enum ast_bridge_feature_flags {
  33         /*! Upon channel hangup all bridge participants should be kicked out. */
  34         AST_BRIDGE_FLAG_DISSOLVE_HANGUP = (1 << 0),
  35         /*! The last channel to leave the bridge dissolves it. */
  36         AST_BRIDGE_FLAG_DISSOLVE_EMPTY = (1 << 1),
  37         /*! Move between bridging technologies as needed. */
  38         AST_BRIDGE_FLAG_SMART = (1 << 2),
  39         /*! Bridge channels cannot be merged from this bridge. */
  40         AST_BRIDGE_FLAG_MERGE_INHIBIT_FROM = (1 << 3),
  41         /*! Bridge channels cannot be merged to this bridge. */
  42         AST_BRIDGE_FLAG_MERGE_INHIBIT_TO = (1 << 4),
  43         /*! Bridge channels cannot be local channel swap optimized from this bridge. */
  44         AST_BRIDGE_FLAG_SWAP_INHIBIT_FROM = (1 << 5),
  45         /*! Bridge channels cannot be local channel swap optimized to this bridge. */
  46         AST_BRIDGE_FLAG_SWAP_INHIBIT_TO = (1 << 6),
  47         /*! Bridge channels can be moved to another bridge only by masquerade (ConfBridge) */
  48         AST_BRIDGE_FLAG_MASQUERADE_ONLY = (1 << 7),
  49         /*! Bridge does not allow transfers of channels out */
  50         AST_BRIDGE_FLAG_TRANSFER_PROHIBITED = (1 << 6),
  51         /*! Bridge transfers require transfer of entire bridge rather than individual channels */
  52         AST_BRIDGE_FLAG_TRANSFER_BRIDGE_ONLY = (1 << 7),
  53 };
  54
  55 /*! \brief Flags used for per bridge channel features */
  56 enum ast_bridge_channel_feature_flags {
  57         /*! Upon channel hangup all bridge participants should be kicked out. */
  58         AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP = (1 << 0),
  59         /*! This channel leaves the bridge if all participants have this flag set. */
  60         AST_BRIDGE_CHANNEL_FLAG_LONELY = (1 << 1),
  61         /*! This channel cannot be moved to another bridge. */
  62         AST_BRIDGE_CHANNEL_FLAG_IMMOVABLE = (1 << 2),
  63 };
  64
  65 /*! \brief Built in DTMF features */
  66 enum ast_bridge_builtin_feature {
  67         /*! DTMF based Blind Transfer */
  68         AST_BRIDGE_BUILTIN_BLINDTRANSFER,
  69         /*! DTMF based Attended Transfer */
  70         AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
  71         /*!
  72          * DTMF based depart bridge feature
  73          *
  74          * \note Imparted channels are optionally hangup depending upon
  75          * how it was imparted.
  76          *
  77          * \note Joined channels exit the bridge with
  78          * AST_BRIDGE_CHANNEL_STATE_END.
  79          */
  80         AST_BRIDGE_BUILTIN_HANGUP,
  81         /*!
  82          * DTMF based Park
  83          *
  84          * \details The bridge is parked and the channel hears the
  85          * parking slot to which it was parked.
  86          */
  87         AST_BRIDGE_BUILTIN_PARKCALL,
  88 /* BUGBUG does Monitor and/or MixMonitor require a two party bridge?  MixMonitor is used by ConfBridge so maybe it doesn't. */
  89         /*!
  90          * DTMF one-touch-record toggle using Monitor app.
  91          *
  92          * \note Only valid on two party bridges.
  93          */
  94         AST_BRIDGE_BUILTIN_AUTOMON,
  95         /*!
  96          * DTMF one-touch-record toggle using MixMonitor app.
  97          *
  98          * \note Only valid on two party bridges.
  99          */
 100         AST_BRIDGE_BUILTIN_AUTOMIXMON,
 101
 102         /*! End terminator for list of built in features. Must remain last. */
 103         AST_BRIDGE_BUILTIN_END
 104 };
 105
 106 enum ast_bridge_builtin_interval {
 107         /*! Apply Call Duration Limits */
 108         AST_BRIDGE_BUILTIN_INTERVAL_LIMITS,
 109
 110         /*! End terminator for list of built in interval features. Must remain last. */
 111         AST_BRIDGE_BUILTIN_INTERVAL_END
 112 };
 113
 114 struct ast_bridge;
 115 struct ast_bridge_channel;
 116
 117 /*!
 118  * \brief Hook callback type
 119  *
 120  * \param bridge The bridge that the channel is part of
 121  * \param bridge_channel Channel executing the feature
 122  * \param hook_pvt Private data passed in when the hook was created
 123  *
 124  * For interval hooks:
 125  * \retval 0 Setup to fire again at the last interval.
 126  * \retval positive Setup to fire again at the new interval returned.
 127  * \retval -1 Remove the callback hook.
 128  *
 129  * For other hooks:
 130  * \retval 0 Keep the callback hook.
 131  * \retval -1 Remove the callback hook.
 132  */
 133 typedef int (*ast_bridge_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt);
 134
 135 /*!
 136  * \brief Hook pvt destructor callback
 137  *
 138  * \param hook_pvt Private data passed in when the hook was created to destroy
 139  */
 140 typedef void (*ast_bridge_hook_pvt_destructor)(void *hook_pvt);
 141
 142 /*!
 143  * \brief Talking indicator callback
 144  *
 145  * \details This callback can be registered with the bridge in order
 146  * to receive updates on when a bridge_channel has started and stopped
 147  * talking
 148  *
 149  * \param bridge_channel Channel executing the feature
 150  * \param talking TRUE if the channel is now talking
 151  *
 152  * \retval 0 success
 153  * \retval -1 failure
 154  */
 155 typedef void (*ast_bridge_talking_indicate_callback)(struct ast_bridge_channel *bridge_channel, void *pvt_data, int talking);
 156
 157
 158 typedef void (*ast_bridge_talking_indicate_destructor)(void *pvt_data);
 159
 160 /*!
 161  * \brief Maximum length of a DTMF feature string
 162  */
 163 #define MAXIMUM_DTMF_FEATURE_STRING (11 + 1)
 164
 165 /*! Extra parameters for a DTMF feature hook. */
 166 struct ast_bridge_hook_dtmf {
 167         /*! DTMF String that is examined during a feature hook lookup */
 168         char code[MAXIMUM_DTMF_FEATURE_STRING];
 169 };
 170
 171 /*! Extra parameters for an interval timer hook. */
 172 struct ast_bridge_hook_timer {
 173         /*! Time at which the hook should actually trip */
 174         struct timeval trip_time;
 175         /*! Heap index for interval hook */
 176         ssize_t heap_index;
 177         /*! Interval that the hook should execute at in milliseconds */
 178         unsigned int interval;
 179         /*! Sequence number for the hook to ensure expiration ordering */
 180         unsigned int seqno;
 181 };
 182
 183 enum ast_bridge_hook_remove_flags {
 184         /*! The hook is removed when the channel is pulled from the bridge. */
 185         AST_BRIDGE_HOOK_REMOVE_ON_PULL = (1 << 0),
 186 };
 187
 188 /* BUGBUG Need to be able to selectively remove DTMF, hangup, and interval hooks. */
 189 /*! \brief Structure that is the essence of a feature hook. */
 190 struct ast_bridge_hook {
 191         /*! Linked list information */
 192         AST_LIST_ENTRY(ast_bridge_hook) entry;
 193         /*! Callback that is called when hook is tripped */
 194         ast_bridge_hook_callback callback;
 195         /*! Callback to destroy hook_pvt data right before destruction. */
 196         ast_bridge_hook_pvt_destructor destructor;
 197         /*! Unique data that was passed into us */
 198         void *hook_pvt;
 199         /*! Flags determining when hooks should be removed from a bridge channel */
 200         struct ast_flags remove_flags;
 201         /*! Extra hook parameters. */
 202         union {
 203                 /*! Extra parameters for a DTMF feature hook. */
 204                 struct ast_bridge_hook_dtmf dtmf;
 205                 /*! Extra parameters for an interval timer hook. */
 206                 struct ast_bridge_hook_timer timer;
 207         } parms;
 208 };
 209
 210 #define BRIDGE_FEATURES_INTERVAL_RATE 10
 211
 212 /*!
 213  * \brief Structure that contains features information
 214  */
 215 struct ast_bridge_features {
 216         /*! Attached DTMF feature hooks */
 217         struct ao2_container *dtmf_hooks;
 218         /*! Attached hangup interception hooks container */
 219         struct ao2_container *hangup_hooks;
 220         /*! Attached bridge channel join interception hooks container */
 221         struct ao2_container *join_hooks;
 222         /*! Attached bridge channel leave interception hooks container */
 223         struct ao2_container *leave_hooks;
 224         /*! Attached interval hooks */
 225         struct ast_heap *interval_hooks;
 226         /*! Used to determine when interval based features should be checked */
 227         struct ast_timer *interval_timer;
 228         /*! Limits feature data */
 229         struct ast_bridge_features_limits *limits;
 230         /*! Callback to indicate when a bridge channel has started and stopped talking */
 231         ast_bridge_talking_indicate_callback talker_cb;
 232         /*! Callback to destroy any pvt data stored for the talker. */
 233         ast_bridge_talking_indicate_destructor talker_destructor_cb;
 234         /*! Talker callback pvt data */
 235         void *talker_pvt_data;
 236         /*! Feature flags that are enabled */
 237         struct ast_flags feature_flags;
 238         /*! Used to assign the sequence number to the next interval hook added. */
 239         unsigned int interval_sequence;
 240         /*! TRUE if feature_flags is setup */
 241         unsigned int usable:1;
 242         /*! TRUE if the channel/bridge is muted. */
 243         unsigned int mute:1;
 244         /*! TRUE if DTMF should be passed into the bridge tech.  */
 245         unsigned int dtmf_passthrough:1;
 246 };
 247
 248 /*!
 249  * \brief Structure that contains configuration information for the blind transfer built in feature
 250  */
 251 struct ast_bridge_features_blind_transfer {
 252         /*! Context to use for transfers (If not empty.) */
 253         char context[AST_MAX_CONTEXT];
 254 };
 255
 256 /*!
 257  * \brief Structure that contains configuration information for the attended transfer built in feature
 258  */
 259 struct ast_bridge_features_attended_transfer {
 260         /*! Context to use for transfers (If not empty.) */
 261         char context[AST_MAX_CONTEXT];
 262         /*! DTMF string used to abort the transfer (If not empty.) */
 263         char abort[MAXIMUM_DTMF_FEATURE_STRING];
 264         /*! DTMF string used to turn the transfer into a three way conference (If not empty.) */
 265         char threeway[MAXIMUM_DTMF_FEATURE_STRING];
 266         /*! DTMF string used to complete the transfer (If not empty.) */
 267         char complete[MAXIMUM_DTMF_FEATURE_STRING];
 268 };
 269
 270 /*!
 271  * \brief Structure that contains configuration information for the limits feature
 272  */
 273 struct ast_bridge_features_limits {
 274         /*! Maximum duration that the channel is allowed to be in the bridge (specified in milliseconds) */
 275         unsigned int duration;
 276         /*! Duration into the call when warnings should begin (specified in milliseconds or 0 to disable) */
 277         unsigned int warning;
 278         /*! Interval between the warnings (specified in milliseconds or 0 to disable) */
 279         unsigned int frequency;
 280
 281         AST_DECLARE_STRING_FIELDS(
 282                 /*! Sound file to play when the maximum duration is reached (if empty, then nothing will be played) */
 283                 AST_STRING_FIELD(duration_sound);
 284                 /*! Sound file to play when the warning time is reached (if empty, then the remaining time will be played) */
 285                 AST_STRING_FIELD(warning_sound);
 286                 /*! Sound file to play when the call is first entered (if empty, then the remaining time will be played) */
 287                 AST_STRING_FIELD(connect_sound);
 288         );
 289         /*! Time when the bridge will be terminated by the limits feature */
 290         struct timeval quitting_time;
 291 };
 292
 293 /*!
 294  * \brief Register a handler for a built in feature
 295  *
 296  * \param feature The feature that the handler will be responsible for
 297  * \param callback The callback function that will handle it
 298  * \param dtmf Default DTMF string used to activate the feature
 299  *
 300  * \retval 0 on success
 301  * \retval -1 on failure
 302  *
 303  * Example usage:
 304  *
 305  * \code
 306  * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
 307  * \endcode
 308  *
 309  * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
 310  * attended transfer feature.
 311  */
 312 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_hook_callback callback, const char *dtmf);
 313
 314 /*!
 315  * \brief Unregister a handler for a built in feature
 316  *
 317  * \param feature The feature to unregister
 318  *
 319  * \retval 0 on success
 320  * \retval -1 on failure
 321  *
 322  * Example usage:
 323  *
 324  * \code
 325  * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
 326  * \endcode
 327  *
 328  * This unregisters the function that is handling the built in attended transfer feature.
 329  */
 330 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
 331
 332 /*!
 333  * \brief Attach interval hooks to a bridge features structure
 334  *
 335  * \param features Bridge features structure
 336  * \param limits Configured limits applicable to the channel
 337  * \param remove_flags Dictates what situations the hook should be removed.
 338  *
 339  * \retval 0 on success
 340  * \retval -1 on failure
 341  */
 342 typedef int (*ast_bridge_builtin_set_limits_fn)(struct ast_bridge_features *features,
 343                 struct ast_bridge_features_limits *limits, enum ast_bridge_hook_remove_flags remove_flags);
 344
 345 /*!
 346  * \brief Register a handler for a built in interval feature
 347  *
 348  * \param interval The interval feature that the handler will be responsible for
 349  * \param callback the Callback function that will handle it
 350  *
 351  * \retval 0 on success
 352  * \retval -1 on failure
 353  *
 354  * Example usage:
 355  *
 356  * \code
 357  * ast_bridge_interval_register(AST_BRIDGE_BUILTIN_INTERVAL_LIMITS, bridge_builtin_set_limits);
 358  * \endcode
 359  *
 360  * This registers the function bridge_builtin_set_limits as the function responsible for the built in
 361  * duration limit feature.
 362  */
 363 int ast_bridge_interval_register(enum ast_bridge_builtin_interval interval, ast_bridge_builtin_set_limits_fn callback);
 364
 365 /*!
 366  * \brief Unregisters a handler for a built in interval feature
 367  *
 368  * \param interval the interval feature to unregister
 369  *
 370  * \retval 0 on success
 371  * \retval -1 on failure
 372  *
 373  * Example usage:
 374  *
 375  * \code
 376  * ast_bridge_interval_unregister(AST_BRIDGE_BULTIN_INTERVAL_LIMITS)
 377  * /endcode
 378  *
 379  * This unregisters the function that is handling the built in duration limit feature.
 380  */
 381 int ast_bridge_interval_unregister(enum ast_bridge_builtin_interval interval);
 382
 383 /*!
 384  * \brief Attach a bridge channel join hook to a bridge features structure
 385  *
 386  * \param features Bridge features structure
 387  * \param callback Function to execute upon activation
 388  * \param hook_pvt Unique data
 389  * \param destructor Optional destructor callback for hook_pvt data
 390  * \param remove_flags Dictates what situations the hook should be removed.
 391  *
 392  * \retval 0 on success
 393  * \retval -1 on failure
 394  *
 395  * Example usage:
 396  *
 397  * \code
 398  * struct ast_bridge_features features;
 399  * ast_bridge_features_init(&features);
 400  * ast_bridge_join_hook(&features, join_callback, NULL, NULL, 0);
 401  * \endcode
 402  *
 403  * This makes the bridging core call join_callback when a
 404  * channel successfully joins the bridging system.  A pointer to
 405  * useful data may be provided to the hook_pvt parameter.
 406  */
 407 int ast_bridge_join_hook(struct ast_bridge_features *features,
 408         ast_bridge_hook_callback callback,
 409         void *hook_pvt,
 410         ast_bridge_hook_pvt_destructor destructor,
 411         enum ast_bridge_hook_remove_flags remove_flags);
 412
 413 /*!
 414  * \brief Attach a bridge channel leave hook to a bridge features structure
 415  *
 416  * \param features Bridge features structure
 417  * \param callback Function to execute upon activation
 418  * \param hook_pvt Unique data
 419  * \param destructor Optional destructor callback for hook_pvt data
 420  * \param remove_flags Dictates what situations the hook should be removed.
 421  *
 422  * \retval 0 on success
 423  * \retval -1 on failure
 424  *
 425  * Example usage:
 426  *
 427  * \code
 428  * struct ast_bridge_features features;
 429  * ast_bridge_features_init(&features);
 430  * ast_bridge_leave_hook(&features, leave_callback, NULL, NULL, 0);
 431  * \endcode
 432  *
 433  * This makes the bridging core call leave_callback when a
 434  * channel successfully leaves the bridging system.  A pointer
 435  * to useful data may be provided to the hook_pvt parameter.
 436  */
 437 int ast_bridge_leave_hook(struct ast_bridge_features *features,
 438         ast_bridge_hook_callback callback,
 439         void *hook_pvt,
 440         ast_bridge_hook_pvt_destructor destructor,
 441         enum ast_bridge_hook_remove_flags remove_flags);
 442
 443 /*!
 444  * \brief Attach a hangup hook to a bridge features structure
 445  *
 446  * \param features Bridge features structure
 447  * \param callback Function to execute upon activation
 448  * \param hook_pvt Unique data
 449  * \param destructor Optional destructor callback for hook_pvt data
 450  * \param remove_flags Dictates what situations the hook should be removed.
 451  *
 452  * \retval 0 on success
 453  * \retval -1 on failure
 454  *
 455  * Example usage:
 456  *
 457  * \code
 458  * struct ast_bridge_features features;
 459  * ast_bridge_features_init(&features);
 460  * ast_bridge_hangup_hook(&features, hangup_callback, NULL, NULL, 0);
 461  * \endcode
 462  *
 463  * This makes the bridging core call hangup_callback if a
 464  * channel that has this hook hangs up.  A pointer to useful
 465  * data may be provided to the hook_pvt parameter.
 466  */
 467 int ast_bridge_hangup_hook(struct ast_bridge_features *features,
 468         ast_bridge_hook_callback callback,
 469         void *hook_pvt,
 470         ast_bridge_hook_pvt_destructor destructor,
 471         enum ast_bridge_hook_remove_flags remove_flags);
 472
 473 /*!
 474  * \brief Attach a DTMF hook to a bridge features structure
 475  *
 476  * \param features Bridge features structure
 477  * \param dtmf DTMF string to be activated upon
 478  * \param callback Function to execute upon activation
 479  * \param hook_pvt Unique data
 480  * \param destructor Optional destructor callback for hook_pvt data
 481  * \param remove_flags Dictates what situations the hook should be removed.
 482  *
 483  * \retval 0 on success
 484  * \retval -1 on failure
 485  *
 486  * Example usage:
 487  *
 488  * \code
 489  * struct ast_bridge_features features;
 490  * ast_bridge_features_init(&features);
 491  * ast_bridge_dtmf_hook(&features, "#", pound_callback, NULL, NULL, 0);
 492  * \endcode
 493  *
 494  * This makes the bridging core call pound_callback if a channel that has this
 495  * feature structure inputs the DTMF string '#'. A pointer to useful data may be
 496  * provided to the hook_pvt parameter.
 497  */
 498 int ast_bridge_dtmf_hook(struct ast_bridge_features *features,
 499         const char *dtmf,
 500         ast_bridge_hook_callback callback,
 501         void *hook_pvt,
 502         ast_bridge_hook_pvt_destructor destructor,
 503         enum ast_bridge_hook_remove_flags remove_flags);
 504
 505 /*!
 506  * \brief attach an interval hook to a bridge features structure
 507  *
 508  * \param features Bridge features structure
 509  * \param interval The interval that the hook should execute at in milliseconds
 510  * \param callback Function to execute upon activation
 511  * \param hook_pvt Unique data
 512  * \param destructor Optional destructor callback for hook_pvt data
 513  * \param remove_flags Dictates what situations the hook should be removed.
 514  *
 515  * \retval 0 on success
 516  * \retval -1 on failure
 517  *
 518  * \code
 519  * struct ast_bridge_features features;
 520  * ast_bridge_features_init(&features);
 521  * ast_bridge_interval_hook(&features, 1000, playback_callback, NULL, NULL, 0);
 522  * \endcode
 523  *
 524  * This makes the bridging core call playback_callback every second. A pointer to useful
 525  * data may be provided to the hook_pvt parameter.
 526  */
 527 int ast_bridge_interval_hook(struct ast_bridge_features *features,
 528         unsigned int interval,
 529         ast_bridge_hook_callback callback,
 530         void *hook_pvt,
 531         ast_bridge_hook_pvt_destructor destructor,
 532         enum ast_bridge_hook_remove_flags remove_flags);
 533
 534 /*!
 535  * \brief Set a callback on the features structure to receive talking notifications on.
 536  *
 537  * \param features Bridge features structure
 538  * \param talker_cb Callback function to execute when talking events occur in the bridge core.
 539  * \param pvt_data Optional unique data that will be passed with the talking events.
 540  * \param talker_destructor Optional destructor callback for pvt data.
 541  *
 542  * \return Nothing
 543  */
 544 void ast_bridge_features_set_talk_detector(struct ast_bridge_features *features,
 545         ast_bridge_talking_indicate_callback talker_cb,
 546         ast_bridge_talking_indicate_destructor talker_destructor,
 547         void *pvt_data);
 548
 549 /*!
 550  * \brief Enable a built in feature on a bridge features structure
 551  *
 552  * \param features Bridge features structure
 553  * \param feature Feature to enable
 554  * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
 555  * \param config Configuration structure unique to the built in type
 556  * \param destructor Optional destructor callback for config data
 557  * \param remove_flags Dictates what situations the hook should be removed.
 558  *
 559  * \retval 0 on success
 560  * \retval -1 on failure
 561  *
 562  * Example usage:
 563  *
 564  * \code
 565  * struct ast_bridge_features features;
 566  * ast_bridge_features_init(&features);
 567  * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL, NULL, 0);
 568  * \endcode
 569  *
 570  * This enables the attended transfer DTMF option using the default DTMF string. An alternate
 571  * string may be provided using the dtmf parameter. Internally this is simply setting up a hook
 572  * to a built in feature callback function.
 573  */
 574 int ast_bridge_features_enable(struct ast_bridge_features *features,
 575         enum ast_bridge_builtin_feature feature,
 576         const char *dtmf,
 577         void *config,
 578         ast_bridge_hook_pvt_destructor destructor,
 579         enum ast_bridge_hook_remove_flags remove_flags);
 580
 581 /*!
 582  * \brief Constructor function for ast_bridge_features_limits
 583  *
 584  * \param limits pointer to a ast_bridge_features_limits struct that has been allocted, but not initialized
 585  *
 586  * \retval 0 on success
 587  * \retval -1 on failure
 588  */
 589 int ast_bridge_features_limits_construct(struct ast_bridge_features_limits *limits);
 590
 591 /*!
 592  * \brief Destructor function for ast_bridge_features_limits
 593  *
 594  * \param limits pointer to an ast_bridge_features_limits struct that needs to be destroyed
 595  *
 596  * This function does not free memory allocated to the ast_bridge_features_limits struct, it only frees elements within the struct.
 597  * You must still call ast_free on the the struct if you allocated it with malloc.
 598  */
 599 void ast_bridge_features_limits_destroy(struct ast_bridge_features_limits *limits);
 600
 601 /*!
 602  * \brief Limit the amount of time a channel may stay in the bridge and optionally play warning messages as time runs out
 603  *
 604  * \param features Bridge features structure
 605  * \param limits Configured limits applicable to the channel
 606  * \param remove_flags Dictates what situations the hook should be removed.
 607  *
 608  * \retval 0 on success
 609  * \retval -1 on failure
 610  *
 611  * Example usage:
 612  *
 613  * \code
 614  * struct ast_bridge_features features;
 615  * struct ast_bridge_features_limits limits;
 616  * ast_bridge_features_init(&features);
 617  * ast_bridge_features_limits_construct(&limits);
 618  * ast_bridge_features_set_limits(&features, &limits, 0);
 619  * ast_bridge_features_limits_destroy(&limits);
 620  * \endcode
 621  *
 622  * This sets the maximum time the channel can be in the bridge to 10 seconds and does not play any warnings.
 623  *
 624  * \note This API call can only be used on a features structure that will be used in association with a bridge channel.
 625  * \note The ast_bridge_features_limits structure must remain accessible for the lifetime of the features structure.
 626  */
 627 int ast_bridge_features_set_limits(struct ast_bridge_features *features, struct ast_bridge_features_limits *limits, enum ast_bridge_hook_remove_flags remove_flags);
 628
 629 /*!
 630  * \brief Set a flag on a bridge channel features structure
 631  *
 632  * \param features Bridge channel features structure
 633  * \param flag Flag to enable
 634  *
 635  * \return Nothing
 636  *
 637  * Example usage:
 638  *
 639  * \code
 640  * struct ast_bridge_features features;
 641  * ast_bridge_features_init(&features);
 642  * ast_bridge_features_set_flag(&features, AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP);
 643  * \endcode
 644  *
 645  * This sets the AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP feature
 646  * to be enabled on the features structure 'features'.
 647  */
 648 void ast_bridge_features_set_flag(struct ast_bridge_features *features, unsigned int flag);
 649
 650 /*!
 651  * \brief Initialize bridge features structure
 652  *
 653  * \param features Bridge featues structure
 654  *
 655  * \retval 0 on success
 656  * \retval -1 on failure
 657  *
 658  * Example usage:
 659  *
 660  * \code
 661  * struct ast_bridge_features features;
 662  * ast_bridge_features_init(&features);
 663  * \endcode
 664  *
 665  * This initializes the feature structure 'features' to have nothing enabled.
 666  *
 667  * \note This MUST be called before enabling features or flags. Failure to do so
 668  *       may result in a crash.
 669  */
 670 int ast_bridge_features_init(struct ast_bridge_features *features);
 671
 672 /*!
 673  * \brief Clean up the contents of a bridge features structure
 674  *
 675  * \param features Bridge features structure
 676  *
 677  * \return Nothing
 678  *
 679  * Example usage:
 680  *
 681  * \code
 682  * struct ast_bridge_features features;
 683  * ast_bridge_features_init(&features);
 684  * ast_bridge_features_cleanup(&features);
 685  * \endcode
 686  *
 687  * This cleans up the feature structure 'features'.
 688  *
 689  * \note This MUST be called after the features structure is done being used
 690  *       or a memory leak may occur.
 691  */
 692 void ast_bridge_features_cleanup(struct ast_bridge_features *features);
 693
 694 /*!
 695  * \brief Allocate a new bridge features struct.
 696  * \since 12.0.0
 697  *
 698  * Example usage:
 699  *
 700  * \code
 701  * struct ast_bridge_features *features;
 702  * features = ast_bridge_features_new();
 703  * ast_bridge_features_destroy(features);
 704  * \endcode
 705  *
 706  * \retval features New allocated features struct.
 707  * \retval NULL on error.
 708  */
 709 struct ast_bridge_features *ast_bridge_features_new(void);
 710
 711 /*!
 712  * \brief Destroy an allocated bridge features struct.
 713  * \since 12.0.0
 714  *
 715  * \param features Bridge features structure
 716  *
 717  * Example usage:
 718  *
 719  * \code
 720  * struct ast_bridge_features *features;
 721  * features = ast_bridge_features_new();
 722  * ast_bridge_features_destroy(features);
 723  * \endcode
 724  *
 725  * \return Nothing
 726  */
 727 void ast_bridge_features_destroy(struct ast_bridge_features *features);
 728
 729 #if defined(__cplusplus) || defined(c_plusplus)
 730 }
 731 #endif
 732
 733 #endif /* _ASTERISK_BRIDGING_FEATURES_H */