core_local: local channel data not being properly unref'ed and unlocked
[asterisk/asterisk.git] / include / asterisk / core_local.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Richard Mudgett <rmudgett@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 Local proxy channel special access.
22  *
23  * \author Richard Mudgett <rmudgett@digium.com>
24  *
25  * See Also:
26  * \arg \ref AstCREDITS
27  */
28
29 #ifndef _ASTERISK_CORE_LOCAL_H
30 #define _ASTERISK_CORE_LOCAL_H
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C" {
34 #endif
35
36 /* Forward declare some struct names */
37 struct ast_channel;
38 struct ast_bridge;
39 struct ast_bridge_features;
40 struct stasis_message_type;
41
42 /* ------------------------------------------------------------------- */
43
44 /*!
45  * \brief Add a reference to the local channel's private tech, lock the local channel's
46  *        private base, and add references and lock both sides of the local channel.
47  *
48  * \note None of these locks should be held prior to calling this function.
49  * \note To undo this process call ast_local_unlock_all2.
50  *
51  * \since 13.17.0, 14.6.0
52  *
53  * \param chan Must be a local channel
54  * \param tech_pvt [out] channel's private tech (ref and lock added)
55  * \param base_chan [out] One side of the local channel (ref and lock added)
56  * \param base_owner [out] Other side of the local channel (ref and lock added)
57  */
58 void ast_local_lock_all(struct ast_channel *chan, void **tech_pvt,
59         struct ast_channel **base_chan, struct ast_channel **base_owner);
60
61 /*!
62  * \brief Remove a reference to the given local channel's private tech, unlock the given
63  *        local channel's private base, and remove references and unlock both sides of
64  *        given the local channel.
65  *
66  * \note This function should be used in conjunction with ast_local_lock_all2.
67  *
68  * \since 13.17.0, 14.6.0
69  *
70  * \param tech_pvt channel's private tech (ref and lock removed)
71  * \param base_chan One side of the local channel (ref and lock removed)
72  * \param base_owner Other side of the local channel (ref and lock removed)
73  */
74 void ast_local_unlock_all(void *tech_pvt, struct ast_channel *base_chan,
75         struct ast_channel *base_owner);
76
77 /*!
78  * \brief Get the other local channel in the pair.
79  * \since 12.0.0
80  *
81  * \param ast Local channel to get peer.
82  *
83  * \note On entry, ast must be locked.
84  *
85  * \retval peer reffed on success.
86  * \retval NULL if no peer or error.
87  */
88 struct ast_channel *ast_local_get_peer(struct ast_channel *ast);
89
90 /*!
91  * \brief Setup the outgoing local channel to join a bridge on ast_call().
92  * \since 12.0.0
93  *
94  * \param ast Either channel of a local channel pair.
95  * \param bridge Bridge to join.
96  * \param swap Channel to swap with when joining.
97  * \param features Bridge features structure.
98  *
99  * \note The features parameter must be NULL or obtained by
100  * ast_bridge_features_new().  You must not dereference features
101  * after calling even if the call fails.
102  *
103  * \note Intended to be called after ast_request() and before
104  * ast_call() on a local channel.
105  *
106  * \retval 0 on success.
107  * \retval -1 on error.
108  */
109 int ast_local_setup_bridge(struct ast_channel *ast, struct ast_bridge *bridge, struct ast_channel *swap, struct ast_bridge_features *features);
110
111 /*!
112  * \brief Setup the outgoing local channel to masquerade into a channel on ast_call().
113  * \since 12.0.0
114  *
115  * \param ast Either channel of a local channel pair.
116  * \param masq Channel to masquerade into.
117  *
118  * \note Intended to be called after ast_request() and before
119  * ast_call() on a local channel.
120  *
121  * \retval 0 on success.
122  * \retval -1 on error.
123  */
124 int ast_local_setup_masquerade(struct ast_channel *ast, struct ast_channel *masq);
125
126 /* ------------------------------------------------------------------- */
127
128 /*!
129  * \brief Message type for when two local channel halves are bridged together
130  * \since 12.0.0
131  *
132  * \note Payloads for the \ref ast_local_bridge_type are a \ref ast_multi_channel_blob.
133  * Roles for the channels in the \ref ast_multi_channel_blob are "1" and "2", reflecting
134  * the two halves. Unlike most other bridges, the 'bridge' between two local channels is
135  * not part of the bridge framework; as such, the message simply references the two local
136  * channel halves that are now bridged.
137  *
138  * \retval A \ref stasis message type
139  */
140 struct stasis_message_type *ast_local_bridge_type(void);
141
142 /*!
143  * \brief Message type for when a local channel optimization begins
144  * \since 12.0.0
145  *
146  * \note Payloads for the \ref ast_local_optimization_begin_type are a
147  * \ref ast_multi_channel_blob. Roles for the channels in the \ref ast_multi_channel_blob
148  * are "1" and "2", reflecting the two halves.
149  *
150  * \retval A \ref stasis message type
151  */
152 struct stasis_message_type *ast_local_optimization_begin_type(void);
153
154 /*!
155  * \brief Message type for when a local channel optimization completes
156  * \since 12.0.0
157  *
158  * \note Payloads for the \ref ast_local_optimization_end_type are a
159  * \ref ast_multi_channel_blob. Roles for the channels in the \ref ast_multi_channel_blob
160  * are "1" and "2", reflecting the two halves.
161  *
162  * \retval A \ref stasis message type
163  */
164 struct stasis_message_type *ast_local_optimization_end_type(void);
165
166 #if defined(__cplusplus) || defined(c_plusplus)
167 }
168 #endif
169
170 #endif  /* _ASTERISK_CORE_LOCAL_H */