asterisk/include/asterisk/bridge_features.h

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2009, Digium, Inc.
 *
 * Joshua Colp <jcolp@digium.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*!
 * \file
 * \brief Channel Bridging API
 * \author Joshua Colp <jcolp@digium.com>
 */

#ifndef _ASTERISK_BRIDGING_FEATURES_H
#define _ASTERISK_BRIDGING_FEATURES_H

#include "asterisk/channel.h"

#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif

/*! \brief Flags used for bridge features */
enum ast_bridge_feature_flags {
	/*! Upon channel hangup all bridge participants should be kicked out. */
	AST_BRIDGE_FLAG_DISSOLVE_HANGUP = (1 << 0),
	/*! The last channel to leave the bridge dissolves it. */
	AST_BRIDGE_FLAG_DISSOLVE_EMPTY = (1 << 1),
	/*! Move between bridging technologies as needed. */
	AST_BRIDGE_FLAG_SMART = (1 << 2),
	/*! Bridge channels cannot be merged from this bridge. */
	AST_BRIDGE_FLAG_MERGE_INHIBIT_FROM = (1 << 3),
	/*! Bridge channels cannot be merged to this bridge. */
	AST_BRIDGE_FLAG_MERGE_INHIBIT_TO = (1 << 4),
	/*! Bridge channels cannot be local channel swap optimized from this bridge. */
	AST_BRIDGE_FLAG_SWAP_INHIBIT_FROM = (1 << 5),
	/*! Bridge channels cannot be local channel swap optimized to this bridge. */
	AST_BRIDGE_FLAG_SWAP_INHIBIT_TO = (1 << 6),
	/*! Bridge channels can be moved to another bridge only by masquerade (ConfBridge) */
	AST_BRIDGE_FLAG_MASQUERADE_ONLY = (1 << 7),
	/*! Bridge does not allow transfers of channels out */
	AST_BRIDGE_FLAG_TRANSFER_PROHIBITED = (1 << 8),
	/*! Bridge transfers require transfer of entire bridge rather than individual channels */
	AST_BRIDGE_FLAG_TRANSFER_BRIDGE_ONLY = (1 << 9),
	/*! Bridge is invisible to AMI/CLI/ARI/etc. */
	AST_BRIDGE_FLAG_INVISIBLE = (1 << 10),
};

/*! \brief Flags used for per bridge channel features */
enum ast_bridge_channel_feature_flags {
	/*! Upon channel hangup all bridge participants should be kicked out. */
	AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP = (1 << 0),
	/*! This channel leaves the bridge if all participants have this flag set. */
	AST_BRIDGE_CHANNEL_FLAG_LONELY = (1 << 1),
	/*! This channel cannot be moved to another bridge. */
	AST_BRIDGE_CHANNEL_FLAG_IMMOVABLE = (1 << 2),
};

/*! \brief Built in DTMF features */
enum ast_bridge_builtin_feature {
	/*! DTMF based Blind Transfer */
	AST_BRIDGE_BUILTIN_BLINDTRANSFER,
	/*! DTMF based Attended Transfer */
	AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
	/*!
	 * DTMF based depart bridge feature
	 *
	 * \note Imparted channels are optionally hangup depending upon
	 * how it was imparted.
	 *
	 * \note Joined channels exit the bridge with
	 * BRIDGE_CHANNEL_STATE_END_WITH_DISSOLVE.
	 */
	AST_BRIDGE_BUILTIN_HANGUP,
	/*!
	 * DTMF based Park
	 *
	 * \details The bridge is parked and the channel hears the
	 * parking slot to which it was parked.
	 */
	AST_BRIDGE_BUILTIN_PARKCALL,
	/*!
	 * DTMF one-touch-record toggle using MixMonitor app.
	 *
	 * \note Only valid on two party bridges.
	 */
	AST_BRIDGE_BUILTIN_AUTOMIXMON,

	/*! End terminator for list of built in features. Must remain last. */
	AST_BRIDGE_BUILTIN_END
};

enum ast_bridge_builtin_interval {
	/*! Apply Call Duration Limits */
	AST_BRIDGE_BUILTIN_INTERVAL_LIMITS,

	/*! End terminator for list of built in interval features. Must remain last. */
	AST_BRIDGE_BUILTIN_INTERVAL_END
};

struct ast_bridge;
struct ast_bridge_channel;

/*!
 * \brief Hook callback type
 *
 * \param bridge_channel Channel executing the feature
 * \param hook_pvt Private data passed in when the hook was created
 *
 * \retval 0        for interval hooks: setup to fire again at the last interval.
 *                  for other hooks: keep the callback hook.
 * \retval positive for interval hooks: Setup to fire again at the new interval returned.
 *                  for other hooks: n/a
 * \retval -1       for all hooks: remove the callback hook.
 */
