Asterisk - The Open Source Telephony Project GIT-master-0bf3178
autochan.h
Go to the documentation of this file.
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"
28
29#ifndef _ASTERISK_AUTOCHAN_H
30#define _ASTERISK_AUTOCHAN_H
31
36};
37
38/*!
39 * \par Just what the $!@# is an autochan?
40 *
41 * An ast_autochan is a structure which contains an ast_channel. The pointer
42 * inside an autochan has the ability to update itself if the channel it points
43 * to is masqueraded into a different channel.
44 *
45 * This has a great benefit for any application or service which creates a thread
46 * outside of the channel's main operating thread which keeps a pointer to said
47 * channel. when a masquerade occurs on the channel, the autochan's chan pointer
48 * will automatically update to point to the new channel.
49 *
50 * Some rules for autochans
51 *
52 * 1. If you are going to use an autochan, then be sure to always refer to the
53 * channel using the chan pointer inside the autochan if possible, since this is
54 * the pointer that will be updated during a masquerade.
55 *
56 * 2. If you are going to save off a pointer to the autochan's chan, then be sure
57 * to save off the pointer using ast_channel_ref and to unref the channel when you
58 * are finished with the pointer. If you do not do this and a masquerade occurs on
59 * the channel, then it is possible that your saved pointer will become invalid.
60 *
61 * 3. If you want to lock the autochan->chan channel, be sure to use
62 * ast_autochan_channel_lock and ast_autochan_channel_unlock. An attempt to lock
63 * the autochan->chan directly may result in it being changed after you've
64 * retrieved the value of chan, but before you've had a chance to lock it.
65 * While chan is locked, the autochan structure is guaranteed to keep the
66 * same channel.
67 */
68
69/*!
70 * \brief Lock the autochan's channel lock.
71 *
72 * \note We must do deadlock avoidance because the channel lock is
73 * superior to the autochan lock in locking order.
74 */
75#define ast_autochan_channel_lock(autochan) \
76 do { \
77 ast_mutex_lock(&(autochan)->lock); \
78 while (ast_channel_trylock((autochan)->chan)) { \
79 DEADLOCK_AVOIDANCE(&(autochan)->lock); \
80 } \
81 ast_mutex_unlock(&(autochan)->lock); \
82 } while (0)
83
84#define ast_autochan_channel_unlock(autochan) \
85 ast_channel_unlock(autochan->chan)
86
87/*!
88 * \brief set up a new ast_autochan structure
89 *
90 * \details
91 * Allocates and initializes an ast_autochan, sets the
92 * autochan's chan pointer to point to the chan parameter, and
93 * adds the autochan to the global list of autochans. The newly-
94 * created autochan is returned to the caller. This function will
95 * cause the refcount of chan to increase by 1.
96 *
97 * \param chan The channel our new autochan will point to
98 *
99 * \note autochans must be freed using ast_autochan_destroy
100 *
101 * \retval NULL Failure
102 * \retval non-NULL success
103 */
105
106/*!
107 * \brief destroy an ast_autochan structure
108 *
109 * \details
110 * Removes the passed-in autochan from the list of autochans and
111 * unrefs the channel that is pointed to. Also frees the autochan
112 * struct itself. This function will unref the channel reference
113 * which was made in ast_autochan_setup
114 *
115 * \param autochan The autochan that you wish to destroy
116 */
117void ast_autochan_destroy(struct ast_autochan *autochan);
118
119/*!
120 * \brief Switch what channel autochans point to
121 *
122 * \details
123 * Traverses the list of autochans. All autochans which point to
124 * old_chan will be updated to point to new_chan instead. Currently
125 * this is only called during an ast_channel_move() operation in
126 * channel.c.
127 *
128 * \pre Both channels must be locked before calling this function.
129 *
130 * \param old_chan The channel that autochans may currently point to
131 * \param new_chan The channel that we want to point those autochans to now
132 */
133void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan);
134
135#endif /* _ASTERISK_AUTOCHAN_H */
Asterisk main include file. File version handling, generic pbx functions.
void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan)
Switch what channel autochans point to.
Definition: autochan.c:86
struct ast_autochan * ast_autochan_setup(struct ast_channel *chan)
set up a new ast_autochan structure
Definition: autochan.c:38
void ast_autochan_destroy(struct ast_autochan *autochan)
destroy an ast_autochan structure
Definition: autochan.c:64
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
struct ast_channel * chan
Definition: autochan.h:33
struct ast_autochan::@188 list
ast_mutex_t lock
Definition: autochan.h:35
Main Channel structure associated with a channel.
Structure for mutex and tracking information.
Definition: lock.h:135