agent/candidate.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2006-2009 Collabora Ltd.
   5  *  Contact: Youness Alaoui
   6  * (C) 2006-2009 Nokia Corporation. All rights reserved.
   7  *  Contact: Kai Vehmanen
   8  *
   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/
  13  *
  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
  17  * License.
  18  *
  19  * The Original Code is the Nice GLib ICE library.
  20  *
  21  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  22  * Corporation. All Rights Reserved.
  23  *
  24  * Contributors:
  25  *   Dafydd Harries, Collabora Ltd.
  26  *   Youness Alaoui, Collabora Ltd.
  27  *   Kai Vehmanen, Nokia
  28  *
  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.
  38  */
  39
  40 #ifndef __LIBNICE_CANDIDATE_H__
  41 #define __LIBNICE_CANDIDATE_H__
  42
  43 #include <glib.h>
  44 #include <glib-object.h>
  45
  46
  47 /**
  48  * SECTION:candidate
  49  * @short_description: ICE candidate representation
  50  * @see_also: #NiceAddress
  51  * @stability: Stable
  52  *
  53  * A representation of an ICE candidate. Make sure you read the ICE drafts[1] to
  54  * understand correctly the concept of ICE candidates.
  55  *
  56  * [1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/
  57  */
  58
  59
  60 G_BEGIN_DECLS
  61
  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
  69
  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
  75
  76 /* Max foundation size '1*32ice-char' plus terminating NULL, ICE ID-19  */
  77 /**
  78  * NICE_CANDIDATE_MAX_FOUNDATION:
  79  *
  80  * The maximum size a candidate foundation can have.
  81  */
  82 #define NICE_CANDIDATE_MAX_FOUNDATION                (32+1)
  83
  84 /**
  85  * NICE_CANDIDATE_MAX_TURN_SERVERS
  86  *
  87  * The maximum number of turns servers.
  88  */
  89 #define NICE_CANDIDATE_MAX_TURN_SERVERS              8
  90
  91 /**
  92  * NICE_CANDIDATE_MAX_LOCAL_ADDRESSES
  93  *
  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.
  99  */
 100 #define NICE_CANDIDATE_MAX_LOCAL_ADDRESSES           64
 101
 102 /**
 103  * NiceCandidateType:
 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
 108  *
 109  * An enum represneting the type of a candidate
 110  */
 111 typedef enum
 112 {
 113   NICE_CANDIDATE_TYPE_HOST,
 114   NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE,
 115   NICE_CANDIDATE_TYPE_PEER_REFLEXIVE,
 116   NICE_CANDIDATE_TYPE_RELAYED,
 117 } NiceCandidateType;
 118
 119 /**
 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
 125  *
 126  * An enum representing the type of transport to use
 127  */
 128 typedef enum
 129 {
 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;
 135
 136 /**
 137  * NiceRelayType:
 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
 141  *
 142  * An enum representing the type of relay to use
 143  */
 144 typedef enum {
 145   NICE_RELAY_TYPE_TURN_UDP,
 146   NICE_RELAY_TYPE_TURN_TCP,
 147   NICE_RELAY_TYPE_TURN_TLS
 148 } NiceRelayType;
 149
 150
 151 typedef struct _NiceCandidate NiceCandidate;
 152
 153 typedef struct _TurnServer TurnServer;
 154
 155 /**
 156  * 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
 167  *
 168  * A structure to store the TURN relay settings
 169  */
 170 struct _TurnServer
 171 {
 172   gint ref_count;
 173
 174   NiceAddress server;
 175   gchar *username;
 176   gchar *password;
 177   guint8 *decoded_username;
 178   guint8 *decoded_password;
 179   gsize decoded_username_len;
 180   gsize decoded_password_len;
 181   NiceRelayType type;
 182   guint preference;
 183 };
 184
 185 /**
 186  * NiceCandidate:
 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
 203  *
 204  * A structure to represent an ICE candidate
 205  <note>
 206    <para>
 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.
 211    </para>
 212  </note>
 213  */
 214 struct _NiceCandidate
 215 {
 216   NiceCandidateType type;
 217   NiceCandidateTransport transport;
 218   NiceAddress addr;
 219   NiceAddress base_addr;
 220   guint32 priority;
 221   guint stream_id;
 222   guint component_id;
 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 */
 226   TurnServer *turn;
 227   gpointer sockptr;
 228   guint64 keepalive_next_tick; /* next tick timestamp */
 229 };
 230
 231 /**
 232  * nice_candidate_new:
 233  * @type: The #NiceCandidateType of the candidate to create
 234  *
 235  * Creates a new candidate. Must be freed with nice_candidate_free()
 236  *
 237  * Returns: A new #NiceCandidate
 238  */
 239 NiceCandidate *
 240 nice_candidate_new (NiceCandidateType type);
 241
 242 /**
 243  * nice_candidate_free:
 244  * @candidate: The candidate to free
 245  *
 246  * Frees a #NiceCandidate
 247  */
 248 void
 249 nice_candidate_free (NiceCandidate *candidate);
 250
 251 /**
 252  * nice_candidate_copy:
 253  * @candidate: The candidate to copy
 254  *
 255  * Makes a copy of a #NiceCandidate
 256  *
 257  * Returns: A new #NiceCandidate, a copy of @candidate
 258  */
 259 NiceCandidate *
 260 nice_candidate_copy (const NiceCandidate *candidate);
 261
 262 /**
 263  * nice_candidate_equal_target:
 264  * @candidate1: A candidate
 265  * @candidate2: A candidate
 266  *
 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.
 269  *
 270  * Returns: %TRUE if the candidates point to the same place
 271  *
 272  * Since: 0.1.15
 273  */
 274 gboolean
 275 nice_candidate_equal_target (const NiceCandidate *candidate1,
 276     const NiceCandidate *candidate2);
 277
 278   GType nice_candidate_get_type (void);
 279
 280 /**
 281  * NICE_TYPE_CANDIDATE:
 282  *
 283  * A boxed type for a #NiceCandidate.
 284  */
 285 #define NICE_TYPE_CANDIDATE nice_candidate_get_type ()
 286
 287 G_END_DECLS
 288
 289 #endif /* __LIBNICE_CANDIDATE_H__ */
 290