8557072c69bfd81cb1fc909b7514b90f7c03377f
[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 Lock the "chan" and "owner" channels (and return them) on the base
46  *        private structure as well as the base private structure itself.
47  *
48  * \note This also adds references to each of the above mentioned elements and
49  *       also the underlying private local structure.
50  * \note None of these locks should be held prior to calling this function.
51  * \note To undo this process call ast_local_unlock_all.
52  *
53  * \since 13.8.0
54  *
55  * \param chan Must be a local channel
56  * \param outchan The local channel's "chan" channel
57  * \param outowner The local channel's "owner" channel
58  */
59 void ast_local_lock_all(struct ast_channel *chan, struct ast_channel **outchan,
60                         struct ast_channel **outowner);
61
62 /*!
63  * \brief Unlock the "chan" and "owner" channels on the base private structure
64  *        as well as the base private structure itself.
65  *
66  * \note This also removes references to each of the above mentioned elements and
67  *       also the underlying private local structure.
68  * \note This function should be used in conjunction with ast_local_lock_all.
69  *
70  * \since 13.8.0
71  *
72  * \param chan Must be a local channel
73  */
74 void ast_local_unlock_all(struct ast_channel *chan);
75
76 /*!
77  * \brief Get the other local channel in the pair.
78  * \since 12.0.0
79  *
80  * \param ast Local channel to get peer.
81  *
82  * \note On entry, ast must be locked.
83  *
84  * \retval peer reffed on success.
85  * \retval NULL if no peer or error.
86  */
87 struct ast_channel *ast_local_get_peer(struct ast_channel *ast);
88
89 /*!
90  * \brief Setup the outgoing local channel to join a bridge on ast_call().
91  * \since 12.0.0
92  *
93  * \param ast Either channel of a local channel pair.
94  * \param bridge Bridge to join.
95  * \param swap Channel to swap with when joining.
96  * \param features Bridge features structure.
97  *
98  * \note The features parameter must be NULL or obtained by
99  * ast_bridge_features_new().  You must not dereference features
100  * after calling even if the call fails.
101  *
102  * \note Intended to be called after ast_request() and before
103  * ast_call() on a local channel.
104  *
105  * \retval 0 on success.
106  * \retval -1 on error.
107  */
108 int ast_local_setup_bridge(struct ast_channel *ast, struct ast_bridge *bridge, struct ast_channel *swap, struct ast_bridge_features *features);
109
110 /*!
111  * \brief Setup the outgoing local channel to masquerade into a channel on ast_call().
112  * \since 12.0.0
113  *
114  * \param ast Either channel of a local channel pair.
115  * \param masq Channel to masquerade into.
116  *
117  * \note Intended to be called after ast_request() and before
118  * ast_call() on a local channel.
119  *
120  * \retval 0 on success.
121  * \retval -1 on error.
122  */
123 int ast_local_setup_masquerade(struct ast_channel *ast, struct ast_channel *masq);
124
125 /* ------------------------------------------------------------------- */
126
127 /*!
128  * \brief Message type for when two local channel halves are bridged together
129  * \since 12.0.0
130  *
131  * \note Payloads for the \ref ast_local_bridge_type are a \ref ast_multi_channel_blob.
132  * Roles for the channels in the \ref ast_multi_channel_blob are "1" and "2", reflecting
133  * the two halves. Unlike most other bridges, the 'bridge' between two local channels is
134  * not part of the bridge framework; as such, the message simply references the two local
135  * channel halves that are now bridged.
136  *
137  * \retval A \ref stasis message type
138  */
139 struct stasis_message_type *ast_local_bridge_type(void);
140
141 /*!
142  * \brief Message type for when a local channel optimization begins
143  * \since 12.0.0
144  *
145  * \note Payloads for the \ref ast_local_optimization_begin_type are a
146  * \ref ast_multi_channel_blob. Roles for the channels in the \ref ast_multi_channel_blob
147  * are "1" and "2", reflecting the two halves.
148  *
149  * \retval A \ref stasis message type
150  */
151 struct stasis_message_type *ast_local_optimization_begin_type(void);
152
153 /*!
154  * \brief Message type for when a local channel optimization completes
155  * \since 12.0.0
156  *
157  * \note Payloads for the \ref ast_local_optimization_end_type are a
158  * \ref ast_multi_channel_blob. Roles for the channels in the \ref ast_multi_channel_blob
159  * are "1" and "2", reflecting the two halves.
160  *
161  * \retval A \ref stasis message type
162  */
163 struct stasis_message_type *ast_local_optimization_end_type(void);
164
165 #if defined(__cplusplus) || defined(c_plusplus)
166 }
167 #endif
168
169 #endif  /* _ASTERISK_CORE_LOCAL_H */