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