SDP: Make SDP translation to/from internal representation more const.
[asterisk/asterisk.git] / include / asterisk / sdp_state.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2017, 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 #ifndef _ASTERISK_SDP_STATE_H
20 #define _ASTERISK_SDP_STATE_H
21
22 #include "asterisk/stream.h"
23 #include "asterisk/sdp_options.h"
24
25 struct ast_sdp_state;
26 struct ast_sockaddr;
27 struct ast_udptl;
28 struct ast_control_t38_parameters;
29
30 /*!
31  * \brief Allocate a new SDP state
32  *
33  * SDP state keeps tabs on everything SDP-related for a media session.
34  * Most SDP operations will require the state to be provided.
35  * Ownership of the SDP options is taken on by the SDP state.
36  * A good strategy is to call this during session creation.
37  */
38 struct ast_sdp_state *ast_sdp_state_alloc(struct ast_stream_topology *streams,
39         struct ast_sdp_options *options);
40
41 /*!
42  * \brief Free the SDP state.
43  *
44  * A good strategy is to call this during session destruction
45  */
46 void ast_sdp_state_free(struct ast_sdp_state *sdp_state);
47
48 /*!
49  * \brief Get the associated RTP instance for a particular stream on the SDP state.
50  *
51  * Stream numbers correspond to the streams in the topology of the associated channel
52  */
53 struct ast_rtp_instance *ast_sdp_state_get_rtp_instance(const struct ast_sdp_state *sdp_state,
54         int stream_index);
55
56 /*!
57  * \brief Get the associated UDPTL instance for a particular stream on the SDP state.
58  *
59  * Stream numbers correspond to the streams in the topology of the associated channel
60  */
61 struct ast_udptl *ast_sdp_state_get_udptl_instance(const struct ast_sdp_state *sdp_state,
62         int stream_index);
63
64 /*!
65  * \brief Get the global connection address on the SDP state.
66  */
67 const struct ast_sockaddr *ast_sdp_state_get_connection_address(const struct ast_sdp_state *sdp_state);
68
69 /*!
70  * \brief Get the connection address for a particular stream.
71  *
72  * \param sdp_state
73  * \param stream_index The particular stream to get the connection address of
74  * \param address[out] A place to store the address in
75  *
76  * \retval 0 Success
77  *
78  * \note
79  * Stream numbers correspond to the streams in the topology of the associated channel
80  */
81 int ast_sdp_state_get_stream_connection_address(const struct ast_sdp_state *sdp_state,
82         int stream_index, struct ast_sockaddr *address);
83
84 /*!
85  * \brief Get the joint negotiated streams based on local and remote capabilities.
86  *
87  * If this is called prior to receiving a remote SDP, then this will just mirror
88  * the local configured endpoint capabilities.
89  */
90 const struct ast_stream_topology *ast_sdp_state_get_joint_topology(
91         const struct ast_sdp_state *sdp_state);
92
93 /*!
94  * \brief Get the local topology
95  *
96  */
97 const struct ast_stream_topology *ast_sdp_state_get_local_topology(
98         const struct ast_sdp_state *sdp_state);
99
100 /*!
101  * \brief Get the sdp_state options
102  *
103  */
104 const struct ast_sdp_options *ast_sdp_state_get_options(
105         const struct ast_sdp_state *sdp_state);
106
107
108 /*!
109  * \brief Get the local SDP.
110  *
111  * \param sdp_state
112  *
113  * \retval non-NULL Success
114  * \retval NULL Failure
115  *
116  * \note
117  * This function will allocate a new SDP with RTP instances if it has not already
118  * been allocated.
119  *
120  */
121 const struct ast_sdp *ast_sdp_state_get_local_sdp(struct ast_sdp_state *sdp_state);
122
123 /*!
124  * \brief Get the local SDP Implementation.
125  *
126  * \param sdp_state
127  *
128  * \retval non-NULL Success
129  * \retval NULL Failure
130  *
131  * \note
132  * This function calls ast_sdp_state_get_local_sdp then translates it into
133  * the defined implementation.
134  *
135  * The return here is const. The use case for this is so that a channel can add
136  * the SDP to an outgoing message. The API user should not attempt to modify the SDP.
137  * SDP modification should only be done through the API.
138  *
139  * \since 15
140  */
141 const void *ast_sdp_state_get_local_sdp_impl(struct ast_sdp_state *sdp_state);
142
143 /*!
144  * \brief Set the remote SDP
145  *
146  * \param sdp_state
147  * \param sdp
148  *
149  * \retval 0 Success
150  * \retval non-0 Failure
151  *
152  * \since 15
153  */
154 int ast_sdp_state_set_remote_sdp(struct ast_sdp_state *sdp_state, const struct ast_sdp *sdp);
155
156 /*!
157  * \brief Set the remote SDP from an Implementation
158  *
159  * \param sdp_state
160  * \param remote The implementation's representation of an SDP.
161  *
162  * \retval 0 Success
163  * \retval non-0 Failure
164  *
165  * \since 15
166  */
167 int ast_sdp_state_set_remote_sdp_from_impl(struct ast_sdp_state *sdp_state, const void *remote);
168
169 /*!
170  * \brief Reset the SDP state and stream capabilities as if the SDP state had just been allocated.
171  *
172  * \param sdp_state
173  * \param remote The implementation's representation of an SDP.
174  *
175  * \retval 0 Success
176  *
177  * \note
178  * This is most useful for when a channel driver is sending a session refresh message
179  * and needs to re-advertise its initial capabilities instead of the previously-negotiated
180  * joint capabilities.
181  *
182  * \since 15
183  */
184 int ast_sdp_state_reset(struct ast_sdp_state *sdp_state);
185
186 /*!
187  * \brief Update the local stream topology on the SDP state.
188  *
189  * \param sdp_state
190  * \param streams The new stream topology.
191  *
192  * \retval 0 Success
193  *
194  * \since 15
195  */
196 int ast_sdp_state_update_local_topology(struct ast_sdp_state *sdp_state, struct ast_stream_topology *streams);
197
198 /*!
199  * \brief Set the local address (IP address) to use for connection addresses
200  *
201  * \param sdp_state
202  * \param address The local address
203  *
204  * \note
205  * Passing NULL as an address will unset the explicit local connection address.
206  *
207  * \since 15
208  */
209 void ast_sdp_state_set_local_address(struct ast_sdp_state *sdp_state, struct ast_sockaddr *address);
210
211 /*!
212  * \brief Set the connection address (IP address and port) to use for a specific stream
213  *
214  * \param sdp_state
215  * \param stream_index The stream to set the connection address for
216  * \param address The connection address
217  *
218  * \retval 0 Success
219  *
220  * \note
221  * Passing NULL as an address will unset the explicit local connection address.
222  *
223  * \since 15
224  */
225 int ast_sdp_state_set_connection_address(struct ast_sdp_state *sdp_state, int stream_index,
226         struct ast_sockaddr *address);
227
228 /*!
229  * \since 15.0.0
230  * \brief Set a stream to be held or unheld
231  *
232  * \param sdp_state
233  * \param stream_index The stream to set the held value for
234  * \param locally_held
235  */
236 void ast_sdp_state_set_locally_held(struct ast_sdp_state *sdp_state,
237         int stream_index, unsigned int locally_held);
238
239 /*!
240  * \since 15.0.0
241  * \brief Set the UDPTL session parameters
242  *
243  * \param sdp_state
244  * \param stream_index The stream to set the UDPTL session parameters for
245  * \param params
246  */
247 void ast_sdp_state_set_t38_parameters(struct ast_sdp_state *sdp_state,
248         int stream_index, struct ast_control_t38_parameters *params);
249
250 /*!
251  * \since 15.0.0
252  * \brief Get whether a stream is held or not
253  *
254  * \param sdp_state
255  * \param stream_index The stream to get the held state for
256  *
257  * \returns locally_held
258  */
259 unsigned int ast_sdp_state_get_locally_held(const struct ast_sdp_state *sdp_state,
260         int stream_index);
261
262 #endif /* _ASTERISK_SDP_STATE_H */