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 _CANDIDATE_H
  41 #define _CANDIDATE_H
  42
  43
  44 /**
  45  * SECTION:candidate
  46  * @short_description: ICE candidate representation
  47  * @see_also: #NiceAddress
  48  * @stability: Stable
  49  *
  50  * A representation of an ICE candidate. Make sure you read the ICE drafts[1] to
  51  * understand correctly the concept of ICE candidates.
  52  *
  53  * [1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/
  54  */
  55
  56
  57 G_BEGIN_DECLS
  58
  59
  60 #define NICE_CANDIDATE_TYPE_PREF_HOST                 120
  61 #define NICE_CANDIDATE_TYPE_PREF_PEER_REFLEXIVE       110
  62 #define NICE_CANDIDATE_TYPE_PREF_SERVER_REFLEXIVE     100
  63 #define NICE_CANDIDATE_TYPE_PREF_RELAYED               60
  64
  65 /* Max foundation size '1*32ice-char' plus terminating NULL, ICE ID-19  */
  66 /**
  67  * NICE_CANDIDATE_MAX_FOUNDATION:
  68  *
  69  * The maximum size a candidate foundation can have.
  70  */
  71 #define NICE_CANDIDATE_MAX_FOUNDATION                32+1
  72
  73
  74 /**
  75  * NiceCandidateType:
  76  * @NICE_CANDIDATE_TYPE_HOST: A host candidate
  77  * @NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE: A server reflexive candidate
  78  * @NICE_CANDIDATE_TYPE_PEER_REFLEXIVE: A peer reflexive candidate
  79  * @NICE_CANDIDATE_TYPE_RELAYED: A relay candidate
  80  *
  81  * An enum represneting the type of a candidate
  82  */
  83 typedef enum
  84 {
  85   NICE_CANDIDATE_TYPE_HOST,
  86   NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE,
  87   NICE_CANDIDATE_TYPE_PEER_REFLEXIVE,
  88   NICE_CANDIDATE_TYPE_RELAYED,
  89 } NiceCandidateType;
  90
  91 /**
  92  * NiceCandidateTransport:
  93  * @NICE_CANDIDATE_TRANSPORT_UDP: UDP transport
  94  *
  95  * An enum representing the type of transport to use
  96  */
  97 typedef enum
  98 {
  99   NICE_CANDIDATE_TRANSPORT_UDP,
 100 } NiceCandidateTransport;
 101
 102 /**
 103  * NiceRelayType:
 104  * @NICE_RELAY_TYPE_TURN_UDP: A TURN relay using UDP
 105  * @NICE_RELAY_TYPE_TURN_TCP: A TURN relay using TCP
 106  * @NICE_RELAY_TYPE_TURN_TLS: A TURN relay using TLS over TCP
 107  *
 108  * An enum representing the type of relay to use
 109  */
 110 typedef enum {
 111   NICE_RELAY_TYPE_TURN_UDP,
 112   NICE_RELAY_TYPE_TURN_TCP,
 113   NICE_RELAY_TYPE_TURN_TLS
 114 } NiceRelayType;
 115
 116
 117 typedef struct _NiceCandidate NiceCandidate;
 118
 119 typedef struct _TurnServer TurnServer;
 120
 121 /**
 122  * TurnServer:
 123  * @server: The #NiceAddress of the TURN server
 124  * @username: The TURN username
 125  * @password: The TURN password
 126  * @type: The #NiceRelayType of the server
 127  *
 128  * A structure to store the TURN relay settings
 129  */
 130 struct _TurnServer
 131 {
 132   NiceAddress server;       /**< TURN server address */
 133   gchar *username;           /**< TURN username */
 134   gchar *password;           /**< TURN password */
 135   NiceRelayType type;             /**< TURN type */
 136 };
 137
 138 /**
 139  * NiceCandidate:
 140  * @type: The type of candidate
 141  * @transport: The transport being used for the candidate
 142  * @addr: The #NiceAddress of the candidate
 143  * @base_addr: The #NiceAddress of the base address used by the candidate
 144  * @priority: The priority of the candidate <emphasis> see note </emphasis>
 145  * @stream_id: The ID of the stream to which belongs the candidate
 146  * @component_id: The ID of the component to which belongs the candidate
 147  * @foundation: The foundation of the candidate
 148  * @username: The candidate-specific username to use (overrides the one set
 149  * by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())
 150  * @password: The candidate-specific password to use (overrides the one set
 151  * by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())
 152  * @turn: The #TurnServer settings if the candidate is
 153  * of type %NICE_CANDIDATE_TYPE_RELAYED
 154  * @sockptr: The underlying socket
 155  *
 156  * A structure to represent an ICE candidate
 157  <note>
 158    <para>
 159    The @priority is an integer as specified in the ICE draft 19. If you are
 160    using the MSN or the GOOGLE compatibility mode (which are based on ICE
 161    draft 6, which uses a floating point qvalue as priority), then the @priority
 162    value will represent the qvalue multiplied by 1000.
 163    </para>
 164  </note>
 165  */
 166 struct _NiceCandidate
 167 {
 168   NiceCandidateType type;
 169   NiceCandidateTransport transport;
 170   NiceAddress addr;
 171   NiceAddress base_addr;
 172   guint32 priority;
 173   guint stream_id;
 174   guint component_id;
 175   gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];
 176   gchar *username;        /* pointer to a NULL-terminated username string */
 177   gchar *password;        /* pointer to a NULL-terminated password string */
 178   TurnServer *turn;
 179   gpointer sockptr;
 180 };
 181
 182 /**
 183  * nice_candidate_new:
 184  * @type: The #NiceCandidateType of the candidate to create
 185  *
 186  * Creates a new candidate. Must be freed with nice_candidate_free()
 187  *
 188  * Returns: A new #NiceCandidate
 189  */
 190 NiceCandidate *
 191 nice_candidate_new (NiceCandidateType type);
 192
 193 /**
 194  * nice_candidate_free:
 195  * @candidate: The candidate to free
 196  *
 197  * Frees a #NiceCandidate
 198  */
 199 void
 200 nice_candidate_free (NiceCandidate *candidate);
 201
 202 /**
 203  * nice_candidate_copy:
 204  * @candidate: The candidate to copy
 205  *
 206  * Makes a copy of a #NiceCandidate
 207  *
 208  * Returns: A new #NiceCandidate, a copy of @candidate
 209  */
 210 NiceCandidate *
 211 nice_candidate_copy (const NiceCandidate *candidate);
 212
 213
 214 guint32
 215 nice_candidate_jingle_priority (NiceCandidate *candidate);
 216
 217 guint32
 218 nice_candidate_msn_priority (NiceCandidate *candidate);
 219
 220 guint32
 221 nice_candidate_ice_priority_full (guint type_pref, guint local_pref,
 222     guint component_id);
 223
 224 guint32
 225 nice_candidate_ice_priority (const NiceCandidate *candidate);
 226
 227 guint64
 228 nice_candidate_pair_priority (guint32 o_prio, guint32 a_prio);
 229
 230
 231 G_END_DECLS
 232
 233 #endif /* _CANDIDATE_H */
 234