[svn-commits] mmichelson: branch mmichelson/atxfer_features r393479 - /team/mmichelson/atxf...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Tue Jul 2 14:24:53 CDT 2013
Author: mmichelson
Date: Tue Jul 2 14:24:51 2013
New Revision: 393479
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=393479
Log:
Add some more doxygen.
Modified:
team/mmichelson/atxfer_features/main/bridging_basic.c
Modified: team/mmichelson/atxfer_features/main/bridging_basic.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/atxfer_features/main/bridging_basic.c?view=diff&rev=393479&r1=393478&r2=393479
==============================================================================
--- team/mmichelson/atxfer_features/main/bridging_basic.c (original)
+++ team/mmichelson/atxfer_features/main/bridging_basic.c Tue Jul 2 14:24:51 2013
@@ -122,9 +122,15 @@
return 0;
}
+/*!
+ * \brief The basis for basic bridge personalities
+ */
struct bridge_basic_personality {
+ /*! The name of this personality */
const char *name;
+ /*! The v_table to use for this personality */
struct ast_bridge_methods *v_table;
+ /*! User data for this personality */
void *pvt;
};
@@ -191,6 +197,14 @@
ast_bridge_base_v_table.destroy(self);
}
+/*!
+ * \brief Remove appropriate hooks when basic bridge personality changes
+ *
+ * Hooks that have the AST_BRIDGE_HOOK_REMOVE_ON_PERSONALITY_CHANGE flag
+ * set will be removed from all bridge channels in the bridge.
+ *
+ * \param bridge Basic bridge undergoing personality change
+ */
static void remove_hooks_on_personality_change(struct ast_bridge *bridge)
{
struct ast_bridge_channel *iter;
@@ -964,6 +978,16 @@
ast_mutex_destroy(&props->lock);
}
+/*!
+ * \brief Allocate and initialize attended transfer properties
+ *
+ * \param transferee_bridge The bridge where the transfer was initiated
+ * \param transferer The channel performing the attended transfer
+ * \param context Suggestion for what context the transfer target extension can be found in
+ *
+ * \retval NULL Failure to allocate or initialize
+ * \retval non-NULL Newly allocated properties
+ */
static struct attended_transfer_properties *attended_transfer_properties_alloc(
struct ast_bridge *transferee_bridge, struct ast_channel *transferer,
const char *context)
@@ -1023,6 +1047,9 @@
return props;
}
+/*!
+ * \brief Free backlog of stimuli in the queue
+ */
static void clear_stimulus_queue(struct attended_transfer_properties *props)
{
struct stimulus_list *list;
@@ -1033,6 +1060,12 @@
}
}
+/*!
+ * \brief Initiate shutdown of attended transfer properties
+ *
+ * Calling this indicates that the attended transfer properties are no longer needed
+ * because the transfer operation has concluded.
+ */
static void attended_transfer_properties_shutdown(struct attended_transfer_properties *props)
{
if (props->transferee_bridge) {
@@ -1062,6 +1095,9 @@
ao2_cleanup(props);
}
+/*!
+ * \brief Send a stasis publication for a successful attended transfer
+ */
static void publish_transfer_success(struct attended_transfer_properties *props)
{
struct ast_bridge_channel_pair transferee = {
@@ -1077,6 +1113,9 @@
&transferee, &transfer_target, props->transferee_bridge);
}
+/*!
+ * \brief Send a stasis publication for an attended transfer that ends in a threeway call
+ */
static void publish_transfer_threeway(struct attended_transfer_properties *props)
{
struct ast_bridge_channel_pair transferee = {
@@ -1096,6 +1135,9 @@
&transferee, &transfer_target, &threeway);
}
+/*!
+ * \brief Send a stasis publication for a failed attended transfer
+ */
static void publish_transfer_fail(struct attended_transfer_properties *props)
{
struct ast_bridge_channel_pair transferee = {
@@ -1111,6 +1153,12 @@
&transferee, &transfer_target);
}
+/*!
+ * \brief Helper method to play a sound on a channel in a bridge
+ *
+ * \param chan The channel to play the sound to
+ * \param sound The sound to play
+ */
static void play_sound(struct ast_channel *chan, const char *sound)
{
RAII_VAR(struct ast_bridge_channel *, bridge_channel, NULL, ao2_cleanup);
@@ -1126,6 +1174,9 @@
ast_bridge_channel_queue_playfile(bridge_channel, NULL, sound, NULL);
}
+/*!
+ * \brief Helper method to place a channel in a bridge on hold
+ */
static void hold(struct ast_channel *chan)
{
RAII_VAR(struct ast_bridge_channel *, bridge_channel, NULL, ao2_cleanup);
@@ -1141,6 +1192,9 @@
}
}
+/*!
+ * \brief Helper method to take a channel in a bridge off hold
+ */
static void unhold(struct ast_channel *chan)
{
RAII_VAR(struct ast_bridge_channel *, bridge_channel, NULL, ao2_cleanup);
@@ -1154,6 +1208,9 @@
ast_bridge_channel_write_unhold(bridge_channel);
}
+/*!
+ * \brief Helper method to send a ringing indication to a channel in a bridge
+ */
static void ringing(struct ast_channel *chan)
{
RAII_VAR(struct ast_bridge_channel *, bridge_channel, NULL, ao2_cleanup);
@@ -1167,6 +1224,9 @@
ast_bridge_channel_write_control_data(bridge_channel, AST_CONTROL_RINGING, NULL, 0);
}
+/*!
+ * \brief Helper method to send a ringing indication to all channels in a bridge
+ */
static void bridge_ringing(struct ast_bridge *bridge)
{
struct ast_frame ringing = {
@@ -1177,6 +1237,9 @@
ast_bridge_queue_everyone_else(bridge, NULL, &ringing);
}
+/*!
+ * \brief Helper method to send a hold frame to all channels in a bridge
+ */
static void bridge_hold(struct ast_bridge *bridge)
{
struct ast_frame hold = {
@@ -1187,6 +1250,9 @@
ast_bridge_queue_everyone_else(bridge, NULL, &hold);
}
+/*!
+ * \brief Helper method to send an unhold frame to all channels in a bridge
+ */
static void bridge_unhold(struct ast_bridge *bridge)
{
struct ast_frame unhold = {
@@ -1197,6 +1263,9 @@
ast_bridge_queue_everyone_else(bridge, NULL, &unhold);
}
+/*!
+ * \brief Wrapper for \ref bridge_move_do
+ */
static int bridge_move(struct ast_bridge *dest, struct ast_bridge *src, struct ast_channel *channel, struct ast_channel *swap)
{
int res;
@@ -1217,6 +1286,9 @@
return res;
}
+/*!
+ * \brief Wrapper for \ref bridge_merge_do
+ */
static void bridge_merge(struct ast_bridge *dest, struct ast_bridge *src, struct ast_channel **kick_channels, unsigned int num_channels)
{
struct ast_bridge_channel **kick_bridge_channels = num_channels ?
@@ -1319,7 +1391,8 @@
const char *state_name;
/*! Function used to enter a state */
int (*enter)(struct attended_transfer_properties *props);
- /*! Function used to exit a state
+ /*!
+ * Function used to exit a state
* This is used both to determine what the next state
* to transition to will be and to perform any cleanup
* necessary before exiting the current state.
@@ -1413,12 +1486,6 @@
},
};
-/*!
- * \brief enter callback for TRANSFER_CALLING_TARGET state
- *
- * This is the opening state when performing an attended transfer. The goal
- * of this callback is simply to place the transferer into the target bridge.
- */
static int calling_target_enter(struct attended_transfer_properties *props)
{
return bridge_move(props->target_bridge, props->transferee_bridge, props->transferer, NULL);
@@ -2282,7 +2349,17 @@
ast_channel_set_bridge_role_option(chan, TRANSFERER_ROLE_NAME, "swap", atxfer_swap);
}
-/*! \brief Internal built in feature for attended transfers */
+/*!
+ * \brief Internal built in feature for attended transfers
+ *
+ * This hook will set up a thread for monitoring the progress of
+ * an attended transfer. For more information about attended transfer
+ * progress, see documentation on the transfer state machine.
+ *
+ * \param bridge Bridge where attended transfer DTMF sequence was entered
+ * \param bridge_channel The channel that pressed the attended transfer DTMF sequence
+ * \param hook_pvt Structure with further information about the attended transfer
+ */
static int feature_attended_transfer(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt)
{
struct ast_bridge_features_attended_transfer *attended_transfer = hook_pvt;
@@ -2405,6 +2482,11 @@
ao2_cleanup(atxfer->pvt);
}
+/*!
+ * \brief Allocate a normal personlity for a basic bridge
+ *
+ * The normal personality is the default personality for basic bridges.
+ */
static struct bridge_basic_personality *normal_personality_alloc(void)
{
struct bridge_basic_personality *normal;
@@ -2419,6 +2501,16 @@
return normal;
}
+/*!
+ * \brief Allocate an atxfer personality for a basic bridge
+ *
+ * The atxfer personality is used when an attended transfer is being performed. The
+ * bridge where the transfer was initiated and the bridge where the transfer target is
+ * contacted have this personality.
+ *
+ * The personality stores the properties of the attended transfer locally so that they
+ * can be referenced from the v_table methods.
+ */
static struct bridge_basic_personality *atxfer_personality_alloc(struct attended_transfer_properties *props)
{
struct bridge_basic_personality *atxfer;
@@ -2435,6 +2527,14 @@
return atxfer;
}
+/*!
+ * \brief Change a basic bridge's personality to normal
+ *
+ * Changing to normal means that a transfer operation has completed and the
+ * bridge can change back to its normal self. This operation will clean up
+ * the previous personality the bridge had and add back any hooks or features
+ * that should be present on the bridge channels.
+ */
void ast_bridge_basic_change_personality_normal(struct ast_bridge *bridge)
{
struct ast_bridge_channel *bridge_channel;
@@ -2455,6 +2555,14 @@
};
}
+/*!
+ * \brief Change a basic bridge's personality to atxfer
+ *
+ * Changing to atxfer means that a transfer is in progress on the bridge.
+ * When changing to the atxfer bridge, the properties of the attended transfer
+ * are needed so that v_table methods for the atxfer personality can access
+ * the data they need.
+ */
void ast_bridge_basic_change_personality_atxfer(struct ast_bridge *bridge,
struct attended_transfer_properties *props)
{
More information about the svn-commits
mailing list