SDP: Set the remote c= line in RTP instance.
[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  * \note It is assumed that the passed in SDP has been checked for sanity
150  * already.  e.g., There are no syntax errors, a c= line is reachable for
151  * each m= line, etc...
152  *
153  * \retval 0 Success
154  * \retval non-0 Failure
155  *
156  * \since 15
157  */
158 int ast_sdp_state_set_remote_sdp(struct ast_sdp_state *sdp_state, const struct ast_sdp *sdp);
159
160 /*!
161  * \brief Set the remote SDP from an Implementation
162  *
163  * \param sdp_state
164  * \param remote The implementation's representation of an SDP.
165  *
166  * \retval 0 Success
167  * \retval non-0 Failure
168  *
169  * \since 15
170  */
171 int ast_sdp_state_set_remote_sdp_from_impl(struct ast_sdp_state *sdp_state, const void *remote);
172
173 /*!
174  * \brief Reset the SDP state and stream capabilities as if the SDP state had just been allocated.
175  *
176  * \param sdp_state
177  * \param remote The implementation's representation of an SDP.
178  *
179  * \retval 0 Success
180  *
181  * \note
182  * This is most useful for when a channel driver is sending a session refresh message
183  * and needs to re-advertise its initial capabilities instead of the previously-negotiated
184  * joint capabilities.
185  *
186  * \since 15
187  */
188 int ast_sdp_state_reset(struct ast_sdp_state *sdp_state);
189
190 /*!
191  * \brief Update the local stream topology on the SDP state.
192  *
193  * \param sdp_state
194  * \param streams The new stream topology.
195  *
196  * \retval 0 Success
197  *
198  * \since 15
199  */
200 int ast_sdp_state_update_local_topology(struct ast_sdp_state *sdp_state, struct ast_stream_topology *streams);
201
202 /*!
203  * \brief Set the local address (IP address) to use for connection addresses
204  *
205  * \param sdp_state
206  * \param address The local address
207  *
208  * \note
209  * Passing NULL as an address will unset the explicit local connection address.
210  *
211  * \since 15
212  */
213 void ast_sdp_state_set_local_address(struct ast_sdp_state *sdp_state, struct ast_sockaddr *address);
214
215 /*!
216  * \brief Set the connection address (IP address and port) to use for a specific stream
217  *
218  * \param sdp_state
219  * \param stream_index The stream to set the connection address for
220  * \param address The connection address
221  *
222  * \retval 0 Success
223  *
224  * \note
225  * Passing NULL as an address will unset the explicit local connection address.
226  *
227  * \since 15
228  */
229 int ast_sdp_state_set_connection_address(struct ast_sdp_state *sdp_state, int stream_index,
230         struct ast_sockaddr *address);
231
232 /*!
233  * \since 15.0.0
234  * \brief Set a stream to be held or unheld
235  *
236  * \param sdp_state
237  * \param stream_index The stream to set the held value for
238  * \param locally_held
239  */
240 void ast_sdp_state_set_locally_held(struct ast_sdp_state *sdp_state,
241         int stream_index, unsigned int locally_held);
242
243 /*!
244  * \since 15.0.0
245  * \brief Set the UDPTL session parameters
246  *
247  * \param sdp_state
248  * \param stream_index The stream to set the UDPTL session parameters for
249  * \param params
250  */
251 void ast_sdp_state_set_t38_parameters(struct ast_sdp_state *sdp_state,
252         int stream_index, struct ast_control_t38_parameters *params);
253
254 /*!
255  * \since 15.0.0
256  * \brief Get whether a stream is held or not
257  *
258  * \param sdp_state
259  * \param stream_index The stream to get the held state for
260  *
261  * \returns locally_held
262  */
263 unsigned int ast_sdp_state_get_locally_held(const struct ast_sdp_state *sdp_state,
264         int stream_index);
265
266 #endif /* _ASTERISK_SDP_STATE_H */