2 * This file is part of the Nice GLib ICE library.
4 * (C) 2006-2009 Collabora Ltd.
5 * Contact: Youness Alaoui
6 * (C) 2006-2009 Nokia Corporation. All rights reserved.
7 * Contact: Kai Vehmanen
9 * The contents of this file are subject to the Mozilla Public License Version
10 * 1.1 (the "License"); you may not use this file except in compliance with
11 * the License. You may obtain a copy of the License at
12 * http://www.mozilla.org/MPL/
14 * Software distributed under the License is distributed on an "AS IS" basis,
15 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
16 * for the specific language governing rights and limitations under the
19 * The Original Code is the Nice GLib ICE library.
21 * The Initial Developers of the Original Code are Collabora Ltd and Nokia
22 * Corporation. All Rights Reserved.
25 * Dafydd Harries, Collabora Ltd.
26 * Youness Alaoui, Collabora Ltd.
29 * Alternatively, the contents of this file may be used under the terms of the
30 * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
31 * case the provisions of LGPL are applicable instead of those above. If you
32 * wish to allow use of your version of this file only under the terms of the
33 * LGPL and not to allow others to use your version of this file under the
34 * MPL, indicate your decision by deleting the provisions above and replace
35 * them with the notice and other provisions required by the LGPL. If you do
36 * not delete the provisions above, a recipient may use your version of this
37 * file under either the MPL or the LGPL.
40 #ifndef __LIBNICE_CANDIDATE_H__
41 #define __LIBNICE_CANDIDATE_H__
44 #include <glib-object.h>
49 * @short_description: ICE candidate representation
50 * @see_also: #NiceAddress
53 * A representation of an ICE candidate. Make sure you read the ICE drafts[1] to
54 * understand correctly the concept of ICE candidates.
56 * [1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/
62 /* Constants for determining candidate priorities */
63 #define NICE_CANDIDATE_TYPE_PREF_HOST 120
64 #define NICE_CANDIDATE_TYPE_PREF_PEER_REFLEXIVE 110
65 #define NICE_CANDIDATE_TYPE_PREF_NAT_ASSISTED 105
66 #define NICE_CANDIDATE_TYPE_PREF_SERVER_REFLEXIVE 100
67 #define NICE_CANDIDATE_TYPE_PREF_RELAYED_UDP 30
68 #define NICE_CANDIDATE_TYPE_PREF_RELAYED 20
70 /* Priority preference constants for MS-ICE compatibility */
71 #define NICE_CANDIDATE_TRANSPORT_MS_PREF_UDP 15
72 #define NICE_CANDIDATE_TRANSPORT_MS_PREF_TCP 6
73 #define NICE_CANDIDATE_DIRECTION_MS_PREF_PASSIVE 2
74 #define NICE_CANDIDATE_DIRECTION_MS_PREF_ACTIVE 5
76 /* Max foundation size '1*32ice-char' plus terminating NULL, ICE ID-19 */
78 * NICE_CANDIDATE_MAX_FOUNDATION:
80 * The maximum size a candidate foundation can have.
82 #define NICE_CANDIDATE_MAX_FOUNDATION (32+1)
85 * NICE_CANDIDATE_MAX_TURN_SERVERS
87 * The maximum number of turns servers.
89 #define NICE_CANDIDATE_MAX_TURN_SERVERS 8
92 * NICE_CANDIDATE_MAX_LOCAL_ADDRESSES
94 * The maximum number of local addresses. The constraint is that the
95 * maximum number of local addresses and number of turn servers must
96 * fit on 9 bits, to ensure candidate priority uniqueness. See also
97 * @NICE_CANDIDATE_MAX_TURN_SERVERS. We choose 6 bits for the number of
98 * local addresses, and 3 bits for the number of turn servers.
100 #define NICE_CANDIDATE_MAX_LOCAL_ADDRESSES 64
104 * @NICE_CANDIDATE_TYPE_HOST: A host candidate
105 * @NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE: A server reflexive candidate
106 * @NICE_CANDIDATE_TYPE_PEER_REFLEXIVE: A peer reflexive candidate
107 * @NICE_CANDIDATE_TYPE_RELAYED: A relay candidate
109 * An enum represneting the type of a candidate
113 NICE_CANDIDATE_TYPE_HOST,
114 NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE,
115 NICE_CANDIDATE_TYPE_PEER_REFLEXIVE,
116 NICE_CANDIDATE_TYPE_RELAYED,
120 * NiceCandidateTransport:
121 * @NICE_CANDIDATE_TRANSPORT_UDP: UDP transport
122 * @NICE_CANDIDATE_TRANSPORT_TCP_ACTIVE: TCP Active transport
123 * @NICE_CANDIDATE_TRANSPORT_TCP_PASSIVE: TCP Passive transport
124 * @NICE_CANDIDATE_TRANSPORT_TCP_SO: TCP Simultaneous-Open transport
126 * An enum representing the type of transport to use
130 NICE_CANDIDATE_TRANSPORT_UDP,
131 NICE_CANDIDATE_TRANSPORT_TCP_ACTIVE,
132 NICE_CANDIDATE_TRANSPORT_TCP_PASSIVE,
133 NICE_CANDIDATE_TRANSPORT_TCP_SO,
134 } NiceCandidateTransport;
138 * @NICE_RELAY_TYPE_TURN_UDP: A TURN relay using UDP
139 * @NICE_RELAY_TYPE_TURN_TCP: A TURN relay using TCP
140 * @NICE_RELAY_TYPE_TURN_TLS: A TURN relay using TLS over TCP
142 * An enum representing the type of relay to use
145 NICE_RELAY_TYPE_TURN_UDP,
146 NICE_RELAY_TYPE_TURN_TCP,
147 NICE_RELAY_TYPE_TURN_TLS
151 typedef struct _NiceCandidate NiceCandidate;
153 typedef struct _TurnServer TurnServer;
157 * @ref_count: Reference count for the structure.
158 * @server: The #NiceAddress of the TURN server
159 * @username: The TURN username
160 * @password: The TURN password
161 * @decoded_username: The base64 decoded TURN username
162 * @decoded_password: The base64 decoded TURN password
163 * @decoded_username_len: The length of @decoded_username
164 * @decoded_password_len: The length of @decoded_password
165 * @type: The #NiceRelayType of the server
166 * @preference: A unique identifier used to compute priority
168 * A structure to store the TURN relay settings
177 guint8 *decoded_username;
178 guint8 *decoded_password;
179 gsize decoded_username_len;
180 gsize decoded_password_len;
187 * @type: The type of candidate
188 * @transport: The transport being used for the candidate
189 * @addr: The #NiceAddress of the candidate
190 * @base_addr: The #NiceAddress of the base address used by the candidate
191 * @priority: The priority of the candidate <emphasis> see note </emphasis>
192 * @stream_id: The ID of the stream to which belongs the candidate
193 * @component_id: The ID of the component to which belongs the candidate
194 * @foundation: The foundation of the candidate
195 * @username: The candidate-specific username to use (overrides the one set
196 * by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())
197 * @password: The candidate-specific password to use (overrides the one set
198 * by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())
199 * @turn: The #TurnServer settings if the candidate is
200 * of type %NICE_CANDIDATE_TYPE_RELAYED
201 * @sockptr: The underlying socket
202 * @keepalive_next_tick: The timestamp for the next keepalive
204 * A structure to represent an ICE candidate
207 The @priority is an integer as specified in the ICE draft 19. If you are
208 using the MSN or the GOOGLE compatibility mode (which are based on ICE
209 draft 6, which uses a floating point qvalue as priority), then the @priority
210 value will represent the qvalue multiplied by 1000.
214 struct _NiceCandidate
216 NiceCandidateType type;
217 NiceCandidateTransport transport;
219 NiceAddress base_addr;
223 gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];
224 gchar *username; /* pointer to a nul-terminated username string */
225 gchar *password; /* pointer to a nul-terminated password string */
228 guint64 keepalive_next_tick; /* next tick timestamp */
232 * nice_candidate_new:
233 * @type: The #NiceCandidateType of the candidate to create
235 * Creates a new candidate. Must be freed with nice_candidate_free()
237 * Returns: A new #NiceCandidate
240 nice_candidate_new (NiceCandidateType type);
243 * nice_candidate_free:
244 * @candidate: The candidate to free
246 * Frees a #NiceCandidate
249 nice_candidate_free (NiceCandidate *candidate);
252 * nice_candidate_copy:
253 * @candidate: The candidate to copy
255 * Makes a copy of a #NiceCandidate
257 * Returns: A new #NiceCandidate, a copy of @candidate
260 nice_candidate_copy (const NiceCandidate *candidate);
263 * nice_candidate_equal_target:
264 * @candidate1: A candidate
265 * @candidate2: A candidate
267 * Verifies that the candidates point to the same place, meaning they have
268 * the same transport and the same address. It ignores all other aspects.
270 * Returns: %TRUE if the candidates point to the same place
275 nice_candidate_equal_target (const NiceCandidate *candidate1,
276 const NiceCandidate *candidate2);
278 GType nice_candidate_get_type (void);
281 * NICE_TYPE_CANDIDATE:
283 * A boxed type for a #NiceCandidate.
285 #define NICE_TYPE_CANDIDATE nice_candidate_get_type ()
289 #endif /* __LIBNICE_CANDIDATE_H__ */