autochan.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  * Mark Michelson <mmichelson@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 "smart" channels that update automatically if a channel is masqueraded
00022  *
00023  * \author Mark Michelson <mmichelson@digium.com>
00024  */
00025 
00026 #include "asterisk.h"
00027 #include "asterisk/linkedlists.h"
00028 
00029 #ifndef _ASTERISK_AUTOCHAN_H
00030 #define _ASTERISK_AUTOCHAN_H
00031 
00032 struct ast_autochan {
00033    struct ast_channel *chan;
00034    AST_LIST_ENTRY(ast_autochan) list;
00035 };
00036 
00037 /*! 
00038  * \par Just what the $!@# is an autochan?
00039  *
00040  * An ast_autochan is a structure which contains an ast_channel. The pointer
00041  * inside an autochan has the ability to update itself if the channel it points
00042  * to is masqueraded into a different channel.
00043  *
00044  * This has a great benefit for any application or service which creates a thread
00045  * outside of the channel's main operating thread which keeps a pointer to said
00046  * channel. when a masquerade occurs on the channel, the autochan's chan pointer
00047  * will automatically update to point to the new channel.
00048  *
00049  * Some rules for autochans
00050  *
00051  * 1. If you are going to use an autochan, then be sure to always refer to the
00052  * channel using the chan pointer inside the autochan if possible, since this is
00053  * the pointer that will be updated during a masquerade.
00054  *
00055  * 2. If you are going to save off a pointer to the autochan's chan, then be sure
00056  * to save off the pointer using ast_channel_ref and to unref the channel when you
00057  * are finished with the pointer. If you do not do this and a masquerade occurs on
00058  * the channel, then it is possible that your saved pointer will become invalid.
00059  */
00060 
00061 /*!
00062  * \brief set up a new ast_autochan structure
00063  *
00064  * \details
00065  * Allocates and initializes an ast_autochan, sets the
00066  * autochan's chan pointer to point to the chan parameter, and
00067  * adds the autochan to the global list of autochans. The newly-
00068  * created autochan is returned to the caller. This function will
00069  * cause the refcount of chan to increase by 1.
00070  *
00071  * \param chan The channel our new autochan will point to
00072  *
00073  * \note autochans must be freed using ast_autochan_destroy
00074  *
00075  * \retval NULL Failure
00076  * \retval non-NULL success
00077  */
00078 struct ast_autochan *ast_autochan_setup(struct ast_channel *chan);
00079 
00080 /*!
00081  * \brief destroy an ast_autochan structure
00082  *
00083  * \details
00084  * Removes the passed-in autochan from the list of autochans and
00085  * unrefs the channel that is pointed to. Also frees the autochan
00086  * struct itself. This function will unref the channel reference
00087  * which was made in ast_autochan_setup
00088  *
00089  * \param autochan The autochan that you wish to destroy
00090  *
00091  * \retval void
00092  */
00093 void ast_autochan_destroy(struct ast_autochan *autochan);
00094 
00095 /*!
00096  * \brief Switch what channel autochans point to
00097  *
00098  * \details
00099  * Traverses the list of autochans. All autochans which point to
00100  * old_chan will be updated to point to new_chan instead. Currently
00101  * this is only called during an ast_channel_move() operation in
00102  * channel.c.
00103  *
00104  * \pre Both channels must be locked before calling this function.
00105  *
00106  * \param old_chan The channel that autochans may currently point to
00107  * \param new_chan The channel that we want to point those autochans to now
00108  *
00109  * \retval void
00110  */
00111 void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan);
00112 
00113 #endif /* _ASTERISK_AUTOCHAN_H */

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