bridge_channel.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2013 Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  * Richard Mudgett <rmudgett@digium.com>
00008  * Matt Jordan <mjordan@digium.com>
00009  *
00010  * See http://www.asterisk.org for more information about
00011  * the Asterisk project. Please do not directly contact
00012  * any of the maintainers of this project for assistance;
00013  * the project provides a web site, mailing lists and IRC
00014  * channels for your use.
00015  *
00016  * This program is free software, distributed under the terms of
00017  * the GNU General Public License Version 2. See the LICENSE file
00018  * at the top of the source tree.
00019  */
00020 
00021 /*!
00022  * \file
00023  * \page AstBridgeChannel Bridging Channel API
00024  *
00025  * An API that act on a channel in a bridge. Note that while the
00026  * \ref ast_bridge_channel is owned by a channel, it should only be used
00027  * by members of the bridging system. The only places where this API should
00028  * be used is:
00029  *  \arg \ref AstBridging API itself
00030  *  \arg Bridge mixing technologies
00031  *  \arg Bridge sub-classes
00032  *
00033  * In general, anywhere else it is unsafe to use this API. Care should be
00034  * taken when using this API to ensure that the locking order remains
00035  * correct. The locking order must be:
00036  *  \arg The \ref \c ast_bridge
00037  *  \arg The \ref \c ast_bridge_channel
00038  *  \arg The \ref \c ast_channel
00039  *
00040  * \author Joshua Colp <jcolp@digium.com>
00041  * \author Richard Mudgett <rmudgett@digium.com>
00042  * \author Matt Jordan <mjordan@digium.com>
00043  *
00044  * See Also:
00045  * \arg \ref AstBridging
00046  * \arg \ref AstCREDITS
00047  */
00048 
00049 #ifndef _ASTERISK_BRIDGING_CHANNEL_H
00050 #define _ASTERISK_BRIDGING_CHANNEL_H
00051 
00052 #if defined(__cplusplus) || defined(c_plusplus)
00053 extern "C" {
00054 #endif
00055 
00056 #include "asterisk/bridge_features.h"
00057 #include "asterisk/bridge_technology.h"
00058 
00059 /*! \brief State information about a bridged channel */
00060 enum bridge_channel_state {
00061    /*! Waiting for a signal (Channel in the bridge) */
00062    BRIDGE_CHANNEL_STATE_WAIT = 0,
00063    /*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
00064    BRIDGE_CHANNEL_STATE_END,
00065    /*! Bridged channel was forced out. Don't dissolve the bridge regardless */
00066    BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE,
00067 };
00068 
00069 enum bridge_channel_thread_state {
00070    /*! Bridge channel thread is idle/waiting. */
00071    BRIDGE_CHANNEL_THREAD_IDLE,
00072    /*! Bridge channel thread is writing a normal/simple frame. */
00073    BRIDGE_CHANNEL_THREAD_SIMPLE,
00074    /*! Bridge channel thread is processing a frame. */
00075    BRIDGE_CHANNEL_THREAD_FRAME,
00076 };
00077 
00078 struct ast_bridge;
00079 struct ast_bridge_tech_optimizations;
00080 
00081  /*!
00082  * \brief Structure that contains information regarding a channel in a bridge
00083  */
00084 struct ast_bridge_channel {
00085 /* XXX ASTERISK-21271 cond is only here because of external party suspend/unsuspend support. */
00086    /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
00087    ast_cond_t cond;
00088    /*! Current bridged channel state */
00089    enum bridge_channel_state state;
00090    /*! Asterisk channel participating in the bridge */
00091    struct ast_channel *chan;
00092    /*! Asterisk channel we are swapping with (if swapping) */
00093    struct ast_channel *swap;
00094    /*!
00095     * \brief Bridge this channel is participating in
00096     *
00097     * \note The bridge pointer cannot change while the bridge or
00098     * bridge_channel is locked.
00099     */
00100    struct ast_bridge *bridge;
00101    /*!
00102     * \brief Bridge class private channel data.
00103     *
00104     * \note This information is added when the channel is pushed
00105     * into the bridge and removed when it is pulled from the
00106     * bridge.
00107     */
00108    void *bridge_pvt;
00109    /*!
00110     * \brief Private information unique to the bridge technology.
00111     *
00112     * \note This information is added when the channel joins the
00113     * bridge's technology and removed when it leaves the bridge's
00114     * technology.
00115     */
00116    void *tech_pvt;
00117    /*! Thread handling the bridged channel (Needed by ast_bridge_depart) */
00118    pthread_t thread;
00119    /* v-- These flags change while the bridge is locked or before the channel is in the bridge. */
00120    /*! TRUE if the channel is in a bridge. */
00121    unsigned int in_bridge:1;
00122    /*! TRUE if the channel just joined the bridge. */
00123    unsigned int just_joined:1;
00124    /*! TRUE if the channel is suspended from the bridge. */
00125    unsigned int suspended:1;
00126    /*! TRUE if the COLP update on initial join is inhibited. */
00127    unsigned int inhibit_colp:1;
00128    /*! TRUE if the channel must wait for an ast_bridge_depart to reclaim the channel. */
00129    unsigned int depart_wait:1;
00130    /* ^-- These flags change while the bridge is locked or before the channel is in the bridge. */
00131    /*! Features structure for features that are specific to this channel */
00132    struct ast_bridge_features *features;
00133    /*! Technology optimization parameters used by bridging technologies capable of
00134     *  optimizing based upon talk detection. */
00135    struct ast_bridge_tech_optimizations tech_args;
00136    /*! Copy of read format used by chan before join */
00137    struct ast_format *read_format;
00138    /*! Copy of write format used by chan before join */
00139    struct ast_format *write_format;
00140    /*! Call ID associated with bridge channel */
00141    ast_callid callid;
00142    /*! A clone of the roles living on chan when the bridge channel joins the bridge. This may require some opacification */
00143    struct bridge_roles_datastore *bridge_roles;
00144    /*! Linked list information */
00145    AST_LIST_ENTRY(ast_bridge_channel) entry;
00146    /*! Queue of outgoing frames to the channel. */
00147    AST_LIST_HEAD_NOLOCK(, ast_frame) wr_queue;
00148    /*! Pipe to alert thread when frames are put into the wr_queue. */
00149    int alert_pipe[2];
00150    /*!
00151     * \brief The bridge channel thread activity.
00152     *
00153     * \details Used by local channel optimization to determine if
00154     * the thread is in an acceptable state to optimize.
00155     *
00156     * \note Needs to be atomically settable.
00157     */
00158    enum bridge_channel_thread_state activity;
00159    /*! Owed events to the bridge. */
00160    struct {
00161       /*! Time started sending the current digit. (Invalid if owed.dtmf_digit is zero.) */
00162       struct timeval dtmf_tv;
00163       /*! Digit currently sending into the bridge. (zero if not sending) */
00164       char dtmf_digit;
00165    } owed;
00166    /*! DTMF hook sequence state */
00167    struct {
00168       /*! Time at which the DTMF hooks should stop waiting for more digits to come. */
00169       struct timeval interdigit_timeout;
00170       /*! Collected DTMF digits for DTMF hooks. */
00171       char collected[MAXIMUM_DTMF_FEATURE_STRING];
00172    } dtmf_hook_state;
00173 };
00174 
00175 /*!
00176  * \brief Try locking the bridge_channel.
00177  *
00178  * \param bridge_channel What to try locking
00179  *
00180  * \retval 0 on success.
00181  * \retval non-zero on error.
00182  */
00183 #define ast_bridge_channel_trylock(bridge_channel) _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
00184 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
00185 {
00186    return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
00187 }
00188 
00189 /*!
00190  * \brief Lock the bridge_channel.
00191  *
00192  * \param bridge_channel What to lock
00193  *
00194  * \return Nothing
00195  */
00196 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
00197 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
00198 {
00199    __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
00200 }
00201 
00202 /*!
00203  * \brief Unlock the bridge_channel.
00204  *
00205  * \param bridge_channel What to unlock
00206  *
00207  * \return Nothing
00208  */
00209 #define ast_bridge_channel_unlock(bridge_channel)  _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
00210 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
00211 {
00212    __ao2_unlock(bridge_channel, file, function, line, var);
00213 }
00214 
00215 /*!
00216  * \brief Lock the bridge associated with the bridge channel.
00217  * \since 12.0.0
00218  *
00219  * \param bridge_channel Channel that wants to lock the bridge.
00220  *
00221  * \details
00222  * This is an upstream lock operation.  The defined locking
00223  * order is bridge then bridge_channel.
00224  *
00225  * \note On entry, neither the bridge nor bridge_channel is locked.
00226  *
00227  * \note The bridge_channel->bridge pointer changes because of a
00228  * bridge-merge/channel-move operation between bridges.
00229  *
00230  * \return Nothing
00231  */
00232 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
00233 
00234 /*!
00235  * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
00236  *
00237  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
00238  * layer, which in this case is the specific bridging technology being used. Since it
00239  * is necessary for the knowledge of which channels are talking to make its way up to the
00240  * application, this function has been created to allow the bridging technology to communicate
00241  * that information with the bridging core.
00242  *
00243  * \param bridge_channel The bridge channel that has either started or stopped talking.
00244  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
00245  * when this indicates the channel has stopped talking.
00246  *
00247  * \retval 0 on success.
00248  * \retval -1 on error.
00249  */
00250 int ast_bridge_channel_notify_talking(struct ast_bridge_channel *bridge_channel, int started_talking);
00251 
00252 /*!
00253  * \brief Set bridge channel state to leave bridge (if not leaving already).
00254  *
00255  * \param bridge_channel Channel to change the state on
00256  * \param new_state The new state to place the channel into
00257  * \param cause Cause of channel leaving bridge.
00258  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
00259  *
00260  * Example usage:
00261  *
00262  * \code
00263  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
00264  * \endcode
00265  *
00266  * This places the channel pointed to by bridge_channel into the
00267  * state BRIDGE_CHANNEL_STATE_END if it was
00268  * BRIDGE_CHANNEL_STATE_WAIT before.
00269  */
00270 void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
00271 
00272 /*!
00273  * \brief Set bridge channel state to leave bridge (if not leaving already).
00274  *
00275  * \param bridge_channel Channel to change the state on
00276  * \param new_state The new state to place the channel into
00277  * \param cause Cause of channel leaving bridge.
00278  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
00279  *
00280  * Example usage:
00281  *
00282  * \code
00283  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
00284  * \endcode
00285  *
00286  * This places the channel pointed to by bridge_channel into the
00287  * state BRIDGE_CHANNEL_STATE_END if it was
00288  * BRIDGE_CHANNEL_STATE_WAIT before.
00289  */
00290 void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
00291 
00292 /*!
00293  * \brief Get the peer bridge channel of a two party bridge.
00294  * \since 12.0.0
00295  *
00296  * \param bridge_channel What to get the peer of.
00297  *
00298  * \note On entry, bridge_channel->bridge is already locked.
00299  *
00300  * \note This is an internal bridge function.
00301  *
00302  * \retval peer on success.
00303  * \retval NULL no peer channel.
00304  */
00305 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
00306 
00307 /*!
00308  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_internal_join
00309  * \since 12.0.0
00310  *
00311  * \param bridge_channel Channel to restore
00312  */
00313 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
00314 
00315 /*!
00316  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
00317  * \since 12.0.0
00318  *
00319  * \param bridge_channel What to operate on.
00320  * \param request Inhibit request increment.
00321  *     (Positive to add requests.  Negative to remove requests.)
00322  *
00323  * \note This API call is meant for internal bridging operations.
00324  *
00325  * \retval bridge adjusted merge inhibit with reference count.
00326  */
00327 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
00328 
00329 /*!
00330  * \internal
00331  * \brief Update the linkedids for all channels in a bridge
00332  * \since 12.0.0
00333  *
00334  * \param bridge_channel The channel joining the bridge
00335  * \param swap The channel being swapped out of the bridge. May be NULL.
00336  *
00337  * \note The bridge must be locked prior to calling this function.
00338  * \note This should be called during a \ref bridge_channel_internal_push
00339  * operation, typically by a sub-class of a bridge.
00340  */
00341 void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
00342 
00343 /*!
00344  * \internal
00345  * \brief Update the accountcodes for channels joining/leaving a bridge
00346  * \since 12.0.0
00347  *
00348  * This function updates the accountcode and peeraccount on channels in two-party
00349  * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
00350  * however accountcode propagation will still occur if the channel joining has an
00351  * accountcode.
00352  *
00353  * \param joining The channel joining the bridge.  May be NULL.
00354  * \param leaving The channel leaving or being swapped out of the bridge. May be NULL.
00355  *
00356  * \note The joining and leaving parameters cannot both be NULL.
00357  *
00358  * \note The bridge must be locked prior to calling this function.
00359  * \note This should be called during a \ref bridge_channel_internal_push
00360  * or \ref bridge_channel_internal_pull operation, typically by a
00361  * sub-class of a bridge.
00362  */
00363 void ast_bridge_channel_update_accountcodes(struct ast_bridge_channel *joining, struct ast_bridge_channel *leaving);
00364 
00365 /*!
00366  * \brief Write a frame to the specified bridge_channel.
00367  * \since 12.0.0
00368  *
00369  * \param bridge_channel Channel to queue the frame.
00370  * \param fr Frame to write.
00371  *
00372  * \retval 0 on success.
00373  * \retval -1 on error.
00374  */
00375 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
00376 
00377 /*!
00378  * \brief Queue a control frame onto the bridge channel with data.
00379  * \since 12.0.0
00380  *
00381  * \param bridge_channel Which channel to queue the frame onto.
00382  * \param control Type of control frame.
00383  * \param data Frame payload data to pass.
00384  * \param datalen Frame payload data length to pass.
00385  *
00386  * \retval 0 on success.
00387  * \retval -1 on error.
00388  */
00389 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);
00390 
00391 /*!
00392  * \brief Write a control frame into the bridge with data.
00393  * \since 12.0.0
00394  *
00395  * \param bridge_channel Which channel is putting the frame into the bridge.
00396  * \param control Type of control frame.
00397  * \param data Frame payload data to pass.
00398  * \param datalen Frame payload data length to pass.
00399  *
00400  * \retval 0 on success.
00401  * \retval -1 on error.
00402  */
00403 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);
00404 
00405 /*!
00406  * \brief Write a hold frame into the bridge.
00407  * \since 12.0.0
00408  *
00409  * \param bridge_channel Which channel is putting the hold into the bridge.
00410  * \param moh_class The suggested music class for the other end to use.
00411  *
00412  * \retval 0 on success.
00413  * \retval -1 on error.
00414  */
00415 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
00416 
00417 /*!
00418  * \brief Write an unhold frame into the bridge.
00419  * \since 12.0.0
00420  *
00421  * \param bridge_channel Which channel is putting the hold into the bridge.
00422  *
00423  * \retval 0 on success.
00424  * \retval -1 on error.
00425  */
00426 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
00427 
00428 /*!
00429  * \brief Run an application on the bridge channel.
00430  * \since 12.0.0
00431  *
00432  * \param bridge_channel Which channel to run the application on.
00433  * \param app_name Dialplan application name.
00434  * \param app_args Arguments for the application. (NULL tolerant)
00435  * \param moh_class MOH class to request bridge peers to hear while application is running.
00436  *     NULL if no MOH.
00437  *     Empty if default MOH class.
00438  *
00439  * \note This is intended to be called by bridge hooks.
00440  *
00441  * \return Nothing
00442  */
00443 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
00444 
00445 /*!
00446  * \brief Write a bridge action run application frame into the bridge.
00447  * \since 12.0.0
00448  *
00449  * \param bridge_channel Which channel is putting the frame into the bridge
00450  * \param app_name Dialplan application name.
00451  * \param app_args Arguments for the application. (NULL or empty for no arguments)
00452  * \param moh_class MOH class to request bridge peers to hear while application is running.
00453  *     NULL if no MOH.
00454  *     Empty if default MOH class.
00455  *
00456  * \note This is intended to be called by bridge hooks.
00457  *
00458  * \retval 0 on success.
00459  * \retval -1 on error.
00460  */
00461 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
00462 
00463 /*!
00464  * \brief Queue a bridge action run application frame onto the bridge channel.
00465  * \since 12.0.0
00466  *
00467  * \param bridge_channel Which channel to put the frame onto
00468  * \param app_name Dialplan application name.
00469  * \param app_args Arguments for the application. (NULL or empty for no arguments)
00470  * \param moh_class MOH class to request bridge peers to hear while application is running.
00471  *     NULL if no MOH.
00472  *     Empty if default MOH class.
00473  *
00474  * \note This is intended to be called by bridge hooks.
00475  *
00476  * \retval 0 on success.
00477  * \retval -1 on error.
00478  */
00479 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
00480 
00481 /*!
00482  * \brief Custom interpretation of the playfile name.
00483  *
00484  * \param bridge_channel Which channel to play the file on
00485  * \param playfile Sound filename to play.
00486  *
00487  * \return Nothing
00488  */
00489 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
00490 
00491 /*!
00492  * \brief Play a file on the bridge channel.
00493  * \since 12.0.0
00494  *
00495  * \param bridge_channel Which channel to play the file on
00496  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
00497  * \param playfile Sound filename to play.
00498  * \param moh_class MOH class to request bridge peers to hear while file is played.
00499  *     NULL if no MOH.
00500  *     Empty if default MOH class.
00501  *
00502  * \note This is intended to be called by bridge hooks.
00503  *
00504  * \return Nothing
00505  */
00506 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);
00507 
00508 /*!
00509  * \brief Write a bridge action play file frame into the bridge.
00510  * \since 12.0.0
00511  *
00512  * \param bridge_channel Which channel is putting the frame into the bridge
00513  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
00514  * \param playfile Sound filename to play.
00515  * \param moh_class MOH class to request bridge peers to hear while file is played.
00516  *     NULL if no MOH.
00517  *     Empty if default MOH class.
00518  *
00519  * \note This is intended to be called by bridge hooks.
00520  *
00521  * \retval 0 on success.
00522  * \retval -1 on error.
00523  */
00524 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);
00525 
00526 /*!
00527  * \brief Queue a bridge action play file frame onto the bridge channel.
00528  * \since 12.0.0
00529  *
00530  * \param bridge_channel Which channel to put the frame onto.
00531  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
00532  * \param playfile Sound filename to play.
00533  * \param moh_class MOH class to request bridge peers to hear while file is played.
00534  *     NULL if no MOH.
00535  *     Empty if default MOH class.
00536  *
00537  * \note This is intended to be called by bridge hooks.
00538  *
00539  * \retval 0 on success.
00540  * \retval -1 on error.
00541  */
00542 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);
00543 
00544 /*!
00545  * \brief Synchronously queue a bridge action play file frame onto the bridge channel.
00546  * \since 12.2.0
00547  *
00548  * \param bridge_channel Which channel to put the frame onto.
00549  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
00550  * \param playfile Sound filename to play.
00551  * \param moh_class MOH class to request bridge peers to hear while file is played.
00552  *     NULL if no MOH.
00553  *     Empty if default MOH class.
00554  *
00555  * This function will block until the queued frame has been destroyed. This will happen
00556  * either if an error occurs or if the queued playback finishes.
00557  *
00558  * \note No locks may be held when calling this function.
00559  *
00560  * \retval 0 The playback was successfully queued.
00561  * \retval -1 The playback could not be queued.
00562  */
00563 int ast_bridge_channel_queue_playfile_sync(struct ast_bridge_channel *bridge_channel,
00564       ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
00565 
00566 /*!
00567  * \brief Custom callback run on a bridge channel.
00568  *
00569  * \param bridge_channel Which channel to operate on.
00570  * \param payload Data to pass to the callback. (NULL if none).
00571  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
00572  *
00573  * \note The payload MUST NOT have any resources that need to be freed.
00574  *
00575  * \return Nothing
00576  */
00577 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
00578 
00579 enum ast_bridge_channel_custom_callback_option {
00580    /*! The callback temporarily affects media. (Like a custom playfile.) */
00581    AST_BRIDGE_CHANNEL_CB_OPTION_MEDIA = (1 << 0),
00582 };
00583 
00584 /*!
00585  * \brief Write a bridge action custom callback frame into the bridge.
00586  * \since 12.0.0
00587  *
00588  * \param bridge_channel Which channel is putting the frame into the bridge
00589  * \param flags Custom callback option flags.
00590  * \param callback Custom callback run on a bridge channel.
00591  * \param payload Data to pass to the callback. (NULL if none).
00592  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
00593  *
00594  * \note The payload MUST NOT have any resources that need to be freed.
00595  *
00596  * \note This is intended to be called by bridge hooks.
00597  *
00598  * \retval 0 on success.
00599  * \retval -1 on error.
00600  */
00601 int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel,
00602    enum ast_bridge_channel_custom_callback_option flags,
00603    ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
00604 
00605 /*!
00606  * \brief Queue a bridge action custom callback frame onto the bridge channel.
00607  * \since 12.0.0
00608  *
00609  * \param bridge_channel Which channel to put the frame onto.
00610  * \param flags Custom callback option flags.
00611  * \param callback Custom callback run on a bridge channel.
00612  * \param payload Data to pass to the callback. (NULL if none).
00613  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
00614  *
00615  * \note The payload MUST NOT have any resources that need to be freed.
00616  *
00617  * \note This is intended to be called by bridge hooks.
00618  *
00619  * \retval 0 on success.
00620  * \retval -1 on error.
00621  */
00622 int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel,
00623    enum ast_bridge_channel_custom_callback_option flags,
00624    ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
00625 
00626 /*!
00627  * \brief Have a bridge channel park a channel in the bridge
00628  * \since 12.0.0
00629  *
00630  * \param bridge_channel Bridge channel performing the parking
00631  * \param parkee_uuid Unique id of the channel we want to park
00632  * \param parker_uuid Unique id of the channel parking the call
00633  * \param app_data string indicating data used for park application (NULL allowed)
00634  *
00635  * \note This is intended to be called by bridge hooks.
00636  *
00637  * \retval 0 on success.
00638  * \retval -1 on error.
00639  */
00640 int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
00641    const char *parker_uuid, const char *app_data);
00642 
00643 /*!
00644  * \brief Kick the channel out of the bridge.
00645  * \since 12.0.0
00646  *
00647  * \param bridge_channel Which channel is being kicked or hungup.
00648  * \param cause Cause of channel being kicked.
00649  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
00650  *
00651  * \note This is intended to be called by bridge hooks and the
00652  * bridge channel thread.
00653  *
00654  * \return Nothing
00655  */
00656 void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause);
00657 
00658 /*!
00659  * \brief Add a DTMF digit to the collected digits.
00660  * \since 13.3.0
00661  *
00662  * \param bridge_channel Channel that received a DTMF digit.
00663  * \param digit DTMF digit to add to collected digits
00664  *
00665  * \note Neither the bridge nor the bridge_channel locks should be held
00666  * when entering this function.
00667  *
00668  * \note This is can only be called from within DTMF bridge hooks.
00669  */
00670 void ast_bridge_channel_feature_digit_add(struct ast_bridge_channel *bridge_channel, int digit);
00671 
00672 /*!
00673  * \brief Add a DTMF digit to the collected digits to match against DTMF features.
00674  * \since 12.8.0
00675  *
00676  * \param bridge_channel Channel that received a DTMF digit.
00677  * \param digit DTMF digit to add to collected digits or 0 for timeout event.
00678  * \param clear_digits clear the digits array prior to calling hooks
00679  *
00680  * \note Neither the bridge nor the bridge_channel locks should be held
00681  * when entering this function.
00682  *
00683  * \note This is intended to be called by bridge hooks and the
00684  * bridge channel thread.
00685  *
00686  * \note This is intended to be called by non-DTMF bridge hooks and the bridge
00687  * channel thread.  Calling from a DTMF bridge hook can potentially cause
00688  * unbounded recursion.
00689  *
00690  * \return Nothing
00691  */
00692 void ast_bridge_channel_feature_digit(struct ast_bridge_channel *bridge_channel, int digit);
00693 
00694 #if defined(__cplusplus) || defined(c_plusplus)
00695 }
00696 #endif
00697 
00698 #endif   /* _ASTERISK_BRIDGING_CHANNEL_H */

Generated on Thu Apr 16 06:27:16 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6