Wed Jan 27 20:02:04 2016

Asterisk developer's documentation


bridging_features.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2009, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Channel Bridging API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_BRIDGING_FEATURES_H
00025 #define _ASTERISK_BRIDGING_FEATURES_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 /*! \brief Flags used for bridge features */
00032 enum ast_bridge_feature_flags {
00033    /*! Upon hangup the bridge should be discontinued */
00034    AST_BRIDGE_FLAG_DISSOLVE = (1 << 0),
00035    /*! Move between bridging technologies as needed. */
00036    AST_BRIDGE_FLAG_SMART = (1 << 1),
00037 };
00038 
00039 /*! \brief Built in features */
00040 enum ast_bridge_builtin_feature {
00041    /*! DTMF Based Blind Transfer */
00042    AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0,
00043    /*! DTMF Based Attended Transfer */
00044    AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
00045    /*! DTMF Based Hangup Feature */
00046    AST_BRIDGE_BUILTIN_HANGUP,
00047    /*! End terminator for list of built in features. Must remain last. */
00048    AST_BRIDGE_BUILTIN_END,
00049 };
00050 
00051 struct ast_bridge;
00052 struct ast_bridge_channel;
00053 
00054 /*!
00055  * \brief Features hook callback type
00056  *
00057  * \param bridge The bridge that the channel is part of
00058  * \param bridge_channel Channel executing the feature
00059  * \param hook_pvt Private data passed in when the hook was created
00060  *
00061  * \retval 0 success
00062  * \retval -1 failure
00063  */
00064 typedef int (*ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt);
00065 
00066 /*!
00067  * \brief Maximum length of a DTMF feature string
00068  */
00069 #define MAXIMUM_DTMF_FEATURE_STRING 8
00070 
00071 /*!
00072  * \brief Structure that is the essence of a features hook
00073  */
00074 struct ast_bridge_features_hook {
00075    /*! DTMF String that is examined during a feature hook lookup */
00076    char dtmf[MAXIMUM_DTMF_FEATURE_STRING];
00077    /*! Callback that is called when DTMF string is matched */
00078    ast_bridge_features_hook_callback callback;
00079    /*! Unique data that was passed into us */
00080    void *hook_pvt;
00081    /*! Linked list information */
00082    AST_LIST_ENTRY(ast_bridge_features_hook) entry;
00083 };
00084 
00085 /*!
00086  * \brief Structure that contains features information
00087  */
00088 struct ast_bridge_features {
00089    /*! Attached DTMF based feature hooks */
00090    AST_LIST_HEAD_NOLOCK(, ast_bridge_features_hook) hooks;
00091    /*! Feature flags that are enabled */
00092    struct ast_flags feature_flags;
00093    /*! Bit to indicate that this structure is useful and should be considered when looking for features */
00094    unsigned int usable:1;
00095    /*! Bit to indicate whether the channel/bridge is muted or not */
00096    unsigned int mute:1;
00097 };
00098 
00099 /*!
00100  * \brief Structure that contains configuration information for the blind transfer built in feature
00101  */
00102 struct ast_bridge_features_blind_transfer {
00103    /*! Context to use for transfers */
00104    char context[AST_MAX_CONTEXT];
00105 };
00106 
00107 /*!
00108  * \brief Structure that contains configuration information for the attended transfer built in feature
00109  */
00110 struct ast_bridge_features_attended_transfer {
00111    /*! DTMF string used to abort the transfer */
00112    char abort[MAXIMUM_DTMF_FEATURE_STRING];
00113    /*! DTMF string used to turn the transfer into a three way conference */
00114    char threeway[MAXIMUM_DTMF_FEATURE_STRING];
00115    /*! DTMF string used to complete the transfer */
00116    char complete[MAXIMUM_DTMF_FEATURE_STRING];
00117    /*! Context to use for transfers */
00118    char context[AST_MAX_CONTEXT];
00119 };
00120 
00121 /*! \brief Register a handler for a built in feature
00122  *
00123  * \param feature The feature that the handler will be responsible for
00124  * \param callback The callback function that will handle it
00125  * \param dtmf Default DTMF string used to activate the feature
00126  *
00127  * \retval 0 on success
00128  * \retval -1 on failure
00129  *
00130  * Example usage:
00131  *
00132  * \code
00133  * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
00134  * \endcode
00135  *
00136  * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
00137  * attended transfer feature.
00138  */
00139 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf);
00140 
00141 /*! \brief Unregister a handler for a built in feature
00142  *
00143  * \param feature The feature to unregister
00144  *
00145  * \retval 0 on success
00146  * \retval -1 on failure
00147  *
00148  * Example usage:
00149  *
00150  * \code
00151  * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
00152  * \endcode
00153  *
00154  * This unregisters the function that is handling the built in attended transfer feature.
00155  */
00156 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
00157 
00158 /*! \brief Attach a custom hook to a bridge features structure
00159  *
00160  * \param features Bridge features structure
00161  * \param dtmf DTMF string to be activated upon
00162  * \param callback Function to execute upon activation
00163  * \param hook_pvt Unique data
00164  *
00165  * \retval 0 on success
00166  * \retval -1 on failure
00167  *
00168  * Example usage:
00169  *
00170  * \code
00171  * struct ast_bridge_features features;
00172  * ast_bridge_features_init(&features);
00173  * ast_bridge_features_hook(&features, "#", pound_callback, NULL);
00174  * \endcode
00175  *
00176  * This makes the bridging core call pound_callback if a channel that has this
00177  * feature structure inputs the DTMF string '#'. A pointer to useful data may be
00178  * provided to the hook_pvt parameter.
00179  *
00180  * \note It is important that the callback set the bridge channel state back to
00181  *       AST_BRIDGE_CHANNEL_STATE_WAIT or the bridge thread will not service the channel.
00182  */
00183 int ast_bridge_features_hook(struct ast_bridge_features *features, const char *dtmf, ast_bridge_features_hook_callback callback, void *hook_pvt);
00184 
00185 /*! \brief Enable a built in feature on a bridge features structure
00186  *
00187  * \param features Bridge features structure
00188  * \param feature Feature to enable
00189  * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
00190  * \param config Configuration structure unique to the built in type
00191  *
00192  * \retval 0 on success
00193  * \retval -1 on failure
00194  *
00195  * Example usage:
00196  *
00197  * \code
00198  * struct ast_bridge_features features;
00199  * ast_bridge_features_init(&features);
00200  * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL);
00201  * \endcode
00202  *
00203  * This enables the attended transfer DTMF option using the default DTMF string. An alternate
00204  * string may be provided using the dtmf parameter. Internally this is simply setting up a hook
00205  * to a built in feature callback function.
00206  */
00207 int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config);
00208 
00209 /*! \brief Set a flag on a bridge features structure
00210  *
00211  * \param features Bridge features structure
00212  * \param flag Flag to enable
00213  *
00214  * \retval 0 on success
00215  * \retval -1 on failure
00216  *
00217  * Example usage:
00218  *
00219  * \code
00220  * struct ast_bridge_features features;
00221  * ast_bridge_features_init(&features);
00222  * ast_bridge_features_set_flag(&features, AST_BRIDGE_FLAG_DISSOLVE);
00223  * \endcode
00224  *
00225  * This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure
00226  * 'features'.
00227  */
00228 int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag);
00229 
00230 /*! \brief Initialize bridge features structure
00231  *
00232  * \param features Bridge featues structure
00233  *
00234  * \retval 0 on success
00235  * \retval -1 on failure
00236  *
00237  * Example usage:
00238  *
00239  * \code
00240  * struct ast_bridge_features features;
00241  * ast_bridge_features_init(&features);
00242  * \endcode
00243  *
00244  * This initializes the feature structure 'features' to have nothing enabled.
00245  *
00246  * \note This MUST be called before enabling features or flags. Failure to do so
00247  *       may result in a crash.
00248  */
00249 int ast_bridge_features_init(struct ast_bridge_features *features);
00250 
00251 /*! \brief Clean up the contents of a bridge features structure
00252  *
00253  * \param features Bridge features structure
00254  *
00255  * \retval 0 on success
00256  * \retval -1 on failure
00257  *
00258  * Example usage:
00259  *
00260  * \code
00261  * struct ast_bridge_features features;
00262  * ast_bridge_features_init(&features);
00263  * ast_bridge_features_cleanup(&features);
00264  * \endcode
00265  *
00266  * This cleans up the feature structure 'features'.
00267  *
00268  * \note This MUST be called after the features structure is done being used
00269  *       or a memory leak may occur.
00270  */
00271 int ast_bridge_features_cleanup(struct ast_bridge_features *features);
00272 
00273 /*! \brief Play a DTMF stream into a bridge, optionally not to a given channel
00274  *
00275  * \param bridge Bridge to play stream into
00276  * \param dtmf DTMF to play
00277  * \param chan Channel to optionally not play to
00278  *
00279  * \retval 0 on success
00280  * \retval -1 on failure
00281  *
00282  * Example usage:
00283  *
00284  * \code
00285  * ast_bridge_dtmf_stream(bridge, "0123456789", NULL);
00286  * \endcode
00287  *
00288  * This sends the DTMF digits '0123456789' to all channels in the bridge pointed to
00289  * by the bridge pointer. Optionally a channel may be excluded by passing it's channel pointer
00290  * using the chan parameter.
00291  */
00292 int ast_bridge_dtmf_stream(struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan);
00293 
00294 #if defined(__cplusplus) || defined(c_plusplus)
00295 }
00296 #endif
00297 
00298 #endif /* _ASTERISK_BRIDGING_FEATURES_H */

Generated on 27 Jan 2016 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1