typedef int (*ast_bridge_hook_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt);

/*!
 * \brief Hook pvt destructor callback
 *
 * \param hook_pvt Private data passed in when the hook was created to destroy
 */
typedef void (*ast_bridge_hook_pvt_destructor)(void *hook_pvt);

/*!
 * \brief Talking indicator callback
 *
 * \details
 * This callback can be registered with the bridge channel in
 * order to receive updates when the bridge_channel has started
 * and stopped talking.
 *
 * \param bridge_channel Channel executing the feature
 * \param hook_pvt Private data passed in when the hook was created
 * \param talking TRUE if the channel is now talking
 *
 * \retval 0 Keep the callback hook.
 * \retval -1 Remove the callback hook.
 */
typedef int (*ast_bridge_talking_indicate_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt, int talking);

/*!
 * \brief Move indicator callback
 *
 * \details
 * This callback can be registered with the bridge channel in order
 * to be notified when the bridge channel is being moved from one
 * bridge to another.
 *
 * \param bridge_channel The channel executing the feature
 * \param hook_pvt Private data passed in when the hook was created
 * \param src The bridge from which the bridge channel is moving
 * \param dst The bridge into which the bridge channel is moving
 *
 * \retval 0 Keep the callback hook.
 * \retval -1 Remove the callback hook.
 */
typedef int (*ast_bridge_move_indicate_callback)(struct ast_bridge_channel *bridge_channel,
		void *hook_pvt, struct ast_bridge *src, struct ast_bridge *dst);

enum ast_bridge_hook_remove_flags {
	/*! The hook is removed when the channel is pulled from the bridge. */
	AST_BRIDGE_HOOK_REMOVE_ON_PULL = (1 << 0),
	/*! The hook is removed when the bridge's personality changes. */
	AST_BRIDGE_HOOK_REMOVE_ON_PERSONALITY_CHANGE = (1 << 1),
};

enum ast_bridge_hook_type {
	/*! The hook type has not been specified. */
	AST_BRIDGE_HOOK_TYPE_NONE,
	AST_BRIDGE_HOOK_TYPE_DTMF,
	AST_BRIDGE_HOOK_TYPE_TIMER,
	AST_BRIDGE_HOOK_TYPE_HANGUP,
	AST_BRIDGE_HOOK_TYPE_JOIN,
	AST_BRIDGE_HOOK_TYPE_LEAVE,
	AST_BRIDGE_HOOK_TYPE_TALK,
	AST_BRIDGE_HOOK_TYPE_MOVE,
};

/*! \brief Structure that is the essence of a feature hook. */
struct ast_bridge_hook {
	/*! Callback that is called when hook is tripped */
	ast_bridge_hook_callback callback;
	/*! Callback to destroy hook_pvt data right before destruction. */
	ast_bridge_hook_pvt_destructor destructor;
	/*! Unique data that was passed into us */
	void *hook_pvt;
	/*! Flags determining when hooks should be removed from a bridge channel */
	struct ast_flags remove_flags;
	/*! What kind of hook this is. */
	enum ast_bridge_hook_type type;
};

/*!
 * \brief Maximum length of a DTMF feature string
 */
#define MAXIMUM_DTMF_FEATURE_STRING (11 + 1)

/*! Extra parameters for a DTMF feature hook. */
struct ast_bridge_hook_dtmf_parms {
	/*! DTMF String that is examined during a feature hook lookup */
	char code[MAXIMUM_DTMF_FEATURE_STRING];
};

/*! DTMF specific hook. */
struct ast_bridge_hook_dtmf {
	/*! Generic feature hook information. */
	struct ast_bridge_hook generic;
	/*! Extra parameters for a DTMF feature hook. */
	struct ast_bridge_hook_dtmf_parms dtmf;
};

enum ast_bridge_hook_timer_option {
	/*! The timer temporarily affects media. (Like a custom playfile.) */
	AST_BRIDGE_HOOK_TIMER_OPTION_MEDIA = (1 << 0),
};

/*! Extra parameters for an interval timer hook. */
struct ast_bridge_hook_timer_parms {
	/*! Time at which the hook should actually trip */
	struct timeval trip_time;
	/*! Heap index for interval hook */
	ssize_t heap_index;
	/*! Interval that the hook should execute at in milliseconds */
	unsigned int interval;
	/*! Sequence number for the hook to ensure expiration ordering */
	unsigned int seqno;
	/*! Option flags determining how callback is called. */
	unsigned int flags;
};

