Statistics
| Branch: | Revision:

janus-gateway / ice.h @ 5e9e29e0

History | View | Annotate | Download (11.3 KB)

1 be35facb meetecho
/*! \file    ice.h
2
 * \author   Lorenzo Miniero <lorenzo@meetecho.com>
3
 * \copyright GNU Affero General Public License v3
4
 * \brief    ICE/STUN/TURN processing (headers)
5
 * \details  Implementation (based on libnice) of the ICE process. The
6
 * code handles the whole ICE process, from the gathering of candidates
7
 * to the final setup of a virtual channel RTP and RTCP can be transported
8
 * on. Incoming RTP and RTCP packets from peers are relayed to the associated
9
 * plugins by means of the incoming_rtp and incoming_rtcp callbacks. Packets
10
 * to be sent to peers are relayed by peers invoking the relay_rtp and
11
 * relay_rtcp gateway callbacks instead. 
12
 * 
13
 * \ingroup protocols
14
 * \ref protocols
15
 */
16
 
17
#ifndef _JANUS_ICE_H
18
#define _JANUS_ICE_H
19
20
#include <glib.h>
21
#include <agent.h>
22
23
#include "plugins/plugin.h"
24
25
26
/*! \brief ICE stuff initialization
27
 * @param[in] stun_server STUN server address to use, if any
28
 * @param[in] stun_port STUN port to use, if any
29 5e9e29e0 meetecho
 * @param[in] rtp_min_port Minimum port to use for RTP/RTCP, if a range is to be used
30
 * @param[in] rtp_max_port Maximum port to use for RTP/RTCP, if a range is to be used
31 be35facb meetecho
 * @returns 0 in case of success, a negative integer on errors */
32 5e9e29e0 meetecho
gint janus_ice_init(gchar *stun_server, uint16_t stun_port, uint16_t rtp_min_port, uint16_t rtp_max_port);
33 be35facb meetecho
/*! \brief Method to get the STUN server IP address
34
 * @returns The currently used STUN server IP address, if available, or NULL if not */
35
char *janus_ice_get_stun_server(void);
36
/*! \brief Method to get the STUN server port
37
 * @returns The currently used STUN server port, if available, or 0 if not */
38
uint16_t janus_ice_get_stun_port(void);
39
40
41
/*! \brief Helper method to get a string representation of a libnice ICE state
42
 * @param[in] state The libnice ICE state
43
 * @returns A string representation of the libnice ICE state */
