diff options
author | Richard Mudgett <rmudgett@digium.com> | 2015-01-22 19:24:28 +0000 |
---|---|---|
committer | Richard Mudgett <rmudgett@digium.com> | 2015-01-22 19:24:28 +0000 |
commit | 355eb9d22f95c7c435f61922da84feac3b42d5e4 (patch) | |
tree | dbc3730dc7325adac5af68849d76b86a4ef05100 /include | |
parent | c73b4b2a46692be957d0d7ef193f75dc5c98be59 (diff) |
Bridge core: Pass a ref with the swap channel when joining a bridge.
When code imparts a channel into a bridge to swap with another channel, a
ref needs to be held on the swap channel to ensure that it cannot
dissapear before finding it in the bridge.
* The ast_bridge_join() swap channel parameter now always steals a ref for
the swap channel. This is the only change to the bridge framework's
public API semantics.
* bridge_channel_internal_join() now requires the bridge_channel->swap
channel to pass in a ref.
ASTERISK-24649
Reported by: John Bigelow
Review: https://reviewboard.asterisk.org/r/4354/
git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/13@430975 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/bridge.h | 10 | ||||
-rw-r--r-- | include/asterisk/bridge_channel_internal.h | 19 | ||||
-rw-r--r-- | include/asterisk/bridge_internal.h | 3 |
3 files changed, 24 insertions, 8 deletions
diff --git a/include/asterisk/bridge.h b/include/asterisk/bridge.h index ccfb541b9..fecca1dd2 100644 --- a/include/asterisk/bridge.h +++ b/include/asterisk/bridge.h @@ -444,15 +444,19 @@ enum ast_bridge_join_flags { }; /*! - * \brief Join (blocking) a channel to a bridge + * \brief Join a channel to a bridge (blocking) * * \param bridge Bridge to join * \param chan Channel to join - * \param swap Channel to swap out if swapping + * \param swap Channel to swap out if swapping (A channel reference is stolen.) * \param features Bridge features structure * \param tech_args Optional Bridging tech optimization parameters for this channel. * \param flags defined by enum ast_bridge_join_flags. * + * \note The passed in swap channel is always unreffed on return. It is not a + * good idea to access the swap channel on return or for the caller to keep a + * reference to it. + * * \note Absolutely _NO_ locks should be held before calling * this function since it blocks. * @@ -495,7 +499,7 @@ enum ast_bridge_impart_flags { }; /*! - * \brief Impart (non-blocking) a channel onto a bridge + * \brief Impart a channel to a bridge (non-blocking) * * \param bridge Bridge to impart on * \param chan Channel to impart (The channel reference is stolen if impart successful.) diff --git a/include/asterisk/bridge_channel_internal.h b/include/asterisk/bridge_channel_internal.h index b5a3a8de2..71892f51a 100644 --- a/include/asterisk/bridge_channel_internal.h +++ b/include/asterisk/bridge_channel_internal.h @@ -103,6 +103,9 @@ void bridge_channel_settle_owed_events(struct ast_bridge *orig_bridge, struct as * * \param bridge_channel Channel to push. * + * \note A ref is not held by bridge_channel->swap when calling because the + * push with swap happens immediately. + * * \note On entry, bridge_channel->bridge is already locked. * * \retval 0 on success. @@ -128,16 +131,22 @@ void bridge_channel_internal_pull(struct ast_bridge_channel *bridge_channel); /*! * \internal - * \brief Join the bridge_channel to the bridge + * \brief Join the bridge_channel to the bridge (blocking) * * \param bridge_channel The Channel in the bridge * + * \note The bridge_channel->swap holds a channel reference for the swap + * channel going into the bridging system. The ref ensures that the swap + * pointer is valid for the bridge subclass push callbacks. The pointer + * will be NULL on return if the ref was consumed. + * + * \details + * This API call puts the bridge_channel into the bridge and handles the + * bridge_channel's processing of events while it is in the bridge. It + * will return when the channel has been instructed to leave the bridge. + * * \retval 0 bridge channel successfully joined the bridge * \retval -1 bridge channel failed to join the bridge - * - * \note This API call starts the bridge_channel's processing of events while - * it is in the bridge. It will return when the channel has been instructed to - * leave the bridge. */ int bridge_channel_internal_join(struct ast_bridge_channel *bridge_channel); diff --git a/include/asterisk/bridge_internal.h b/include/asterisk/bridge_internal.h index e50e7f987..37c8418c6 100644 --- a/include/asterisk/bridge_internal.h +++ b/include/asterisk/bridge_internal.h @@ -117,6 +117,9 @@ struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabiliti * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge. * \param optimized Indicates whether the move is part of an unreal channel optimization. * + * \note A ref is not held by bridge_channel->swap when calling because the + * move with swap happens immediately. + * * \note The dst_bridge and bridge_channel->bridge are assumed already locked. * * \retval 0 on success. |