/*! Timer specific hook. */
struct ast_bridge_hook_timer {
	/*! Generic feature hook information. */
	struct ast_bridge_hook generic;
	/*! Extra parameters for an interval timer hook. */
	struct ast_bridge_hook_timer_parms timer;
};

/*!
 * \brief Structure that contains features information
 */
struct ast_bridge_features {
	/*! Attached DTMF feature hooks */
	struct ao2_container *dtmf_hooks;
	/*! Attached miscellaneous other hooks. */
	struct ao2_container *other_hooks;
	/*! Attached interval hooks */
	struct ast_heap *interval_hooks;
	/*! Feature flags that are enabled */
	struct ast_flags feature_flags;
	/*! Used to assign the sequence number to the next interval hook added. */
	unsigned int interval_sequence;
	/*! TRUE if feature_flags is setup */
	unsigned int usable:1;
	/*! TRUE if the channel/bridge is muted. */
	unsigned int mute:1;
	/*! TRUE if DTMF should be passed into the bridge tech.  */
	unsigned int dtmf_passthrough:1;
	/*! TRUE to avoid generating COLP frames when joining the bridge */
	unsigned int inhibit_colp:1;
	/*! TRUE if text messaging is permitted. */
	unsigned int text_messaging:1;
};

/*!
 * \brief Structure that contains configuration information for the blind transfer built in feature
 */
struct ast_bridge_features_blind_transfer {
	/*! Context to use for transfers (If not empty.) */
	char context[AST_MAX_CONTEXT];
};

/*!
 * \brief Structure that contains configuration information for the attended transfer built in feature
 */
struct ast_bridge_features_attended_transfer {
	/*! Context to use for transfers (If not empty.) */
	char context[AST_MAX_CONTEXT];
	/*! DTMF string used to abort the transfer (If not empty.) */
	char abort[MAXIMUM_DTMF_FEATURE_STRING];
	/*! DTMF string used to turn the transfer into a three way conference (If not empty.) */
	char threeway[MAXIMUM_DTMF_FEATURE_STRING];
	/*! DTMF string used to complete the transfer (If not empty.) */
	char complete[MAXIMUM_DTMF_FEATURE_STRING];
	/*! DTMF string used to swap bridged targets (If not empty.) */
	char swap[MAXIMUM_DTMF_FEATURE_STRING];
};

enum ast_bridge_features_monitor {
	/*! Toggle start/stop of MixMonitor. */
	AUTO_MONITOR_TOGGLE,
	/*! Start MixMonitor if not already started. */
	AUTO_MONITOR_START,
	/*! Stop MixMonitor if not already stopped. */
	AUTO_MONITOR_STOP,
};

struct ast_bridge_features_automixmonitor {
	/*! Start/Stop behavior. */
	enum ast_bridge_features_monitor start_stop;
};

/*!
 * \brief Structure that contains configuration information for the limits feature
 */
struct ast_bridge_features_limits {
	AST_DECLARE_STRING_FIELDS(
		/*! Sound file to play when the maximum duration is reached (if empty, then nothing will be played) */
		AST_STRING_FIELD(duration_sound);
		/*! Sound file to play when the warning time is reached (if empty, then the remaining time will be played) */
		AST_STRING_FIELD(warning_sound);
		/*! Sound file to play when the call is first entered (if empty, then the remaining time will be played) */
		AST_STRING_FIELD(connect_sound);
	);
	/*! Time when the bridge will be terminated by the limits feature */
	struct timeval quitting_time;
	/*! Maximum duration that the channel is allowed to be in the bridge (specified in milliseconds) */
	unsigned int duration;
	/*! Duration into the call when warnings should begin (specified in milliseconds or 0 to disable) */
	unsigned int warning;
	/*! Interval between the warnings (specified in milliseconds or 0 to disable) */
	unsigned int frequency;
};

/*!
 * \brief Register a handler for a built in feature
 *
 * \param feature The feature that the handler will be responsible for
 * \param callback The callback function that will handle it
 * \param dtmf Default DTMF string used to activate the feature
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
 * \endcode
 *
 * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
 * attended transfer feature.
 */
int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_hook_callback callback, const char *dtmf);

/*!
 * \brief Unregister a handler for a built in feature
 *
 * \param feature The feature to unregister
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
 * \endcode
 *
 * This unregisters the function that is handling the built in attended transfer feature.
 */
int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);