44
const gchar *janus_get_ice_state_name(gint state);
45
46
47
/*! \brief Janus ICE handle/session */
48
typedef struct janus_ice_handle janus_ice_handle;
49
/*! \brief Janus ICE stream */
50
typedef struct janus_ice_stream janus_ice_stream;
51
/*! \brief Janus ICE component */
52
typedef struct janus_ice_component janus_ice_component;
53
54
/*! \brief Janus ICE handle */
55
struct janus_ice_handle {
56
        /*! \brief Opaque pointer to the gateway/peer session */
57
        void *session;
58
        /*! \brief Handle identifier */
59
        guint64 handle_id;
60
        /*! \brief Opaque application (plugin) pointer */
61
        void *app;
62
        /*! \brief Opaque gateway/plugin session pointer */
63
        janus_pluginession *app_handle;
64
        /*! \brief Flag to check whether this ICE session needs to stop right now */
65
        gint stop:1;
66
        /*! \brief Number of gathered candidates */
67
        gint cdone;
68
        /*! \brief GLib context for libnice */
69
        GMainContext *icectx;
70
        /*! \brief GLib loop for libnice */
71
        GMainLoop *iceloop;
72
        /*! \brief GLib thread for libnice */
73
        GThread *icethread;
74
        /*! \brief libnice ICE agent */
75
        NiceAgent *agent;
76
        /*! \brief libnice ICE audio ID */
77
        gint audio_id;
78
        /*! \brief libnice ICE audio ID */
79
        gint video_id;
80
        /*! \brief Number of streams */
81
        gint streams_num;
82
        /*! \brief GLib hash table of streams (IDs are the keys) */
83
        GHashTable *streams;
84
        /*! \brief Audio stream */
85
        janus_ice_stream *audio_stream;
86
        /*! \brief Video stream */
87
        janus_ice_stream *video_stream;
88
        /*! \brief Hashing algorhitm used by the peer for the DTLS certificate (e.g., "SHA-256") */
89
        gchar *remote_hashing;
90
        /*! \brief Hashed fingerprint of the peer's certificate, as parsed in SDP */
91
        gchar *remote_fingerprint;
92
        /*! \brief Mutex to lock/unlock the ICE session */
93
        janus_mutex mutex;
94
};
95
96
/*! \brief Janus ICE stream */
97
struct janus_ice_stream {
98
        /*! \brief Janus ICE handle this stream belongs to */
99
        janus_ice_handle *handle;
100
        /*! \brief libnice ICE stream ID */
101
        guint stream_id;
102
        /*! \brief Whether this stream is ready to be used */
103
        gint cdone:1;
104
        /*! \brief SSRC of the gateway */
105
        guint32 ssrc;
106
        /*! \brief SSRC of the peer */
107
        guint32 ssrc_peer;
108
        /*! \brief RTP payload type of this stream */
109
        gint payload_type;
110
        /*! \brief DTLS role of the gateway for this stream */
111
        janus_dtls_role dtls_role;
112
        /*! \brief GLib hash table of components (IDs are the keys) */
113
        GHashTable *components;
114
        /*! \brief RTP component */
115
        janus_ice_component *rtp_component;
116
        /*! \brief RTCP component */
117
        janus_ice_component *rtcp_component;
118
        /*! \brief Helper flag to avoid flooding the console with the same error all over again */
119
        gint noerrorlog:1;
120
        /*! \brief Mutex to lock/unlock this stream */
121
        janus_mutex mutex;
122
};
123
124
/*! \brief Janus ICE component */
125
struct janus_ice_component {
126
        /*! \brief Janus ICE stream this component belongs to */
127
        janus_ice_stream *stream;
128
        /*! \brief libnice ICE stream ID */
129
        guint stream_id;
130
        /*! \brief libnice ICE component ID */
131
        guint component_id;
132
        /*! \brief GLib list of libnice candidates for this component */
133
        GSList *candidates;
134
        /*! \brief DTLS-SRTP stack */
135
        janus_dtls_srtp *dtls;
136
        /*! \brief Helper flag to avoid flooding the console with the same error all over again */
137
        gint noerrorlog:1;
138
        /*! \brief Mutex to lock/unlock this stream */
139
        janus_mutex mutex;
140
};
141
142
/** @name Janus ICE handle methods
143
 */
144
///@{
145
/*! \brief Method to create a new Janus ICE handle
146
 * @param[in] gateway_session The gateway/peer session this ICE handle will belong to
147
 * @returns The created Janus ICE handle if successful, NULL otherwise */
148
janus_ice_handle *janus_ice_handle_create(void *gateway_session);
149
/*! \brief Method to find an existing Janus ICE handle from its ID
150
 * @param[in] gateway_session The gateway/peer session this ICE handle belongs to
151
 * @param[in] handle_id The Janus ICE handle ID
152
 * @returns The created Janus ICE handle if successful, NULL otherwise */
153
janus_ice_handle *janus_ice_handle_find(void *gateway_session, guint64 handle_id);
154
/*! \brief Method to attach a Janus ICE handle to a plugin
155
 * \details This method is very important, as it allows plugins to send/receive media (RTP/RTCP) to/from a WebRTC peer.
156
 * @param[in] gateway_session The gateway/peer session this ICE handle belongs to
157
 * @param[in] handle_id The Janus ICE handle ID
158
 * @param[in] plugin The plugin the ICE handle needs to be attached to
159
 * @returns 0 in case of success, a negative integer otherwise */
160
gint janus_ice_handle_attach_plugin(void *gateway_session, guint64 handle_id, janus_plugin *plugin);
161
/*! \brief Method to destroy a Janus ICE handle
162
 * @param[in] gateway_session The gateway/peer session this ICE handle belongs to
163
 * @param[in] handle_id The Janus ICE handle ID to destroy
164
 * @returns 0 in case of success, a negative integer otherwise */
165
gint janus_ice_handle_destroy(void *gateway_session, guint64 handle_id);
166
///@}
167
168
169
/** @name Janus ICE handle callbacks
170
 */
