gio/gsocketlistener.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2008 Christian Kellner, Samuel Cormier-Iijima
   4  * Copyright © 2009 codethink
   5  * Copyright © 2009 Red Hat, Inc
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  *
  22  * Authors: Christian Kellner <gicmo@gnome.org>
  23  *          Samuel Cormier-Iijima <sciyoshi@gmail.com>
  24  *          Ryan Lortie <desrt@desrt.ca>
  25  *          Alexander Larsson <alexl@redhat.com>
  26  */
  27
  28 #include "config.h"
  29 #include "gsocketlistener.h"
  30
  31 #include <gio/gtask.h>
  32 #include <gio/gcancellable.h>
  33 #include <gio/gsocketaddress.h>
  34 #include <gio/ginetaddress.h>
  35 #include <gio/gioerror.h>
  36 #include <gio/gsocket.h>
  37 #include <gio/gsocketconnection.h>
  38 #include <gio/ginetsocketaddress.h>
  39 #include "glibintl.h"
  40
  41
  42 /**
  43  * SECTION:gsocketlistener
  44  * @title: GSocketListener
  45  * @short_description: Helper for accepting network client connections
  46  * @include: gio/gio.h
  47  * @see_also: #GThreadedSocketService, #GSocketService.
  48  *
  49  * A #GSocketListener is an object that keeps track of a set
  50  * of server sockets and helps you accept sockets from any of the
  51  * socket, either sync or async.
  52  *
  53  * If you want to implement a network server, also look at #GSocketService
  54  * and #GThreadedSocketService which are subclass of #GSocketListener
  55  * that makes this even easier.
  56  *
  57  * Since: 2.22
  58  */
  59
  60 enum
  61 {
  62   PROP_0,
  63   PROP_LISTEN_BACKLOG
  64 };
  65
  66
  67 static GQuark source_quark = 0;
  68
  69 struct _GSocketListenerPrivate
  70 {
  71   GPtrArray           *sockets;
  72   GMainContext        *main_context;
  73   int                 listen_backlog;
  74   guint               closed : 1;
  75 };
  76
  77 G_DEFINE_TYPE_WITH_PRIVATE (GSocketListener, g_socket_listener, G_TYPE_OBJECT)
  78
  79 static void
  80 g_socket_listener_finalize (GObject *object)
  81 {
  82   GSocketListener *listener = G_SOCKET_LISTENER (object);
  83
  84   if (listener->priv->main_context)
  85     g_main_context_unref (listener->priv->main_context);
  86
  87   if (!listener->priv->closed)
  88     g_socket_listener_close (listener);
  89
  90   g_ptr_array_free (listener->priv->sockets, TRUE);
  91
  92   G_OBJECT_CLASS (g_socket_listener_parent_class)
  93     ->finalize (object);
  94 }
  95
  96 static void
  97 g_socket_listener_get_property (GObject    *object,
  98                                 guint       prop_id,
  99                                 GValue     *value,
 100                                 GParamSpec *pspec)
 101 {
 102   GSocketListener *listener = G_SOCKET_LISTENER (object);
 103
 104   switch (prop_id)
 105     {
 106       case PROP_LISTEN_BACKLOG:
 107         g_value_set_int (value, listener->priv->listen_backlog);
 108         break;
 109
 110       default:
 111         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 112     }
 113 }
 114
 115 static void
 116 g_socket_listener_set_property (GObject      *object,
 117                                 guint         prop_id,
 118                                 const GValue *value,
 119                                 GParamSpec   *pspec)
 120 {
 121   GSocketListener *listener = G_SOCKET_LISTENER (object);
 122
 123   switch (prop_id)
 124     {
 125       case PROP_LISTEN_BACKLOG:
 126         g_socket_listener_set_backlog (listener, g_value_get_int (value));
 127         break;
 128
 129       default:
 130         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 131     }
 132 }
 133
 134
 135 static void
 136 g_socket_listener_class_init (GSocketListenerClass *klass)
 137 {
 138   GObjectClass *gobject_class G_GNUC_UNUSED = G_OBJECT_CLASS (klass);
 139
 140   gobject_class->finalize = g_socket_listener_finalize;
 141   gobject_class->set_property = g_socket_listener_set_property;
 142   gobject_class->get_property = g_socket_listener_get_property;
 143   g_object_class_install_property (gobject_class, PROP_LISTEN_BACKLOG,
 144                                    g_param_spec_int ("listen-backlog",
 145                                                      P_("Listen backlog"),
 146                                                      P_("outstanding connections in the listen queue"),
 147                                                      0,
 148                                                      2000,
 149                                                      10,
 150                                                      G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 151
 152   source_quark = g_quark_from_static_string ("g-socket-listener-source");
 153 }
 154
 155 static void
 156 g_socket_listener_init (GSocketListener *listener)
 157 {
 158   listener->priv = g_socket_listener_get_instance_private (listener);
 159   listener->priv->sockets =
 160     g_ptr_array_new_with_free_func ((GDestroyNotify) g_object_unref);
 161   listener->priv->listen_backlog = 10;
 162 }
 163
 164 /**
 165  * g_socket_listener_new:
 166  *
 167  * Creates a new #GSocketListener with no sockets to listen for.
 168  * New listeners can be added with e.g. g_socket_listener_add_address()
 169  * or g_socket_listener_add_inet_port().
 170  *
 171  * Returns: a new #GSocketListener.
 172  *
 173  * Since: 2.22
 174  */
 175 GSocketListener *
 176 g_socket_listener_new (void)
 177 {
 178   return g_object_new (G_TYPE_SOCKET_LISTENER, NULL);
 179 }
 180
 181 static gboolean
 182 check_listener (GSocketListener *listener,
 183                 GError **error)
 184 {
 185   if (listener->priv->closed)
 186     {
 187       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
 188                            _("Listener is already closed"));
 189       return FALSE;
 190     }
 191
 192   return TRUE;
 193 }
 194
 195 /**
 196  * g_socket_listener_add_socket:
 197  * @listener: a #GSocketListener
 198  * @socket: a listening #GSocket
 199  * @source_object: (allow-none): Optional #GObject identifying this source
 200  * @error: #GError for error reporting, or %NULL to ignore.
 201  *
 202  * Adds @socket to the set of sockets that we try to accept
 203  * new clients from. The socket must be bound to a local
 204  * address and listened to.
 205  *
 206  * @source_object will be passed out in the various calls
 207  * to accept to identify this particular source, which is
 208  * useful if you're listening on multiple addresses and do
 209  * different things depending on what address is connected to.
 210  *
 211  * Returns: %TRUE on success, %FALSE on error.
 212  *
 213  * Since: 2.22
 214  */
 215 gboolean
 216 g_socket_listener_add_socket (GSocketListener  *listener,
 217                               GSocket          *socket,
 218                               GObject          *source_object,
 219                               GError          **error)
 220 {
 221   if (!check_listener (listener, error))
 222     return FALSE;
 223
 224   /* TODO: Check that socket it is bound & not closed? */
 225
 226   if (g_socket_is_closed (socket))
 227     {
 228       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
 229                            _("Added socket is closed"));
 230       return FALSE;
 231     }
 232
 233   g_object_ref (socket);
 234   g_ptr_array_add (listener->priv->sockets, socket);
 235
 236   if (source_object)
 237     g_object_set_qdata_full (G_OBJECT (socket), source_quark,
 238                              g_object_ref (source_object), g_object_unref);
 239
 240
 241   if (G_SOCKET_LISTENER_GET_CLASS (listener)->changed)
 242     G_SOCKET_LISTENER_GET_CLASS (listener)->changed (listener);
 243
 244   return TRUE;
 245 }
 246
 247 /**
 248  * g_socket_listener_add_address:
 249  * @listener: a #GSocketListener
 250  * @address: a #GSocketAddress
 251  * @type: a #GSocketType
 252  * @protocol: a #GSocketProtocol
 253  * @source_object: (allow-none): Optional #GObject identifying this source
 254  * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
 255  * @error: #GError for error reporting, or %NULL to ignore.
 256  *
 257  * Creates a socket of type @type and protocol @protocol, binds
 258  * it to @address and adds it to the set of sockets we're accepting
 259  * sockets from.
 260  *
 261  * Note that adding an IPv6 address, depending on the platform,
 262  * may or may not result in a listener that also accepts IPv4
 263  * connections.  For more deterministic behavior, see
 264  * g_socket_listener_add_inet_port().
 265  *
 266  * @source_object will be passed out in the various calls
 267  * to accept to identify this particular source, which is
 268  * useful if you're listening on multiple addresses and do
 269  * different things depending on what address is connected to.
 270  *
 271  * If successful and @effective_address is non-%NULL then it will
 272  * be set to the address that the binding actually occurred at.  This
 273  * is helpful for determining the port number that was used for when
 274  * requesting a binding to port 0 (ie: "any port").  This address, if
 275  * requested, belongs to the caller and must be freed.
 276  *
 277  * Returns: %TRUE on success, %FALSE on error.
 278  *
 279  * Since: 2.22
 280  */
 281 gboolean
 282 g_socket_listener_add_address (GSocketListener  *listener,
 283                                GSocketAddress   *address,
 284                                GSocketType       type,
 285                                GSocketProtocol   protocol,
 286                                GObject          *source_object,
 287                                GSocketAddress  **effective_address,
 288                                GError          **error)
 289 {
 290   GSocketAddress *local_address;
 291   GSocketFamily family;
 292   GSocket *socket;
 293
 294   if (!check_listener (listener, error))
 295     return FALSE;
 296
 297   family = g_socket_address_get_family (address);
 298   socket = g_socket_new (family, type, protocol, error);
 299   if (socket == NULL)
 300     return FALSE;
 301
 302   g_socket_set_listen_backlog (socket, listener->priv->listen_backlog);
 303
 304   if (!g_socket_bind (socket, address, TRUE, error) ||
 305       !g_socket_listen (socket, error))
 306     {
 307       g_object_unref (socket);
 308       return FALSE;
 309     }
 310
 311   local_address = NULL;
 312   if (effective_address)
 313     {
 314       local_address = g_socket_get_local_address (socket, error);
 315       if (local_address == NULL)
 316         {
 317           g_object_unref (socket);
 318           return FALSE;
 319         }
 320     }
 321
 322   if (!g_socket_listener_add_socket (listener, socket,
 323                                      source_object,
 324                                      error))
 325     {
 326       if (local_address)
 327         g_object_unref (local_address);
 328       g_object_unref (socket);
 329       return FALSE;
 330     }
 331
 332   if (effective_address)
 333     *effective_address = local_address;
 334
 335   g_object_unref (socket); /* add_socket refs this */
 336
 337   return TRUE;
 338 }
 339
 340 /**
 341  * g_socket_listener_add_inet_port:
 342  * @listener: a #GSocketListener
 343  * @port: an IP port number (non-zero)
 344  * @source_object: (allow-none): Optional #GObject identifying this source
 345  * @error: #GError for error reporting, or %NULL to ignore.
 346  *
 347  * Helper function for g_socket_listener_add_address() that
 348  * creates a TCP/IP socket listening on IPv4 and IPv6 (if
 349  * supported) on the specified port on all interfaces.
 350  *
 351  * @source_object will be passed out in the various calls
 352  * to accept to identify this particular source, which is
 353  * useful if you're listening on multiple addresses and do
 354  * different things depending on what address is connected to.
 355  *
 356  * Returns: %TRUE on success, %FALSE on error.
 357  *
 358  * Since: 2.22
 359  */
 360 gboolean
 361 g_socket_listener_add_inet_port (GSocketListener  *listener,
 362                                  guint16           port,
 363                                  GObject          *source_object,
 364                                  GError          **error)
 365 {
 366   gboolean need_ipv4_socket = TRUE;
 367   GSocket *socket4 = NULL;
 368   GSocket *socket6;
 369
 370   g_return_val_if_fail (listener != NULL, FALSE);
 371   g_return_val_if_fail (port != 0, FALSE);
 372
 373   if (!check_listener (listener, error))
 374     return FALSE;
 375
 376   /* first try to create an IPv6 socket */
 377   socket6 = g_socket_new (G_SOCKET_FAMILY_IPV6,
 378                           G_SOCKET_TYPE_STREAM,
 379                           G_SOCKET_PROTOCOL_DEFAULT,
 380                           NULL);
 381
 382   if (socket6 != NULL)
 383     /* IPv6 is supported on this platform, so if we fail now it is
 384      * a result of being unable to bind to our port.  Don't fail
 385      * silently as a result of this!
 386      */
 387     {
 388       GInetAddress *inet_address;
 389       GSocketAddress *address;
 390       gboolean result;
 391
 392       inet_address = g_inet_address_new_any (G_SOCKET_FAMILY_IPV6);
 393       address = g_inet_socket_address_new (inet_address, port);
 394       g_object_unref (inet_address);
 395
 396       g_socket_set_listen_backlog (socket6, listener->priv->listen_backlog);
 397
 398       result = g_socket_bind (socket6, address, TRUE, error) &&
 399                g_socket_listen (socket6, error);
 400
 401       g_object_unref (address);
 402
 403       if (!result)
 404         {
 405           g_object_unref (socket6);
 406
 407           return FALSE;
 408         }
 409
 410       if (source_object)
 411         g_object_set_qdata_full (G_OBJECT (socket6), source_quark,
 412                                  g_object_ref (source_object),
 413                                  g_object_unref);
 414
 415       /* If this socket already speaks IPv4 then we are done. */
 416       if (g_socket_speaks_ipv4 (socket6))
 417         need_ipv4_socket = FALSE;
 418     }
 419
 420   if (need_ipv4_socket)
 421     /* We are here for exactly one of the following reasons:
 422      *
 423      *   - our platform doesn't support IPv6
 424      *   - we successfully created an IPv6 socket but it's V6ONLY
 425      *
 426      * In either case, we need to go ahead and create an IPv4 socket
 427      * and fail the call if we can't bind to it.
 428      */
 429     {
 430       socket4 = g_socket_new (G_SOCKET_FAMILY_IPV4,
 431                               G_SOCKET_TYPE_STREAM,
 432                               G_SOCKET_PROTOCOL_DEFAULT,
 433                               error);
 434
 435       if (socket4 != NULL)
 436         /* IPv4 is supported on this platform, so if we fail now it is
 437          * a result of being unable to bind to our port.  Don't fail
 438          * silently as a result of this!
 439          */
 440         {
 441           GInetAddress *inet_address;
 442           GSocketAddress *address;
 443           gboolean result;
 444
 445           inet_address = g_inet_address_new_any (G_SOCKET_FAMILY_IPV4);
 446           address = g_inet_socket_address_new (inet_address, port);
 447           g_object_unref (inet_address);
 448
 449           g_socket_set_listen_backlog (socket4,
 450                                        listener->priv->listen_backlog);
 451
 452           result = g_socket_bind (socket4, address, TRUE, error) &&
 453                    g_socket_listen (socket4, error);
 454
 455           g_object_unref (address);
 456
 457           if (!result)
 458             {
 459               g_object_unref (socket4);
 460
 461               if (socket6 != NULL)
 462                 g_object_unref (socket6);
 463
 464               return FALSE;
 465             }
 466
 467           if (source_object)
 468             g_object_set_qdata_full (G_OBJECT (socket4), source_quark,
 469                                      g_object_ref (source_object),
 470                                      g_object_unref);
 471         }
 472       else
 473         /* Ok.  So IPv4 is not supported on this platform.  If we
 474          * succeeded at creating an IPv6 socket then that's OK, but
 475          * otherwise we need to tell the user we failed.
 476          */
 477         {
 478           if (socket6 != NULL)
 479             g_clear_error (error);
 480           else
 481             return FALSE;
 482         }
 483     }
 484
 485   g_assert (socket6 != NULL || socket4 != NULL);
 486
 487   if (socket6 != NULL)
 488     g_ptr_array_add (listener->priv->sockets, socket6);
 489
 490   if (socket4 != NULL)
 491     g_ptr_array_add (listener->priv->sockets, socket4);
 492
 493   if (G_SOCKET_LISTENER_GET_CLASS (listener)->changed)
 494     G_SOCKET_LISTENER_GET_CLASS (listener)->changed (listener);
 495
 496   return TRUE;
 497 }
 498
 499 static GList *
 500 add_sources (GSocketListener   *listener,
 501              GSocketSourceFunc  callback,
 502              gpointer           callback_data,
 503              GCancellable      *cancellable,
 504              GMainContext      *context)
 505 {
 506   GSocket *socket;
 507   GSource *source;
 508   GList *sources;
 509   int i;
 510
 511   sources = NULL;
 512   for (i = 0; i < listener->priv->sockets->len; i++)
 513     {
 514       socket = listener->priv->sockets->pdata[i];
 515
 516       source = g_socket_create_source (socket, G_IO_IN, cancellable);
 517       g_source_set_callback (source,
 518                              (GSourceFunc) callback,
 519                              callback_data, NULL);
 520       g_source_attach (source, context);
 521
 522       sources = g_list_prepend (sources, source);
 523     }
 524
 525   return sources;
 526 }
 527
 528 static void
 529 free_sources (GList *sources)
 530 {
 531   GSource *source;
 532   while (sources != NULL)
 533     {
 534       source = sources->data;
 535       sources = g_list_delete_link (sources, sources);
 536       g_source_destroy (source);
 537       g_source_unref (source);
 538     }
 539 }
 540
 541 struct AcceptData {
 542   GMainLoop *loop;
 543   GSocket *socket;
 544 };
 545
 546 static gboolean
 547 accept_callback (GSocket      *socket,
 548                  GIOCondition  condition,
 549                  gpointer      user_data)
 550 {
 551   struct AcceptData *data = user_data;
 552
 553   data->socket = socket;
 554   g_main_loop_quit (data->loop);
 555
 556   return TRUE;
 557 }
 558
 559 /**
 560  * g_socket_listener_accept_socket:
 561  * @listener: a #GSocketListener
 562  * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
 563  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 564  * @error: #GError for error reporting, or %NULL to ignore.
 565  *
 566  * Blocks waiting for a client to connect to any of the sockets added
 567  * to the listener. Returns the #GSocket that was accepted.
 568  *
 569  * If you want to accept the high-level #GSocketConnection, not a #GSocket,
 570  * which is often the case, then you should use g_socket_listener_accept()
 571  * instead.
 572  *
 573  * If @source_object is not %NULL it will be filled out with the source
 574  * object specified when the corresponding socket or address was added
 575  * to the listener.
 576  *
 577  * If @cancellable is not %NULL, then the operation can be cancelled by
 578  * triggering the cancellable object from another thread. If the operation
 579  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
 580  *
 581  * Returns: (transfer full): a #GSocket on success, %NULL on error.
 582  *
 583  * Since: 2.22
 584  */
 585 GSocket *
 586 g_socket_listener_accept_socket (GSocketListener  *listener,
 587                                  GObject         **source_object,
 588                                  GCancellable     *cancellable,
 589                                  GError          **error)
 590 {
 591   GSocket *accept_socket, *socket;
 592
 593   g_return_val_if_fail (G_IS_SOCKET_LISTENER (listener), NULL);
 594
 595   if (!check_listener (listener, error))
 596     return NULL;
 597
 598   if (listener->priv->sockets->len == 1)
 599     {
 600       accept_socket = listener->priv->sockets->pdata[0];
 601       if (!g_socket_condition_wait (accept_socket, G_IO_IN,
 602                                     cancellable, error))
 603         return NULL;
 604     }
 605   else
 606     {
 607       GList *sources;
 608       struct AcceptData data;
 609       GMainLoop *loop;
 610
 611       if (listener->priv->main_context == NULL)
 612         listener->priv->main_context = g_main_context_new ();
 613
 614       loop = g_main_loop_new (listener->priv->main_context, FALSE);
 615       data.loop = loop;
 616       sources = add_sources (listener,
 617                              accept_callback,
 618                              &data,
 619                              cancellable,
 620                              listener->priv->main_context);
 621       g_main_loop_run (loop);
 622       accept_socket = data.socket;
 623       free_sources (sources);
 624       g_main_loop_unref (loop);
 625     }
 626
 627   if (!(socket = g_socket_accept (accept_socket, cancellable, error)))
 628     return NULL;
 629
 630   if (source_object)
 631     *source_object = g_object_get_qdata (G_OBJECT (accept_socket), source_quark);
 632
 633   return socket;
 634 }
 635
 636 /**
 637  * g_socket_listener_accept:
 638  * @listener: a #GSocketListener
 639  * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
 640  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 641  * @error: #GError for error reporting, or %NULL to ignore.
 642  *
 643  * Blocks waiting for a client to connect to any of the sockets added
 644  * to the listener. Returns a #GSocketConnection for the socket that was
 645  * accepted.
 646  *
 647  * If @source_object is not %NULL it will be filled out with the source
 648  * object specified when the corresponding socket or address was added
 649  * to the listener.
 650  *
 651  * If @cancellable is not %NULL, then the operation can be cancelled by
 652  * triggering the cancellable object from another thread. If the operation
 653  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
 654  *
 655  * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
 656  *
 657  * Since: 2.22
 658  */
 659 GSocketConnection *
 660 g_socket_listener_accept (GSocketListener  *listener,
 661                           GObject         **source_object,
 662                           GCancellable     *cancellable,
 663                           GError          **error)
 664 {
 665   GSocketConnection *connection;
 666   GSocket *socket;
 667
 668   socket = g_socket_listener_accept_socket (listener,
 669                                             source_object,
 670                                             cancellable,
 671                                             error);
 672   if (socket == NULL)
 673     return NULL;
 674
 675   connection = g_socket_connection_factory_create_connection (socket);
 676   g_object_unref (socket);
 677
 678   return connection;
 679 }
 680
 681 static gboolean
 682 accept_ready (GSocket      *accept_socket,
 683               GIOCondition  condition,
 684               gpointer      user_data)
 685 {
 686   GTask *task = user_data;
 687   GError *error = NULL;
 688   GSocket *socket;
 689   GObject *source_object;
 690
 691   socket = g_socket_accept (accept_socket, g_task_get_cancellable (task), &error);
 692   if (socket)
 693     {
 694       source_object = g_object_get_qdata (G_OBJECT (accept_socket), source_quark);
 695       if (source_object)
 696         g_object_set_qdata_full (G_OBJECT (task),
 697                                  source_quark,
 698                                  g_object_ref (source_object), g_object_unref);
 699       g_task_return_pointer (task, socket, g_object_unref);
 700     }
 701   else
 702     {
 703       g_task_return_error (task, error);
 704     }
 705
 706   g_object_unref (task);
 707   return FALSE;
 708 }
 709
 710 /**
 711  * g_socket_listener_accept_socket_async:
 712  * @listener: a #GSocketListener
 713  * @cancellable: (allow-none): a #GCancellable, or %NULL
 714  * @callback: (scope async): a #GAsyncReadyCallback
 715  * @user_data: (closure): user data for the callback
 716  *
 717  * This is the asynchronous version of g_socket_listener_accept_socket().
 718  *
 719  * When the operation is finished @callback will be
 720  * called. You can then call g_socket_listener_accept_socket_finish()
 721  * to get the result of the operation.
 722  *
 723  * Since: 2.22
 724  */
 725 void
 726 g_socket_listener_accept_socket_async (GSocketListener     *listener,
 727                                        GCancellable        *cancellable,
 728                                        GAsyncReadyCallback  callback,
 729                                        gpointer             user_data)
 730 {
 731   GTask *task;
 732   GList *sources;
 733   GError *error = NULL;
 734
 735   task = g_task_new (listener, cancellable, callback, user_data);
 736
 737   if (!check_listener (listener, &error))
 738     {
 739       g_task_return_error (task, error);
 740       g_object_unref (task);
 741       return;
 742     }
 743
 744   sources = add_sources (listener,
 745                          accept_ready,
 746                          task,
 747                          cancellable,
 748                          g_main_context_get_thread_default ());
 749   g_task_set_task_data (task, sources, (GDestroyNotify) free_sources);
 750 }
 751
 752 /**
 753  * g_socket_listener_accept_socket_finish:
 754  * @listener: a #GSocketListener
 755  * @result: a #GAsyncResult.
 756  * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
 757  * @error: a #GError location to store the error occurring, or %NULL to
 758  * ignore.
 759  *
 760  * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
 761  *
 762  * Returns: (transfer full): a #GSocket on success, %NULL on error.
 763  *
 764  * Since: 2.22
 765  */
 766 GSocket *
 767 g_socket_listener_accept_socket_finish (GSocketListener  *listener,
 768                                         GAsyncResult     *result,
 769                                         GObject         **source_object,
 770                                         GError          **error)
 771 {
 772   g_return_val_if_fail (G_IS_SOCKET_LISTENER (listener), NULL);
 773   g_return_val_if_fail (g_task_is_valid (result, listener), NULL);
 774
 775   if (source_object)
 776     *source_object = g_object_get_qdata (G_OBJECT (result), source_quark);
 777
 778   return g_task_propagate_pointer (G_TASK (result), error);
 779 }
 780
 781 /**
 782  * g_socket_listener_accept_async:
 783  * @listener: a #GSocketListener
 784  * @cancellable: (allow-none): a #GCancellable, or %NULL
 785  * @callback: (scope async): a #GAsyncReadyCallback
 786  * @user_data: (closure): user data for the callback
 787  *
 788  * This is the asynchronous version of g_socket_listener_accept().
 789  *
 790  * When the operation is finished @callback will be
 791  * called. You can then call g_socket_listener_accept_socket()
 792  * to get the result of the operation.
 793  *
 794  * Since: 2.22
 795  */
 796 void
 797 g_socket_listener_accept_async (GSocketListener     *listener,
 798                                 GCancellable        *cancellable,
 799                                 GAsyncReadyCallback  callback,
 800                                 gpointer             user_data)
 801 {
 802   g_socket_listener_accept_socket_async (listener,
 803                                          cancellable,
 804                                          callback,
 805                                          user_data);
 806 }
 807
 808 /**
 809  * g_socket_listener_accept_finish:
 810  * @listener: a #GSocketListener
 811  * @result: a #GAsyncResult.
 812  * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
 813  * @error: a #GError location to store the error occurring, or %NULL to
 814  * ignore.
 815  *
 816  * Finishes an async accept operation. See g_socket_listener_accept_async()
 817  *
 818  * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
 819  *
 820  * Since: 2.22
 821  */
 822 GSocketConnection *
 823 g_socket_listener_accept_finish (GSocketListener  *listener,
 824                                  GAsyncResult     *result,
 825                                  GObject         **source_object,
 826                                  GError          **error)
 827 {
 828   GSocket *socket;
 829   GSocketConnection *connection;
 830
 831   socket = g_socket_listener_accept_socket_finish (listener,
 832                                                    result,
 833                                                    source_object,
 834                                                    error);
 835   if (socket == NULL)
 836     return NULL;
 837
 838   connection = g_socket_connection_factory_create_connection (socket);
 839   g_object_unref (socket);
 840   return connection;
 841 }
 842
 843 /**
 844  * g_socket_listener_set_backlog:
 845  * @listener: a #GSocketListener
 846  * @listen_backlog: an integer
 847  *
 848  * Sets the listen backlog on the sockets in the listener.
 849  *
 850  * See g_socket_set_listen_backlog() for details
 851  *
 852  * Since: 2.22
 853  */
 854 void
 855 g_socket_listener_set_backlog (GSocketListener *listener,
 856                                int              listen_backlog)
 857 {
 858   GSocket *socket;
 859   int i;
 860
 861   if (listener->priv->closed)
 862     return;
 863
 864   listener->priv->listen_backlog = listen_backlog;
 865
 866   for (i = 0; i < listener->priv->sockets->len; i++)
 867     {
 868       socket = listener->priv->sockets->pdata[i];
 869       g_socket_set_listen_backlog (socket, listen_backlog);
 870     }
 871 }
 872
 873 /**
 874  * g_socket_listener_close:
 875  * @listener: a #GSocketListener
 876  *
 877  * Closes all the sockets in the listener.
 878  *
 879  * Since: 2.22
 880  */
 881 void
 882 g_socket_listener_close (GSocketListener *listener)
 883 {
 884   GSocket *socket;
 885   int i;
 886
 887   g_return_if_fail (G_IS_SOCKET_LISTENER (listener));
 888
 889   if (listener->priv->closed)
 890     return;
 891
 892   for (i = 0; i < listener->priv->sockets->len; i++)
 893     {
 894       socket = listener->priv->sockets->pdata[i];
 895       g_socket_close (socket, NULL);
 896     }
 897   listener->priv->closed = TRUE;
 898 }
 899
 900 /**
 901  * g_socket_listener_add_any_inet_port:
 902  * @listener: a #GSocketListener
 903  * @source_object: (allow-none): Optional #GObject identifying this source
 904  * @error: a #GError location to store the error occurring, or %NULL to
 905  * ignore.
 906  *
 907  * Listens for TCP connections on any available port number for both
 908  * IPv6 and IPv4 (if each is available).
 909  *
 910  * This is useful if you need to have a socket for incoming connections
 911  * but don't care about the specific port number.
 912  *
 913  * @source_object will be passed out in the various calls
 914  * to accept to identify this particular source, which is
 915  * useful if you're listening on multiple addresses and do
 916  * different things depending on what address is connected to.
 917  *
 918  * Returns: the port number, or 0 in case of failure.
 919  *
 920  * Since: 2.24
 921  **/
 922 guint16
 923 g_socket_listener_add_any_inet_port (GSocketListener  *listener,
 924                                      GObject          *source_object,
 925                                      GError          **error)
 926 {
 927   GSList *sockets_to_close = NULL;
 928   guint16 candidate_port = 0;
 929   GSocket *socket6 = NULL;
 930   GSocket *socket4 = NULL;
 931   gint attempts = 37;
 932
 933   /*
 934    * multi-step process:
 935    *  - first, create an IPv6 socket.
 936    *  - if that fails, create an IPv4 socket and bind it to port 0 and
 937    *    that's it.  no retries if that fails (why would it?).
 938    *  - if our IPv6 socket also speaks IPv4 then we are done.
 939    *  - if not, then we need to create a IPv4 socket with the same port
 940    *    number.  this might fail, of course.  so we try this a bunch of
 941    *    times -- leaving the old IPv6 sockets open so that we get a
 942    *    different port number to try each time.
 943    *  - if all that fails then just give up.
 944    */
 945
 946   while (attempts--)
 947     {
 948       GInetAddress *inet_address;
 949       GSocketAddress *address;
 950       gboolean result;
 951
 952       g_assert (socket6 == NULL);
 953       socket6 = g_socket_new (G_SOCKET_FAMILY_IPV6,
 954                               G_SOCKET_TYPE_STREAM,
 955                               G_SOCKET_PROTOCOL_DEFAULT,
 956                               NULL);
 957
 958       if (socket6 != NULL)
 959         {
 960           inet_address = g_inet_address_new_any (G_SOCKET_FAMILY_IPV6);
 961           address = g_inet_socket_address_new (inet_address, 0);
 962           g_object_unref (inet_address);
 963           result = g_socket_bind (socket6, address, TRUE, error);
 964           g_object_unref (address);
 965
 966           if (!result ||
 967               !(address = g_socket_get_local_address (socket6, error)))
 968             {
 969               g_object_unref (socket6);
 970               socket6 = NULL;
 971               break;
 972             }
 973
 974           g_assert (G_IS_INET_SOCKET_ADDRESS (address));
 975           candidate_port =
 976             g_inet_socket_address_get_port (G_INET_SOCKET_ADDRESS (address));
 977           g_assert (candidate_port != 0);
 978           g_object_unref (address);
 979
 980           if (g_socket_speaks_ipv4 (socket6))
 981             break;
 982         }
 983
 984       g_assert (socket4 == NULL);
 985       socket4 = g_socket_new (G_SOCKET_FAMILY_IPV4,
 986                               G_SOCKET_TYPE_STREAM,
 987                               G_SOCKET_PROTOCOL_DEFAULT,
 988                               socket6 ? NULL : error);
 989
 990       if (socket4 == NULL)
 991         /* IPv4 not supported.
 992          * if IPv6 is supported then candidate_port will be non-zero
 993          *   (and the error parameter above will have been NULL)
 994          * if IPv6 is unsupported then candidate_port will be zero
 995          *   (and error will have been set by the above call)
 996          */
 997         break;
 998
 999       inet_address = g_inet_address_new_any (G_SOCKET_FAMILY_IPV4);
1000       address = g_inet_socket_address_new (inet_address, candidate_port);
1001       g_object_unref (inet_address);
1002       /* a note on the 'error' clause below:
1003        *
1004        * if candidate_port is 0 then we report the error right away
1005        * since it is strange that this binding would fail at all.
1006        * otherwise, we ignore the error message (ie: NULL).
1007        *
1008        * the exception to this rule is the last time through the loop
1009        * (ie: attempts == 0) in which case we want to set the error
1010        * because failure here means that the entire call will fail and
1011        * we need something to show to the user.
1012        *
1013        * an english summary of the situation:  "if we gave a candidate
1014        * port number AND we have more attempts to try, then ignore the
1015        * error for now".
1016        */
1017       result = g_socket_bind (socket4, address, TRUE,
1018                               (candidate_port && attempts) ? NULL : error);
1019       g_object_unref (address);
1020
1021       if (candidate_port)
1022         {
1023           g_assert (socket6 != NULL);
1024
1025           if (result)
1026             /* got our candidate port successfully */
1027             break;
1028
1029           else
1030             /* we failed to bind to the specified port.  try again. */
1031             {
1032               g_object_unref (socket4);
1033               socket4 = NULL;
1034
1035               /* keep this open so we get a different port number */
1036               sockets_to_close = g_slist_prepend (sockets_to_close,
1037                                                   socket6);
1038               candidate_port = 0;
1039               socket6 = NULL;
1040             }
1041         }
1042       else
1043         /* we didn't tell it a port.  this means two things.
1044          *  - if we failed, then something really bad happened.
1045          *  - if we succeeded, then we need to find out the port number.
1046          */
1047         {
1048           g_assert (socket6 == NULL);
1049
1050           if (!result ||
1051               !(address = g_socket_get_local_address (socket4, error)))
1052             {
1053               g_object_unref (socket4);
1054               socket4 = NULL;
1055               break;
1056             }
1057
1058             g_assert (G_IS_INET_SOCKET_ADDRESS (address));
1059             candidate_port =
1060               g_inet_socket_address_get_port (G_INET_SOCKET_ADDRESS (address));
1061             g_assert (candidate_port != 0);
1062             g_object_unref (address);
1063             break;
1064         }
1065     }
1066
1067   /* should only be non-zero if we have a socket */
1068   g_assert ((candidate_port != 0) == (socket4 || socket6));
1069
1070   while (sockets_to_close)
1071     {
1072       g_object_unref (sockets_to_close->data);
1073       sockets_to_close = g_slist_delete_link (sockets_to_close,
1074                                               sockets_to_close);
1075     }
1076
1077   /* now we actually listen() the sockets and add them to the listener */
1078   if (socket6 != NULL)
1079     {
1080       g_socket_set_listen_backlog (socket6, listener->priv->listen_backlog);
1081       if (!g_socket_listen (socket6, error))
1082         {
1083           g_object_unref (socket6);
1084           if (socket4)
1085             g_object_unref (socket4);
1086
1087           return 0;
1088         }
1089
1090       if (source_object)
1091         g_object_set_qdata_full (G_OBJECT (socket6), source_quark,
1092                                  g_object_ref (source_object),
1093                                  g_object_unref);
1094
1095       g_ptr_array_add (listener->priv->sockets, socket6);
1096     }
1097
1098    if (socket4 != NULL)
1099     {
1100       g_socket_set_listen_backlog (socket4, listener->priv->listen_backlog);
1101       if (!g_socket_listen (socket4, error))
1102         {
1103           g_object_unref (socket4);
1104           if (socket6)
1105             g_object_unref (socket6);
1106
1107           return 0;
1108         }
1109
1110       if (source_object)
1111         g_object_set_qdata_full (G_OBJECT (socket4), source_quark,
1112                                  g_object_ref (source_object),
1113                                  g_object_unref);
1114
1115       g_ptr_array_add (listener->priv->sockets, socket4);
1116     }
1117
1118   if ((socket4 != NULL || socket6 != NULL) &&
1119       G_SOCKET_LISTENER_GET_CLASS (listener)->changed)
1120     G_SOCKET_LISTENER_GET_CLASS (listener)->changed (listener);
1121
1122   return candidate_port;
1123 }