/*!
 * \brief Invoke a built in feature hook now.
 *
 * \param feature The feature to invoke
 * \param bridge_channel Channel executing the feature
 * \param hook_pvt Private data passed in when the hook was created
 *
 * \note This API call is only meant to be used by bridge
 * subclasses and hook callbacks to request a builtin feature
 * hook to be executed.
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_features_do(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_channel, hook_pvt);
 * \endcode
 */
int ast_bridge_features_do(enum ast_bridge_builtin_feature feature, struct ast_bridge_channel *bridge_channel, void *hook_pvt);

/*!
 * \brief Attach interval hooks to a bridge features structure
 *
 * \param features Bridge features structure
 * \param limits Configured limits applicable to the channel
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure
 */
typedef int (*ast_bridge_builtin_set_limits_fn)(struct ast_bridge_features *features,
		struct ast_bridge_features_limits *limits, enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Register a handler for a built in interval feature
 *
 * \param interval The interval feature that the handler will be responsible for
 * \param callback the Callback function that will handle it
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_interval_register(AST_BRIDGE_BUILTIN_INTERVAL_LIMITS, bridge_builtin_set_limits);
 * \endcode
 *
 * This registers the function bridge_builtin_set_limits as the function responsible for the built in
 * duration limit feature.
 */
int ast_bridge_interval_register(enum ast_bridge_builtin_interval interval, ast_bridge_builtin_set_limits_fn callback);

/*!
 * \brief Unregisters a handler for a built in interval feature
 *
 * \param interval the interval feature to unregister
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_interval_unregister(AST_BRIDGE_BULTIN_INTERVAL_LIMITS)
 * \endcode
 *
 * This unregisters the function that is handling the built in duration limit feature.
 */
int ast_bridge_interval_unregister(enum ast_bridge_builtin_interval interval);

/*!
 * \brief Attach a bridge channel join hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_join_hook(&features, join_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging core call join_callback when a
 * channel successfully joins the bridging system.  A pointer to
 * useful data may be provided to the hook_pvt parameter.
 */
int ast_bridge_join_hook(struct ast_bridge_features *features,
	ast_bridge_hook_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Attach a bridge channel leave hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_leave_hook(&features, leave_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging core call leave_callback when a
 * channel successfully leaves the bridging system.  A pointer
 * to useful data may be provided to the hook_pvt parameter.
 */
int ast_bridge_leave_hook(struct ast_bridge_features *features,
	ast_bridge_hook_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Attach a hangup hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_hangup_hook(&features, hangup_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging core call hangup_callback if a
 * channel that has this hook hangs up.  A pointer to useful
 * data may be provided to the hook_pvt parameter.
 */
int ast_bridge_hangup_hook(struct ast_bridge_features *features,
	ast_bridge_hook_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Attach a DTMF hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param dtmf DTMF string to be activated upon
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_dtmf_hook(&features, "#", pound_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging core call pound_callback if a channel that has this
 * feature structure inputs the DTMF string '#'. A pointer to useful data may be
 * provided to the hook_pvt parameter.
 */
int ast_bridge_dtmf_hook(struct ast_bridge_features *features,
	const char *dtmf,
	ast_bridge_hook_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Attach an interval hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param flags Interval timer callback option flags.
 * \param interval The interval that the hook should execute at in milliseconds
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_interval_hook(&features, 1000, playback_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging core call playback_callback every second. A pointer to useful
 * data may be provided to the hook_pvt parameter.
 */
int ast_bridge_interval_hook(struct ast_bridge_features *features,
	enum ast_bridge_hook_timer_option flags,
	unsigned int interval,
	ast_bridge_hook_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Attach a bridge channel talk detection hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_talk_hook(&features, talk_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging technology call talk_callback when a
 * channel is recognized as starting and stopping talking.  A
 * pointer to useful data may be provided to the hook_pvt
 * parameter.
 *
 * \note This hook is currently only supported by softmix.
 */
int ast_bridge_talk_detector_hook(struct ast_bridge_features *features,
	ast_bridge_talking_indicate_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Attach a bridge channel move detection hook to a bridge features structure
 *
 * \param features Bridge features structure
 * \param callback Function to execute upon activation
 * \param hook_pvt Unique data
 * \param destructor Optional destructor callback for hook_pvt data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_move_hook(&features, move_callback, NULL, NULL, 0);
 * \endcode
 *
 * This makes the bridging core call \p callback when a
 * channel is moved from one bridge to another.  A
 * pointer to useful data may be provided to the hook_pvt
 * parameter.
 */
int ast_bridge_move_hook(struct ast_bridge_features *features,
	ast_bridge_move_indicate_callback callback,
	void *hook_pvt,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Enable a built in feature on a bridge features structure
 *
 * \param features Bridge features structure
 * \param feature Feature to enable
 * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
 * \param config Configuration structure unique to the built in type
 * \param destructor Optional destructor callback for config data
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL, NULL, 0);
 * \endcode
 *
 * This enables the attended transfer DTMF option using the default DTMF string. An alternate
 * string may be provided using the dtmf parameter. Internally this is simply setting up a hook
 * to a built in feature callback function.
 */
int ast_bridge_features_enable(struct ast_bridge_features *features,
	enum ast_bridge_builtin_feature feature,
	const char *dtmf,
	void *config,
	ast_bridge_hook_pvt_destructor destructor,
	enum ast_bridge_hook_remove_flags remove_flags);

/*!
 * \brief Constructor function for ast_bridge_features_limits
 *
 * \param limits pointer to a ast_bridge_features_limits struct that has been allocated, but not initialized
 *
 * \retval 0 on success
 * \retval -1 on failure
 */
int ast_bridge_features_limits_construct(struct ast_bridge_features_limits *limits);

/*!
 * \brief Destructor function for ast_bridge_features_limits
 *
 * \param limits pointer to an ast_bridge_features_limits struct that needs to be destroyed
 *
 * This function does not free memory allocated to the ast_bridge_features_limits struct, it only frees elements within the struct.
 * You must still call ast_free on the struct if you allocated it with malloc.
 */
void ast_bridge_features_limits_destroy(struct ast_bridge_features_limits *limits);

/*!
 * \brief Limit the amount of time a channel may stay in the bridge and optionally play warning messages as time runs out
 *
 * \param features Bridge features structure
 * \param limits Configured limits applicable to the channel
 * \param remove_flags Dictates what situations the hook should be removed.
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * struct ast_bridge_features_limits limits;
 * ast_bridge_features_init(&features);
 * ast_bridge_features_limits_construct(&limits);
 * ast_bridge_features_set_limits(&features, &limits, 0);
 * ast_bridge_features_limits_destroy(&limits);
 * \endcode
 *
 * This sets the maximum time the channel can be in the bridge to 10 seconds and does not play any warnings.
 *
 * \note This API call can only be used on a features structure that will be used in association with a bridge channel.
 * \note The ast_bridge_features_limits structure must remain accessible for the lifetime of the features structure.
 */
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);

/*!
 * \brief Set a flag on a bridge channel features structure
 *
 * \param features Bridge channel features structure
 * \param flag Flag to enable
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_features_set_flag(&features, AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP);
 * \endcode
 *
 * This sets the AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP feature
 * to be enabled on the features structure 'features'.
 */
void ast_bridge_features_set_flag(struct ast_bridge_features *features, unsigned int flag);

/*!
 * \brief Merge one ast_bridge_features into another
 *
 * \param into The ast_bridge_features that will be merged into
 * \param from The ast_bridge_features that will be merged from
 */
void ast_bridge_features_merge(struct ast_bridge_features *into, const struct ast_bridge_features *from);

/*!
 * \brief Initialize bridge features structure
 *
 * \param features Bridge featues structure
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * \endcode
 *
 * This initializes the feature structure 'features' to have nothing enabled.
 *
 * \note This MUST be called before enabling features or flags. Failure to do so
 *       may result in a crash.
 */
int ast_bridge_features_init(struct ast_bridge_features *features);

/*!
 * \brief Clean up the contents of a bridge features structure
 *
 * \param features Bridge features structure
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features features;
 * ast_bridge_features_init(&features);
 * ast_bridge_features_cleanup(&features);
 * \endcode
 *
 * This cleans up the feature structure 'features'.
 *
 * \note This MUST be called after the features structure is done being used
 *       or a memory leak may occur.
 */
void ast_bridge_features_cleanup(struct ast_bridge_features *features);

/*!
 * \brief Allocate a new bridge features struct.
 * \since 12.0.0
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features *features;
 * features = ast_bridge_features_new();
 * ast_bridge_features_destroy(features);
 * \endcode
 *
 * \return features New allocated features struct.
 * \retval NULL on error.
 */
struct ast_bridge_features *ast_bridge_features_new(void);

/*!
 * \brief Destroy an allocated bridge features struct.
 * \since 12.0.0
 *
 * \param features Bridge features structure
 *
 * Example usage:
 *
 * \code
 * struct ast_bridge_features *features;
 * features = ast_bridge_features_new();
 * ast_bridge_features_destroy(features);
 * \endcode
 */
void ast_bridge_features_destroy(struct ast_bridge_features *features);

#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

#endif /* _ASTERISK_BRIDGING_FEATURES_H */