core_unreal.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  * Richard Mudgett <rmudgett@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 /*!
00020  * \file
00021  * \brief Unreal channel derivative framework.
00022  *
00023  * \author Richard Mudgett <rmudgett@digium.com>
00024  *
00025  * See Also:
00026  * \arg \ref AstCREDITS
00027  */
00028 
00029 #ifndef _ASTERISK_CORE_UNREAL_H
00030 #define _ASTERISK_CORE_UNREAL_H
00031 
00032 #include "asterisk/astobj2.h"
00033 #include "asterisk/channel.h"
00034 #include "asterisk/bridge.h"
00035 #include "asterisk/abstract_jb.h"
00036 
00037 #if defined(__cplusplus) || defined(c_plusplus)
00038 extern "C" {
00039 #endif
00040 
00041 /* Forward declare some struct names */
00042 struct ast_format_cap;
00043 
00044 /* ------------------------------------------------------------------- */
00045 
00046 struct ast_unreal_pvt;
00047 
00048 enum ast_unreal_channel_indicator {
00049    AST_UNREAL_OWNER,
00050    AST_UNREAL_CHAN,
00051 };
00052 
00053 /*!
00054  * \brief Callbacks that can be provided by concrete implementations of the unreal
00055  * channel driver that will be called when events occur in the unreal layer
00056  */
00057 struct ast_unreal_pvt_callbacks {
00058    /*!
00059     * \brief Called when an optimization attempt has started
00060     * \note p is locked when this callback is called
00061     * \param p The \ref ast_unreal_pvt object
00062     * \param source The channel that is optimizing into an unreal_pvt channel's bridge.
00063     * If NULL, the optimization is being accomplished via a bridge merge.
00064     * \param dest Indicator of which channel's bridge in the unreal_pvt will survive the
00065     * optimization
00066     * \param id Unique identifier for this optimization operation.
00067     */
00068    void (* const optimization_started)(struct ast_unreal_pvt *p, struct ast_channel *source,
00069          enum ast_unreal_channel_indicator dest, unsigned int id);
00070 
00071    /*!
00072     * \brief Called when an optimization attempt completed successfully
00073     * \note p is locked when this callback is called
00074     * \param p The \ref ast_unreal_pvt object
00075     * \param success Non-zero if the optimization succeeded, zero if the optimization
00076     * met with fatal and permanent error
00077     * \param id Unique identifier for this optimization. Same as the one from the optimization_started
00078     * call
00079     */
00080    void (* const optimization_finished)(struct ast_unreal_pvt *p, int success, unsigned int id);
00081 };
00082 
00083 /*!
00084  * \brief The base pvt structure for local channel derivatives.
00085  *
00086  * The unreal pvt has two ast_chan objects - the "owner" and the "next channel", the outbound channel
00087  *
00088  * ast_chan owner -> ast_unreal_pvt -> ast_chan chan
00089  */
00090 struct ast_unreal_pvt {
00091    struct ast_unreal_pvt_callbacks *callbacks; /*!< Event callbacks */
00092    struct ast_channel *owner;                  /*!< Master Channel - ;1 side */
00093    struct ast_channel *chan;                   /*!< Outbound channel - ;2 side */
00094    struct ast_format_cap *reqcap;              /*!< Requested format capabilities */
00095    struct ast_jb_conf jb_conf;                 /*!< jitterbuffer configuration */
00096    unsigned int flags;                         /*!< Private option flags */
00097    /*! Base name of the unreal channels.  exten@context or other name. */
00098    char name[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
00099 };
00100 
00101 #define AST_UNREAL_IS_OUTBOUND(a, b) ((a) == (b)->chan ? 1 : 0)
00102 
00103 #define AST_UNREAL_CARETAKER_THREAD (1 << 0) /*!< The ;2 side launched a PBX, was pushed into a bridge, or was masqueraded into an application. */
00104 #define AST_UNREAL_NO_OPTIMIZATION  (1 << 1) /*!< Do not optimize out the unreal channels */
00105 #define AST_UNREAL_MOH_INTERCEPT    (1 << 2) /*!< Intercept and act on hold/unhold control frames */
00106 #define AST_UNREAL_OPTIMIZE_BEGUN   (1 << 3) /*!< Indicates that an optimization attempt has been started */
00107 
00108 /*!
00109  * \brief Send an unreal pvt in with no locks held and get all locks
00110  *
00111  * \note NO locks should be held prior to calling this function
00112  * \note The pvt must have a ref held before calling this function
00113  * \note if outchan or outowner is set != NULL after calling this function
00114  *       those channels are locked and reffed.
00115  * \note Batman.
00116  */
00117 void ast_unreal_lock_all(struct ast_unreal_pvt *p, struct ast_channel **outchan, struct ast_channel **outowner);
00118 
00119 /*!
00120  * \brief Hangup one end (maybe both ends) of an unreal channel derivative.
00121  * \since 12.0.0
00122  *
00123  * \param p Private channel struct (reffed)
00124  * \param ast Channel being hung up.  (locked)
00125  *
00126  * \note Common hangup code for unreal channels.  Derived
00127  * channels will need to deal with any additional resources.
00128  *
00129  * \retval 0 on success.
00130  * \retval -1 on error.
00131  */
00132 int ast_unreal_hangup(struct ast_unreal_pvt *p, struct ast_channel *ast);
00133 
00134 /*! Unreal channel framework struct ast_channel_tech.send_digit_begin callback */
00135 int ast_unreal_digit_begin(struct ast_channel *ast, char digit);
00136 
00137 /*! Unreal channel framework struct ast_channel_tech.send_digit_end callback */
00138 int ast_unreal_digit_end(struct ast_channel *ast, char digit, unsigned int duration);
00139 
00140 /*! Unreal channel framework struct ast_channel_tech.answer callback */
00141 int ast_unreal_answer(struct ast_channel *ast);
00142 
00143 /*! Unreal channel framework struct ast_channel_tech.read and struct ast_channel_tech.exception callback */
00144 struct ast_frame *ast_unreal_read(struct ast_channel *ast);
00145 
00146 /*! Unreal channel framework struct ast_channel_tech.write callback */
00147 int ast_unreal_write(struct ast_channel *ast, struct ast_frame *f);
00148 
00149 /*! Unreal channel framework struct ast_channel_tech.indicate callback */
00150 int ast_unreal_indicate(struct ast_channel *ast, int condition, const void *data, size_t datalen);
00151 
00152 /*! Unreal channel framework struct ast_channel_tech.fixup callback */
00153 int ast_unreal_fixup(struct ast_channel *oldchan, struct ast_channel *newchan);
00154 
00155 /*! Unreal channel framework struct ast_channel_tech.send_html callback */
00156 int ast_unreal_sendhtml(struct ast_channel *ast, int subclass, const char *data, int datalen);
00157 
00158 /*! Unreal channel framework struct ast_channel_tech.send_text callback */
00159 int ast_unreal_sendtext(struct ast_channel *ast, const char *text);
00160 
00161 /*! Unreal channel framework struct ast_channel_tech.queryoption callback */
00162 int ast_unreal_queryoption(struct ast_channel *ast, int option, void *data, int *datalen);
00163 
00164 /*! Unreal channel framework struct ast_channel_tech.setoption callback */
00165 int ast_unreal_setoption(struct ast_channel *chan, int option, void *data, int datalen);
00166 
00167 /*!
00168  * \brief struct ast_unreal_pvt destructor.
00169  * \since 12.0.0
00170  *
00171  * \param vdoomed Object to destroy.
00172  *
00173  * \return Nothing
00174  */
00175 void ast_unreal_destructor(void *vdoomed);
00176 
00177 /*!
00178  * \brief Allocate the base unreal struct for a derivative.
00179  * \since 12.0.0
00180  *
00181  * \param size Size of the unreal struct to allocate.
00182  * \param destructor Destructor callback.
00183  * \param cap Format capabilities to give the unreal private struct.
00184  *
00185  * \retval pvt on success.
00186  * \retval NULL on error.
00187  */
00188 struct ast_unreal_pvt *ast_unreal_alloc(size_t size, ao2_destructor_fn destructor, struct ast_format_cap *cap);
00189 
00190 /*!
00191  * \brief Create the semi1 and semi2 unreal channels.
00192  * \since 12.0.0
00193  *
00194  * \param p Unreal channel private struct.
00195  * \param tech Channel technology to use.
00196  * \param semi1_state State to start the semi1(owner) channel in.
00197  * \param semi2_state State to start the semi2(outgoing chan) channel in.
00198  * \param exten Exten to start the chennels in. (NULL if s)
00199  * \param context Context to start the channels in. (NULL if default)
00200  * \param requestor Channel requesting creation. (NULL if none)
00201  * \param callid Thread callid to use.
00202  *
00203  * \retval semi1_channel on success.
00204  * \retval NULL on error.
00205  */
00206 struct ast_channel *ast_unreal_new_channels(struct ast_unreal_pvt *p,
00207    const struct ast_channel_tech *tech, int semi1_state, int semi2_state,
00208    const char *exten, const char *context, const struct ast_assigned_ids *assignedids, 
00209    const struct ast_channel *requestor, ast_callid callid);
00210 
00211 /*!
00212  * \brief Setup unreal owner and chan channels before initiating call.
00213  * \since 12.0.0
00214  *
00215  * \param semi1 Owner channel of unreal channel pair.
00216  * \param semi2 Outgoing channel of unreal channel pair.
00217  *
00218  * \note On entry, the semi1 and semi2 channels are already locked.
00219  *
00220  * \return Nothing
00221  */
00222 void ast_unreal_call_setup(struct ast_channel *semi1, struct ast_channel *semi2);
00223 
00224 /*!
00225  * \brief Push the semi2 unreal channel into a bridge from either member of the unreal pair
00226  * \since 12.0.0
00227  *
00228  * \param ast A member of the unreal channel being pushed
00229  * \param bridge Which bridge we want to push the channel to
00230  * \param flags Feature flags to be set on the bridge channel.
00231  *
00232  * \retval 0 if the channel is successfully imparted onto the bridge
00233  * \retval -1 on failure
00234  *
00235  * \note This is equivalent to ast_call() on unreal based channel drivers that are designed to use it instead.
00236  */
00237 int ast_unreal_channel_push_to_bridge(struct ast_channel *ast, struct ast_bridge *bridge, unsigned int flags);
00238 
00239 /* ------------------------------------------------------------------- */
00240 
00241 #if defined(__cplusplus) || defined(c_plusplus)
00242 }
00243 #endif
00244 
00245 #endif   /* _ASTERISK_CORE_UNREAL_H */

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