include/asterisk/bridge_channel.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2013 Digium, Inc.
   5  *
   6  * Joshua Colp <jcolp@digium.com>
   7  * Richard Mudgett <rmudgett@digium.com>
   8  * Matt Jordan <mjordan@digium.com>
   9  *
  10  * See http://www.asterisk.org for more information about
  11  * the Asterisk project. Please do not directly contact
  12  * any of the maintainers of this project for assistance;
  13  * the project provides a web site, mailing lists and IRC
  14  * channels for your use.
  15  *
  16  * This program is free software, distributed under the terms of
  17  * the GNU General Public License Version 2. See the LICENSE file
  18  * at the top of the source tree.
  19  */
  20
  21 /*!
  22  * \file
  23  * \page AstBridgeChannel Bridging Channel API
  24  *
  25  * An API that act on a channel in a bridge. Note that while the
  26  * \ref ast_bridge_channel is owned by a channel, it should only be used
  27  * by members of the bridging system. The only places where this API should
  28  * be used is:
  29  *  \arg \ref AstBridging API itself
  30  *  \arg Bridge mixing technologies
  31  *  \arg Bridge sub-classes
  32  *
  33  * In general, anywhere else it is unsafe to use this API. Care should be
  34  * taken when using this API to ensure that the locking order remains
  35  * correct. The locking order must be:
  36  *  \arg The \ref \c ast_bridge
  37  *  \arg The \ref \c ast_bridge_channel
  38  *  \arg The \ref \c ast_channel
  39  *
  40  * \author Joshua Colp <jcolp@digium.com>
  41  * \author Richard Mudgett <rmudgett@digium.com>
  42  * \author Matt Jordan <mjordan@digium.com>
  43  *
  44  * See Also:
  45  * \arg \ref AstBridging
  46  * \arg \ref AstCREDITS
  47  */
  48
  49 #ifndef _ASTERISK_BRIDGING_CHANNEL_H
  50 #define _ASTERISK_BRIDGING_CHANNEL_H
  51
  52 #if defined(__cplusplus) || defined(c_plusplus)
  53 extern "C" {
  54 #endif
  55
  56 #include "asterisk/bridge_technology.h"
  57
  58 /*! \brief State information about a bridged channel */
  59 enum bridge_channel_state {
  60         /*! Waiting for a signal (Channel in the bridge) */
  61         BRIDGE_CHANNEL_STATE_WAIT = 0,
  62         /*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
  63         BRIDGE_CHANNEL_STATE_END,
  64         /*! Bridged channel was forced out. Don't dissolve the bridge regardless */
  65         BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE,
  66 };
  67
  68 enum bridge_channel_thread_state {
  69         /*! Bridge channel thread is idle/waiting. */
  70         BRIDGE_CHANNEL_THREAD_IDLE,
  71         /*! Bridge channel thread is writing a normal/simple frame. */
  72         BRIDGE_CHANNEL_THREAD_SIMPLE,
  73         /*! Bridge channel thread is processing a frame. */
  74         BRIDGE_CHANNEL_THREAD_FRAME,
  75 };
  76
  77 struct ast_bridge;
  78 struct ast_bridge_tech_optimizations;
  79
  80  /*!
  81  * \brief Structure that contains information regarding a channel in a bridge
  82  */
  83 struct ast_bridge_channel {
  84 /* XXX ASTERISK-21271 cond is only here because of external party suspend/unsuspend support. */
  85         /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
  86         ast_cond_t cond;
  87         /*! Current bridged channel state */
  88         enum bridge_channel_state state;
  89         /*! Asterisk channel participating in the bridge */
  90         struct ast_channel *chan;
  91         /*! Asterisk channel we are swapping with (if swapping) */
  92         struct ast_channel *swap;
  93         /*!
  94          * \brief Bridge this channel is participating in
  95          *
  96          * \note The bridge pointer cannot change while the bridge or
  97          * bridge_channel is locked.
  98          */
  99         struct ast_bridge *bridge;
 100         /*!
 101          * \brief Bridge class private channel data.
 102          *
 103          * \note This information is added when the channel is pushed
 104          * into the bridge and removed when it is pulled from the
 105          * bridge.
 106          */
 107         void *bridge_pvt;
 108         /*!
 109          * \brief Private information unique to the bridge technology.
 110          *
 111          * \note This information is added when the channel joins the
 112          * bridge's technology and removed when it leaves the bridge's
 113          * technology.
 114          */
 115         void *tech_pvt;
 116         /*! Thread handling the bridged channel (Needed by ast_bridge_depart) */
 117         pthread_t thread;
 118         /* v-- These flags change while the bridge is locked or before the channel is in the bridge. */
 119         /*! TRUE if the channel is in a bridge. */
 120         unsigned int in_bridge:1;
 121         /*! TRUE if the channel just joined the bridge. */
 122         unsigned int just_joined:1;
 123         /*! TRUE if the channel is suspended from the bridge. */
 124         unsigned int suspended:1;
 125         /*! TRUE if the COLP update on initial join is inhibited. */
 126         unsigned int inhibit_colp:1;
 127         /*! TRUE if the channel must wait for an ast_bridge_depart to reclaim the channel. */
 128         unsigned int depart_wait:1;
 129         /* ^-- These flags change while the bridge is locked or before the channel is in the bridge. */
 130         /*! Features structure for features that are specific to this channel */
 131         struct ast_bridge_features *features;
 132         /*! Technology optimization parameters used by bridging technologies capable of
 133          *  optimizing based upon talk detection. */
 134         struct ast_bridge_tech_optimizations tech_args;
 135         /*! Copy of read format used by chan before join */
 136         struct ast_format read_format;
 137         /*! Copy of write format used by chan before join */
 138         struct ast_format write_format;
 139         /*! Call ID associated with bridge channel */
 140         struct ast_callid *callid;
 141         /*! A clone of the roles living on chan when the bridge channel joins the bridge. This may require some opacification */
 142         struct bridge_roles_datastore *bridge_roles;
 143         /*! Linked list information */
 144         AST_LIST_ENTRY(ast_bridge_channel) entry;
 145         /*! Queue of outgoing frames to the channel. */
 146         AST_LIST_HEAD_NOLOCK(, ast_frame) wr_queue;
 147         /*! Pipe to alert thread when frames are put into the wr_queue. */
 148         int alert_pipe[2];
 149         /*!
 150          * \brief The bridge channel thread activity.
 151          *
 152          * \details Used by local channel optimization to determine if
 153          * the thread is in an acceptable state to optimize.
 154          *
 155          * \note Needs to be atomically settable.
 156          */
 157         enum bridge_channel_thread_state activity;
 158         /*! Owed events to the bridge. */
 159         struct {
 160                 /*! Time started sending the current digit. (Invalid if owed.dtmf_digit is zero.) */
 161                 struct timeval dtmf_tv;
 162                 /*! Digit currently sending into the bridge. (zero if not sending) */
 163                 char dtmf_digit;
 164         } owed;
 165 };
 166
 167 /*!
 168  * \brief Try locking the bridge_channel.
 169  *
 170  * \param bridge_channel What to try locking
 171  *
 172  * \retval 0 on success.
 173  * \retval non-zero on error.
 174  */
 175 #define ast_bridge_channel_trylock(bridge_channel)      _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
 176 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
 177 {
 178         return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
 179 }
 180
 181 /*!
 182  * \brief Lock the bridge_channel.
 183  *
 184  * \param bridge_channel What to lock
 185  *
 186  * \return Nothing
 187  */
 188 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
 189 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
 190 {
 191         __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
 192 }
 193
 194 /*!
 195  * \brief Unlock the bridge_channel.
 196  *
 197  * \param bridge_channel What to unlock
 198  *
 199  * \return Nothing
 200  */
 201 #define ast_bridge_channel_unlock(bridge_channel)       _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
 202 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
 203 {
 204         __ao2_unlock(bridge_channel, file, function, line, var);
 205 }
 206
 207 /*!
 208  * \brief Lock the bridge associated with the bridge channel.
 209  * \since 12.0.0
 210  *
 211  * \param bridge_channel Channel that wants to lock the bridge.
 212  *
 213  * \details
 214  * This is an upstream lock operation.  The defined locking
 215  * order is bridge then bridge_channel.
 216  *
 217  * \note On entry, neither the bridge nor bridge_channel is locked.
 218  *
 219  * \note The bridge_channel->bridge pointer changes because of a
 220  * bridge-merge/channel-move operation between bridges.
 221  *
 222  * \return Nothing
 223  */
 224 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
 225
 226 /*!
 227  * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
 228  *
 229  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
 230  * layer, which in this case is the specific bridging technology being used. Since it
 231  * is necessary for the knowledge of which channels are talking to make its way up to the
 232  * application, this function has been created to allow the bridging technology to communicate
 233  * that information with the bridging core.
 234  *
 235  * \param bridge_channel The bridge channel that has either started or stopped talking.
 236  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
 237  * when this indicates the channel has stopped talking.
 238  *
 239  * \retval 0 on success.
 240  * \retval -1 on error.
 241  */
 242 int ast_bridge_channel_notify_talking(struct ast_bridge_channel *bridge_channel, int started_talking);
 243
 244 /*!
 245  * \brief Set bridge channel state to leave bridge (if not leaving already).
 246  *
 247  * \param bridge_channel Channel to change the state on
 248  * \param new_state The new state to place the channel into
 249  * \param cause Cause of channel leaving bridge.
 250  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
 251  *
 252  * Example usage:
 253  *
 254  * \code
 255  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
 256  * \endcode
 257  *
 258  * This places the channel pointed to by bridge_channel into the
 259  * state BRIDGE_CHANNEL_STATE_END if it was
 260  * BRIDGE_CHANNEL_STATE_WAIT before.
 261  */
 262 void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
 263
 264 /*!
 265  * \brief Set bridge channel state to leave bridge (if not leaving already).
 266  *
 267  * \param bridge_channel Channel to change the state on
 268  * \param new_state The new state to place the channel into
 269  * \param cause Cause of channel leaving bridge.
 270  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
 271  *
 272  * Example usage:
 273  *
 274  * \code
 275  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
 276  * \endcode
 277  *
 278  * This places the channel pointed to by bridge_channel into the
 279  * state BRIDGE_CHANNEL_STATE_END if it was
 280  * BRIDGE_CHANNEL_STATE_WAIT before.
 281  */
 282 void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
 283
 284 /*!
 285  * \brief Get the peer bridge channel of a two party bridge.
 286  * \since 12.0.0
 287  *
 288  * \param bridge_channel What to get the peer of.
 289  *
 290  * \note On entry, bridge_channel->bridge is already locked.
 291  *
 292  * \note This is an internal bridge function.
 293  *
 294  * \retval peer on success.
 295  * \retval NULL no peer channel.
 296  */
 297 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
 298
 299 /*!
 300  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_internal_join
 301  * \since 12.0.0
 302  *
 303  * \param bridge_channel Channel to restore
 304  */
 305 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
 306
 307 /*!
 308  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
 309  * \since 12.0.0
 310  *
 311  * \param bridge_channel What to operate on.
 312  * \param request Inhibit request increment.
 313  *     (Positive to add requests.  Negative to remove requests.)
 314  *
 315  * \note This API call is meant for internal bridging operations.
 316  *
 317  * \retval bridge adjusted merge inhibit with reference count.
 318  */
 319 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
 320
 321 /*!
 322  * \internal
 323  * \brief Update the linkedids for all channels in a bridge
 324  * \since 12.0.0
 325  *
 326  * \param bridge_channel The channel joining the bridge
 327  * \param swap The channel being swapped out of the bridge. May be NULL.
 328  *
 329  * \note The bridge must be locked prior to calling this function. This should be called
 330  * during a \ref bridge_channel_internal_push operation, typically by a sub-class of a bridge
 331  */
 332 void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
 333
 334 /*!
 335  * \internal
 336  * \brief Update the accountcodes for a channel entering a bridge
 337  * \since 12.0.0
 338  *
 339  * This function updates the accountcode and peeraccount on channels in two-party
 340  * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
 341  * however accountcode propagation will still occur if the channel joining has an
 342  * accountcode.
 343  *
 344  * \param bridge_channel The channel joining the bridge
 345  * \param swap The channel being swapped out of the bridge. May be NULL.
 346  *
 347  * \note The bridge must be locked prior to calling this function. This should be called
 348  * during a \ref bridge_channel_internal_push operation, typically by a sub-class of a bridge
 349  */
 350 void ast_bridge_channel_update_accountcodes(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
 351
 352 /*!
 353  * \brief Write a frame to the specified bridge_channel.
 354  * \since 12.0.0
 355  *
 356  * \param bridge_channel Channel to queue the frame.
 357  * \param fr Frame to write.
 358  *
 359  * \retval 0 on success.
 360  * \retval -1 on error.
 361  */
 362 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
 363
 364 /*!
 365  * \brief Queue a control frame onto the bridge channel with data.
 366  * \since 12.0.0
 367  *
 368  * \param bridge_channel Which channel to queue the frame onto.
 369  * \param control Type of control frame.
 370  * \param data Frame payload data to pass.
 371  * \param datalen Frame payload data length to pass.
 372  *
 373  * \retval 0 on success.
 374  * \retval -1 on error.
 375  */
 376 int ast_bridge_channel_queue_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
 377
 378 /*!
 379  * \brief Write a control frame into the bridge with data.
 380  * \since 12.0.0
 381  *
 382  * \param bridge_channel Which channel is putting the frame into the bridge.
 383  * \param control Type of control frame.
 384  * \param data Frame payload data to pass.
 385  * \param datalen Frame payload data length to pass.
 386  *
 387  * \retval 0 on success.
 388  * \retval -1 on error.
 389  */
 390 int ast_bridge_channel_write_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
 391
 392 /*!
 393  * \brief Write a hold frame into the bridge.
 394  * \since 12.0.0
 395  *
 396  * \param bridge_channel Which channel is putting the hold into the bridge.
 397  * \param moh_class The suggested music class for the other end to use.
 398  *
 399  * \retval 0 on success.
 400  * \retval -1 on error.
 401  */
 402 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
 403
 404 /*!
 405  * \brief Write an unhold frame into the bridge.
 406  * \since 12.0.0
 407  *
 408  * \param bridge_channel Which channel is putting the hold into the bridge.
 409  *
 410  * \retval 0 on success.
 411  * \retval -1 on error.
 412  */
 413 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
 414
 415 /*!
 416  * \brief Run an application on the bridge channel.
 417  * \since 12.0.0
 418  *
 419  * \param bridge_channel Which channel to run the application on.
 420  * \param app_name Dialplan application name.
 421  * \param app_args Arguments for the application. (NULL tolerant)
 422  * \param moh_class MOH class to request bridge peers to hear while application is running.
 423  *     NULL if no MOH.
 424  *     Empty if default MOH class.
 425  *
 426  * \note This is intended to be called by bridge hooks.
 427  *
 428  * \return Nothing
 429  */
 430 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
 431
 432 /*!
 433  * \brief Write a bridge action run application frame into the bridge.
 434  * \since 12.0.0
 435  *
 436  * \param bridge_channel Which channel is putting the frame into the bridge
 437  * \param app_name Dialplan application name.
 438  * \param app_args Arguments for the application. (NULL or empty for no arguments)
 439  * \param moh_class MOH class to request bridge peers to hear while application is running.
 440  *     NULL if no MOH.
 441  *     Empty if default MOH class.
 442  *
 443  * \note This is intended to be called by bridge hooks.
 444  *
 445  * \retval 0 on success.
 446  * \retval -1 on error.
 447  */
 448 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
 449
 450 /*!
 451  * \brief Queue a bridge action run application frame onto the bridge channel.
 452  * \since 12.0.0
 453  *
 454  * \param bridge_channel Which channel to put the frame onto
 455  * \param app_name Dialplan application name.
 456  * \param app_args Arguments for the application. (NULL or empty for no arguments)
 457  * \param moh_class MOH class to request bridge peers to hear while application is running.
 458  *     NULL if no MOH.
 459  *     Empty if default MOH class.
 460  *
 461  * \note This is intended to be called by bridge hooks.
 462  *
 463  * \retval 0 on success.
 464  * \retval -1 on error.
 465  */
 466 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
 467
 468 /*!
 469  * \brief Custom interpretation of the playfile name.
 470  *
 471  * \param bridge_channel Which channel to play the file on
 472  * \param playfile Sound filename to play.
 473  *
 474  * \return Nothing
 475  */
 476 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
 477
 478 /*!
 479  * \brief Play a file on the bridge channel.
 480  * \since 12.0.0
 481  *
 482  * \param bridge_channel Which channel to play the file on
 483  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
 484  * \param playfile Sound filename to play.
 485  * \param moh_class MOH class to request bridge peers to hear while file is played.
 486  *     NULL if no MOH.
 487  *     Empty if default MOH class.
 488  *
 489  * \note This is intended to be called by bridge hooks.
 490  *
 491  * \return Nothing
 492  */
 493 void ast_bridge_channel_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
 494
 495 /*!
 496  * \brief Write a bridge action play file frame into the bridge.
 497  * \since 12.0.0
 498  *
 499  * \param bridge_channel Which channel is putting the frame into the bridge
 500  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
 501  * \param playfile Sound filename to play.
 502  * \param moh_class MOH class to request bridge peers to hear while file is played.
 503  *     NULL if no MOH.
 504  *     Empty if default MOH class.
 505  *
 506  * \note This is intended to be called by bridge hooks.
 507  *
 508  * \retval 0 on success.
 509  * \retval -1 on error.
 510  */
 511 int ast_bridge_channel_write_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
 512
 513 /*!
 514  * \brief Queue a bridge action play file frame onto the bridge channel.
 515  * \since 12.0.0
 516  *
 517  * \param bridge_channel Which channel to put the frame onto.
 518  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
 519  * \param playfile Sound filename to play.
 520  * \param moh_class MOH class to request bridge peers to hear while file is played.
 521  *     NULL if no MOH.
 522  *     Empty if default MOH class.
 523  *
 524  * \note This is intended to be called by bridge hooks.
 525  *
 526  * \retval 0 on success.
 527  * \retval -1 on error.
 528  */
 529 int ast_bridge_channel_queue_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
 530
 531 /*!
 532  * \brief Custom callback run on a bridge channel.
 533  *
 534  * \param bridge_channel Which channel to operate on.
 535  * \param payload Data to pass to the callback. (NULL if none).
 536  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
 537  *
 538  * \note The payload MUST NOT have any resources that need to be freed.
 539  *
 540  * \return Nothing
 541  */
 542 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
 543
 544 enum ast_bridge_channel_custom_callback_option {
 545         /*! The callback temporarily affects media. (Like a custom playfile.) */
 546         AST_BRIDGE_CHANNEL_CB_OPTION_MEDIA = (1 << 0),
 547 };
 548
 549 /*!
 550  * \brief Write a bridge action custom callback frame into the bridge.
 551  * \since 12.0.0
 552  *
 553  * \param bridge_channel Which channel is putting the frame into the bridge
 554  * \param flags Custom callback option flags.
 555  * \param callback Custom callback run on a bridge channel.
 556  * \param payload Data to pass to the callback. (NULL if none).
 557  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
 558  *
 559  * \note The payload MUST NOT have any resources that need to be freed.
 560  *
 561  * \note This is intended to be called by bridge hooks.
 562  *
 563  * \retval 0 on success.
 564  * \retval -1 on error.
 565  */
 566 int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel,
 567         enum ast_bridge_channel_custom_callback_option flags,
 568         ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
 569
 570 /*!
 571  * \brief Queue a bridge action custom callback frame onto the bridge channel.
 572  * \since 12.0.0
 573  *
 574  * \param bridge_channel Which channel to put the frame onto.
 575  * \param flags Custom callback option flags.
 576  * \param callback Custom callback run on a bridge channel.
 577  * \param payload Data to pass to the callback. (NULL if none).
 578  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
 579  *
 580  * \note The payload MUST NOT have any resources that need to be freed.
 581  *
 582  * \note This is intended to be called by bridge hooks.
 583  *
 584  * \retval 0 on success.
 585  * \retval -1 on error.
 586  */
 587 int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel,
 588         enum ast_bridge_channel_custom_callback_option flags,
 589         ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
 590
 591 /*!
 592  * \brief Have a bridge channel park a channel in the bridge
 593  * \since 12.0.0
 594  *
 595  * \param bridge_channel Bridge channel performing the parking
 596  * \param parkee_uuid Unique id of the channel we want to park
 597  * \param parker_uuid Unique id of the channel parking the call
 598  * \param app_data string indicating data used for park application (NULL allowed)
 599  *
 600  * \note This is intended to be called by bridge hooks.
 601  *
 602  * \retval 0 on success.
 603  * \retval -1 on error.
 604  */
 605 int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
 606         const char *parker_uuid, const char *app_data);
 607
 608 /*!
 609  * \brief Kick the channel out of the bridge.
 610  * \since 12.0.0
 611  *
 612  * \param bridge_channel Which channel is being kicked or hungup.
 613  * \param cause Cause of channel being kicked.
 614  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
 615  *
 616  * \note This is intended to be called by bridge hooks and the
 617  * bridge channel thread.
 618  *
 619  * \return Nothing
 620  */
 621 void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause);
 622
 623 #if defined(__cplusplus) || defined(c_plusplus)
 624 }
 625 #endif
 626
 627 #endif  /* _ASTERISK_BRIDGING_CHANNEL_H */