a0981b7c9f6b5cedbf824773021c05745e04db2d
[asterisk/asterisk.git] / 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 during an ast_channel_move() operation in
102  * channel.c.
103  *
104  * \pre Both channels must be locked before calling this function.
105  *
106  * \param old_chan The channel that autochans may currently point to
107  * \param new_chan The channel that we want to point those autochans to now
108  *
109  * \retval void
110  */
111 void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan);
112
113 #endif /* _ASTERISK_AUTOCHAN_H */