171
///@{
172
/*! \brief libnice callback to notify when candidates have been gathered for an ICE agent
173
 * @param[in] agent The libnice agent for which the callback applies
174
 * @param[in] stream_id The stream ID for which the callback applies
175
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
176
void janus_ice_cb_candidate_gathering_done (NiceAgent *agent, guint stream_id, gpointer ice);
177
/*! \brief libnice callback to notify when the state of a component changes for an ICE agent
178
 * @param[in] agent The libnice agent for which the callback applies
179
 * @param[in] stream_id The stream ID for which the callback applies
180
 * @param[in] component_id The component ID for which the callback applies
181
 * @param[in] state New ICE state of the component
182
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
183
void janus_ice_cb_component_state_changed (NiceAgent *agent, guint stream_id, guint component_id, guint state, gpointer ice);
184
/*! \brief libnice callback to notify when a pair of candidates has been selected for an ICE agent
185
 * @param[in] agent The libnice agent for which the callback applies
186
 * @param[in] stream_id The stream ID for which the callback applies
187
 * @param[in] component_id The component ID for which the callback applies
188
 * @param[in] lfoundation ICE foundation
189
 * @param[in] rfoundation ICE foundation
190
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
191
void janus_ice_cb_new_selected_pair (NiceAgent *agent, guint stream_id, guint component_id, gchar *lfoundation, gchar *rfoundation, gpointer ice);
192
/*! \brief libnice callback to notify when data has been received by an ICE agent
193
 * @param[in] agent The libnice agent for which the callback applies
194
 * @param[in] stream_id The stream ID for which the callback applies
195
 * @param[in] component_id The component ID for which the callback applies
196
 * @param[in] len Length of the data buffer
197
 * @param[in] buf Data buffer
198
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
199
void janus_ice_cb_nice_recv (NiceAgent *agent, guint stream_id, guint component_id, guint len, gchar *buf, gpointer ice);
200
201
/*! \brief Gateway RTP callback, called when a plugin has an RTP packet to send to a peer
202
 * @param[in] handle The Janus ICE handle associated with the peer
203
 * @param[in] video Whether this is an audio or a video frame
204
 * @param[in] buf The packet data (buffer)
205
 * @param[in] len The buffer lenght */
206
void janus_ice_relay_rtp(janus_ice_handle *handle, int video, char *buf, int len);
207
/*! \brief Gateway RTCP callback, called when a plugin has an RTCP message to send to a peer
208
 * @param[in] handle The Janus ICE handle associated with the peer
209
 * @param[in] video Whether this is related to an audio or a video stream
210
 * @param[in] buf The message data (buffer)
211
 * @param[in] len The buffer lenght */
212
void janus_ice_relay_rtcp(janus_ice_handle *handle, int video, char *buf, int len);
213
///@}
214
215
216
/** @name Janus ICE handle helpers
217
 */
218
///@{
219
/*! \brief Janus ICE handle thread */
220
void *janus_ice_thread(void *data);
221
/*! \brief Method to locally set up the ICE candidates (initialization and gathering)
222
 * @param[in] handle The Janus ICE handle this method refers to
223
 * @param[in] offer Whether this is for an OFFER or an ANSWER
224
 * @param[in] audio Whether audio is enabled
225
 * @param[in] video Whether video is enabled
226
 * @returns 0 in case of success, a negative integer otherwise */
227
int janus_ice_setup_local(janus_ice_handle *handle, int offer, int audio, int video);
228
/*! \brief Method to add local candidates to the gateway SDP
229
 * @param[in] handle The Janus ICE handle this method refers to
230
 * @param[in,out] sdp The handle description the gateway is preparing
231
 * @param[in] stream_id The stream ID of the candidate to add to the SDP
232
 * @param[in] component_id The component ID of the candidate to add to the SDP */
233
void janus_ice_setup_candidate(janus_ice_handle *handle, char *sdp, guint stream_id, guint component_id);
234
/*! \brief Method to handle remote candidates and start the connectivity checks
235
 * @param[in] handle The Janus ICE handle this method refers to
236
 * @param[in] stream_id The stream ID of the candidate to add to the SDP
237
 * @param[in] component_id The component ID of the candidate to add to the SDP */
238
void janus_ice_setup_remote_candidate(janus_ice_handle *handle, guint stream_id, guint component_id);
239
/*! \brief Callback to be notified when the DTLS handshake for a specific component has been completed
240
 * \details This method also decides when to notify attached plugins about the availability of a reliable PeerConnection
241
 * @param[in] handle The Janus ICE handle this callback refers to
242
 * @param[in] component The Janus ICE component that is now ready to be used */
243
void janus_ice_dtls_handshake_done(janus_ice_handle *handle, janus_ice_component *component);
244
///@}
245
246
#endif