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 _ADDRESS_H
  41 #define _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  * @addr: Generic sockaddr address
  71  * @ip4: IPv4 sockaddr address
  72  * @ip6: IPv6 sockaddr address
  73  *
  74  * The #NiceAddress structure that represents an IPv4 or IPv6 address.
  75  */
  76 struct _NiceAddress
  77 {
  78   union
  79   {
  80     struct sockaddr     addr;
  81     struct sockaddr_in  ip4;
  82     struct sockaddr_in6 ip6;
  83   } s;
  84 };
  85
  86
  87 /**
  88  * NICE_ADDRESS_STRING_LEN:
  89  *
  90  * The maximum string length representation of an address.
  91  * When using nice_address_to_string() make sure the string has a size of
  92  * at least %NICE_ADDRESS_STRING_LEN
  93  */
  94 #define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
  95
  96 typedef struct _NiceAddress NiceAddress;
  97
  98
  99 /**
 100  * nice_address_init:
 101  * @addr: The #NiceAddress to init
 102  *
 103  * Initialize a #NiceAddress into an undefined address
 104  */
 105 void
 106 nice_address_init (NiceAddress *addr);
 107
 108 /**
 109  * nice_address_new:
 110  *
 111  * Create a new #NiceAddress with undefined address
 112  * You must free it with nice_address_free()
 113  *
 114  * Returns: The new #NiceAddress
 115  */
 116 NiceAddress *
 117 nice_address_new (void);
 118
 119 /**
 120  * nice_address_free:
 121  * @addr: The #NiceAddress to free
 122  *
 123  * Frees a #NiceAddress created with nice_address_new() or nice_address_dup()
 124  */
 125 void
 126 nice_address_free (NiceAddress *addr);
 127
 128 /**
 129  * nice_address_dup:
 130  * @addr: The #NiceAddress to dup
 131  *
 132  * Creates a new #NiceAddress with the same address as @addr
 133  *
 134  * Returns: The new #NiceAddress
 135  */
 136 NiceAddress *
 137 nice_address_dup (const NiceAddress *addr);
 138
 139
 140 /**
 141  * nice_address_set_ipv4:
 142  * @addr: The #NiceAddress to modify
 143  * @addr_ipv4: The IPv4 address
 144  *
 145  * Set @addr to an IPv4 address using the data from @addr_ipv4
 146  *
 147  <note>
 148   <para>
 149    This function will reset the port to 0, so make sure you call it before
 150    nice_address_set_port()
 151   </para>
 152  </note>
 153  */
 154 void
 155 nice_address_set_ipv4 (NiceAddress *addr, guint32 addr_ipv4);
 156
 157
 158 /**
 159  * nice_address_set_ipv6:
 160  * @addr: The #NiceAddress to modify
 161  * @addr_ipv6: The IPv6 address
 162  *
 163  * Set @addr to an IPv6 address using the data from @addr_ipv6
 164  *
 165  <note>
 166   <para>
 167    This function will reset the port to 0, so make sure you call it before
 168    nice_address_set_port()
 169   </para>
 170  </note>
 171  */
 172 void
 173 nice_address_set_ipv6 (NiceAddress *addr, const guchar *addr_ipv6);
 174
 175
 176 /**
 177  * nice_address_set_port:
 178  * @addr: The #NiceAddress to modify
 179  * @port: The port to set
 180  *
 181  * Set the port of @addr to @port
 182  */
 183 void
 184 nice_address_set_port (NiceAddress *addr, guint port);
 185
 186 /**
 187  * nice_address_get_port:
 188  * @addr: The #NiceAddress to query
 189  *
 190  * Retreive the port of @addr
 191  *
 192  * Returns: The port of @addr
 193  */
 194 guint
 195 nice_address_get_port (const NiceAddress *addr);
 196
 197 /**
 198  * nice_address_set_from_string:
 199  * @addr: The #NiceAddress to modify
 200  * @str: The string to set
 201  *
 202  * Sets an IPv4 or IPv6 address from the string @str
 203  *
 204  * Returns: %TRUE if success, %FALSE on error
 205  */
 206 gboolean
 207 nice_address_set_from_string (NiceAddress *addr, const gchar *str);
 208
 209 /**
 210  * nice_address_set_from_sockaddr:
 211  * @addr: The #NiceAddress to modify
 212  * @sin: The sockaddr to set
 213  *
 214  * Sets an IPv4 or IPv6 address from the sockaddr structure @sin
 215  *
 216  */
 217 void
 218 nice_address_set_from_sockaddr (NiceAddress *addr, const struct sockaddr *sin);
 219
 220
 221 /**
 222  * nice_address_copy_to_sockaddr:
 223  * @addr: The #NiceAddress to query
 224  * @sin: The sockaddr to fill
 225  *
 226  * Fills the sockaddr structure @sin with the address contained in @addr
 227  *
 228  */
 229 void
 230 nice_address_copy_to_sockaddr (const NiceAddress *addr, struct sockaddr *sin);
 231
 232 /**
 233  * nice_address_equal:
 234  * @a: First #NiceAddress to compare
 235  * @b: Second #NiceAddress to compare
 236  *
 237  * Compares two #NiceAddress structures to see if they contain the same address
 238  *
 239  * Returns: %TRUE if @a and @b are the same address, %FALSE if they are different
 240  */
 241 gboolean
 242 nice_address_equal (const NiceAddress *a, const NiceAddress *b);
 243
 244 /**
 245  * nice_address_to_string:
 246  * @addr: The #NiceAddress to query
 247  * @dst: The string to fill
 248  *
 249  * Transforms the address @addr into a human readable string
 250  *
 251  */
 252 void
 253 nice_address_to_string (const NiceAddress *addr, gchar *dst);
 254
 255 /**
 256  * nice_address_is_private:
 257  * @addr: The #NiceAddress to query
 258  *
 259  * Verifies if the address in @addr is a private address or not
 260  *
 261  * Returns: %TRUE if @addr is a private address, %FALSE otherwise
 262  */
 263 gboolean
 264 nice_address_is_private (const NiceAddress *addr);
 265
 266 /**
 267  * nice_address_is_valid:
 268  * @addr: The #NiceAddress to query
 269  *
 270  * Validate whether the #NiceAddress @addr is a valid IPv4 or IPv6 address
 271  *
 272  * Returns: %TRUE if @addr is valid, %FALSE otherwise
 273  */
 274 G_GNUC_WARN_UNUSED_RESULT
 275 gboolean
 276 nice_address_is_valid (const NiceAddress *addr);
 277
 278 G_END_DECLS
 279
 280 #endif /* _ADDRESS_H */
 281