include/asterisk/autochan.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2009, Digium, Inc.
   5  *
   6  * Mark Michelson <mmichelson@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*!
  20  * \file
  21  * \brief "smart" channels that update automatically if a channel is masqueraded
  22  *
  23  * \author Mark Michelson <mmichelson@digium.com>
  24  */
  25
  26 #include "asterisk.h"
  27 #include "asterisk/linkedlists.h"
  28
  29 #ifndef _ASTERISK_AUTOCHAN_H
  30 #define _ASTERISK_AUTOCHAN_H
  31
  32 struct ast_autochan {
  33         struct ast_channel *chan;
  34         AST_LIST_ENTRY(ast_autochan) list;
  35 };
  36
  37 /*!
  38  * \par Just what the $!@# is an autochan?
  39  *
  40  * An ast_autochan is a structure which contains an ast_channel. The pointer
  41  * inside an autochan has the ability to update itself if the channel it points
  42  * to is masqueraded into a different channel.
  43  *
  44  * This has a great benefit for any application or service which creates a thread
  45  * outside of the channel's main operating thread which keeps a pointer to said
  46  * channel. when a masquerade occurs on the channel, the autochan's chan pointer
  47  * will automatically update to point to the new channel.
  48  *
  49  * Some rules for autochans
  50  *
  51  * 1. If you are going to use an autochan, then be sure to always refer to the
  52  * channel using the chan pointer inside the autochan if possible, since this is
  53  * the pointer that will be updated during a masquerade.
  54  *
  55  * 2. If you are going to save off a pointer to the autochan's chan, then be sure
  56  * to save off the pointer using ast_channel_ref and to unref the channel when you
  57  * are finished with the pointer. If you do not do this and a masquerade occurs on
  58  * the channel, then it is possible that your saved pointer will become invalid.
  59  */
  60
  61 /*!
  62  * \brief set up a new ast_autochan structure
  63  *
  64  * \details
  65  * Allocates and initializes an ast_autochan, sets the
  66  * autochan's chan pointer to point to the chan parameter, and
  67  * adds the autochan to the global list of autochans. The newly-
  68  * created autochan is returned to the caller. This function will
  69  * cause the refcount of chan to increase by 1.
  70  *
  71  * \param chan The channel our new autochan will point to
  72  *
  73  * \note autochans must be freed using ast_autochan_destroy
  74  *
  75  * \retval NULL Failure
  76  * \retval non-NULL success
  77  */
  78 struct ast_autochan *ast_autochan_setup(struct ast_channel *chan);
  79
  80 /*!
  81  * \brief destroy an ast_autochan structure
  82  *
  83  * \details
  84  * Removes the passed-in autochan from the list of autochans and
  85  * unrefs the channel that is pointed to. Also frees the autochan
  86  * struct itself. This function will unref the channel reference
  87  * which was made in ast_autochan_setup
  88  *
  89  * \param autochan The autochan that you wish to destroy
  90  *
  91  * \retval void
  92  */
  93 void ast_autochan_destroy(struct ast_autochan *autochan);
  94
  95 /*!
  96  * \brief Switch what channel autochans point to
  97  *
  98  * \details
  99  * Traverses the list of autochans. All autochans which point to
 100  * old_chan will be updated to point to new_chan instead. Currently
 101  * this is only called from ast_do_masquerade in channel.c.
 102  *
 103  * \pre Both channels must be locked before calling this function.
 104  *
 105  * \param old_chan The channel that autochans may currently point to
 106  * \param new_chan The channel that we want to point those autochans to now
 107  *
 108  * \retval void
 109  */
 110 void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan);
 111
 112 #endif /* _ASTERISK_AUTOCHAN_H */