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 from ast_do_masquerade in channel.c. 00102 * 00103 * \pre Both channels must be locked before calling this function. 00104 * 00105 * \param old_chan The channel that autochans may currently point to 00106 * \param new_chan The channel that we want to point those autochans to now 00107 * 00108 * \retval void 00109 */ 00110 void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan); 00111 00112 #endif /* _ASTERISK_AUTOCHAN_H */