agent/address.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  *   Youness Alaoui, Collabora Ltd.
  26  *   Dafydd Harries, Collabora Ltd.
  27  *   Kai Vehmanen
  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_ADDRESS_H__
  41 #define __LIBNICE_ADDRESS_H__
  42
  43 /**
  44  * SECTION:address
  45  * @short_description: IP address convenience library
  46  * @stability: Stable
  47  *
  48  * The #NiceAddress structure will allow you to easily set/get and modify an IPv4
  49  * or IPv6 address in order to communicate with the #NiceAgent.
  50  */
  51
  52
  53 #include <glib.h>
  54
  55 #ifdef G_OS_WIN32
  56 #include <winsock2.h>
  57 #include <ws2tcpip.h>
  58 #else
  59 #include <sys/types.h>
  60 #include <sys/socket.h>
  61 #include <netinet/in.h>
  62 #include <arpa/inet.h>
  63 #endif
  64
  65 G_BEGIN_DECLS
  66
  67
  68 /**
  69  * NiceAddress:
  70  *
  71  * The #NiceAddress structure that represents an IPv4 or IPv6 address.
  72  */
  73 struct _NiceAddress
  74 {
  75   union
  76   {
  77     struct sockaddr     addr;
  78     struct sockaddr_in  ip4;
  79     struct sockaddr_in6 ip6;
  80   } s;
  81 };
  82
  83
  84 /**
  85  * NICE_ADDRESS_STRING_LEN:
  86  *
  87  * The maximum string length representation of an address.
  88  * When using nice_address_to_string() make sure the string has a size of
  89  * at least %NICE_ADDRESS_STRING_LEN
  90  */
  91 #define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
  92
  93 typedef struct _NiceAddress NiceAddress;
  94
  95
  96 /**
  97  * nice_address_init:
  98  * @addr: The #NiceAddress to init
  99  *
 100  * Initialize a #NiceAddress into an undefined address
 101  */
 102 void
 103 nice_address_init (NiceAddress *addr);
 104
 105 /**
 106  * nice_address_new:
 107  *
 108  * Create a new #NiceAddress with undefined address
 109  * You must free it with nice_address_free()
 110  *
 111  * Returns: The new #NiceAddress
 112  */
 113 NiceAddress *
 114 nice_address_new (void);
 115
 116 /**
 117  * nice_address_free:
 118  * @addr: The #NiceAddress to free
 119  *
 120  * Frees a #NiceAddress created with nice_address_new() or nice_address_dup()
 121  */
 122 void
 123 nice_address_free (NiceAddress *addr);
 124
 125 /**
 126  * nice_address_dup:
 127  * @addr: The #NiceAddress to dup
 128  *
 129  * Creates a new #NiceAddress with the same address as @addr
 130  *
 131  * Returns: The new #NiceAddress
 132  */
 133 NiceAddress *
 134 nice_address_dup (const NiceAddress *addr);
 135
 136
 137 /**
 138  * nice_address_set_ipv4:
 139  * @addr: The #NiceAddress to modify
 140  * @addr_ipv4: The IPv4 address
 141  *
 142  * Set @addr to an IPv4 address using the data from @addr_ipv4
 143  *
 144  <note>
 145   <para>
 146    This function will reset the port to 0, so make sure you call it before
 147    nice_address_set_port()
 148   </para>
 149  </note>
 150  */
 151 void
 152 nice_address_set_ipv4 (NiceAddress *addr, guint32 addr_ipv4);
 153
 154
 155 /**
 156  * nice_address_set_ipv6:
 157  * @addr: The #NiceAddress to modify
 158  * @addr_ipv6: The IPv6 address
 159  *
 160  * Set @addr to an IPv6 address using the data from @addr_ipv6
 161  *
 162  <note>
 163   <para>
 164    This function will reset the port to 0, so make sure you call it before
 165    nice_address_set_port()
 166   </para>
 167  </note>
 168  */
 169 void
 170 nice_address_set_ipv6 (NiceAddress *addr, const guchar *addr_ipv6);
 171
 172
 173 /**
 174  * nice_address_set_port:
 175  * @addr: The #NiceAddress to modify
 176  * @port: The port to set
 177  *
 178  * Set the port of @addr to @port
 179  */
 180 void
 181 nice_address_set_port (NiceAddress *addr, guint port);
 182
 183 /**
 184  * nice_address_get_port:
 185  * @addr: The #NiceAddress to query
 186  *
 187  * Retreive the port of @addr
 188  *
 189  * Returns: The port of @addr
 190  */
 191 guint
 192 nice_address_get_port (const NiceAddress *addr);
 193
 194 /**
 195  * nice_address_set_from_string:
 196  * @addr: The #NiceAddress to modify
 197  * @str: The string to set
 198  *
 199  * Sets an IPv4 or IPv6 address from the string @str
 200  *
 201  * Returns: %TRUE if success, %FALSE on error
 202  */
 203 gboolean
 204 nice_address_set_from_string (NiceAddress *addr, const gchar *str);
 205
 206 /**
 207  * nice_address_set_from_sockaddr:
 208  * @addr: The #NiceAddress to modify
 209  * @sin: The sockaddr to set
 210  *
 211  * Sets an IPv4 or IPv6 address from the sockaddr structure @sin
 212  *
 213  */
 214 void
 215 nice_address_set_from_sockaddr (NiceAddress *addr, const struct sockaddr *sin);
 216
 217
 218 /**
 219  * nice_address_copy_to_sockaddr:
 220  * @addr: The #NiceAddress to query
 221  * @sin: The sockaddr to fill
 222  *
 223  * Fills the sockaddr structure @sin with the address contained in @addr
 224  *
 225  */
 226 void
 227 nice_address_copy_to_sockaddr (const NiceAddress *addr, struct sockaddr *sin);
 228
 229 /**
 230  * nice_address_equal:
 231  * @a: First #NiceAddress to compare
 232  * @b: Second #NiceAddress to compare
 233  *
 234  * Compares two #NiceAddress structures to see if they contain the same address
 235  * and the same port.
 236  *
 237  * Returns: %TRUE if @a and @b are the same address, %FALSE if they are different
 238  */
 239 gboolean
 240 nice_address_equal (const NiceAddress *a, const NiceAddress *b);
 241
 242 /**
 243  * nice_address_equal_no_port:
 244  * @a: First #NiceAddress to compare
 245  * @b: Second #NiceAddress to compare
 246  *
 247  * Compares two #NiceAddress structures to see if they contain the same address,
 248  * ignoring the port.
 249  *
 250  * Returns: %TRUE if @a and @b are the same address, %FALSE if they
 251  * are different
 252  *
 253  * Since: 0.1.8
 254  */
 255 gboolean
 256 nice_address_equal_no_port (const NiceAddress *a, const NiceAddress *b);
 257
 258 /**
 259  * nice_address_to_string:
 260  * @addr: The #NiceAddress to query
 261  * @dst: The string to fill
 262  *
 263  * Transforms the address @addr into a human readable string
 264  *
 265  */
 266 void
 267 nice_address_to_string (const NiceAddress *addr, gchar *dst);
 268
 269 /**
 270  * nice_address_is_private:
 271  * @addr: The #NiceAddress to query
 272  *
 273  * Verifies if the address in @addr is a private address or not
 274  *
 275  * Returns: %TRUE if @addr is a private address, %FALSE otherwise
 276  */
 277 gboolean
 278 nice_address_is_private (const NiceAddress *addr);
 279
 280 /**
 281  * nice_address_is_valid:
 282  * @addr: The #NiceAddress to query
 283  *
 284  * Validate whether the #NiceAddress @addr is a valid IPv4 or IPv6 address
 285  *
 286  * Returns: %TRUE if @addr is valid, %FALSE otherwise
 287  */
 288 G_GNUC_WARN_UNUSED_RESULT
 289 gboolean
 290 nice_address_is_valid (const NiceAddress *addr);
 291
 292 /**
 293  * nice_address_ip_version:
 294  * @addr: The #NiceAddress to query
 295  *
 296  * Returns the IP version of the address
 297  *
 298  * Returns: 4 for IPv4, 6 for IPv6 and 0 for undefined address
 299  */
 300 G_GNUC_WARN_UNUSED_RESULT
 301 int
 302 nice_address_ip_version (const NiceAddress *addr);
 303
 304 G_END_DECLS
 305
 306 #endif /* __LIBNICE_ADDRESS_H__ */
 307