[gnio] Add docs for GSocketListener and subclasses

[Alexander Larsson <alexl src gnome org>]

commit e08fa200d4b5158ead1e2966fb6278fb923092c2
Author: Alexander Larsson <alexl redhat com>
Date:   Fri May 15 19:47:33 2009 +0200

    Add docs for GSocketListener and subclasses
---
 gio/gsocketlistener.c |  217 ++++++++++++++++++++++++++++++++++++++++++++++++-
 gio/gsocketservice.c  |   55 ++++++++++++-
 2 files changed, 267 insertions(+), 5 deletions(-)

diff --git a/gio/gsocketlistener.c b/gio/gsocketlistener.c
index f5cb9c7..24802e1 100644
--- a/gio/gsocketlistener.c
+++ b/gio/gsocketlistener.c
@@ -34,6 +34,23 @@
 #include <gio/ginetaddress.h>
 #include <gio/ginetsocketaddress.h>
 
+/**
+ * SECTION: gsocketlistener
+ * @title: GSocketListener
+ * @short_description: a high-level helper object for server sockets
+ * @see_also: #GThreadedSocketService, #GSocketService.
+ *
+ * A #GSocketListener is an object that keeps track of a set
+ * of server sockets and helps you accept sockets from any of the
+ * socket, either sync or async.
+ *
+ * If you want to implement a network server, also look at #GSocketService
+ * and #GThreadedSocketService which are subclass of #GSocketListener
+ * that makes this even easier.
+ *
+ * Since: 2.22
+ */
+
 G_DEFINE_TYPE (GSocketListener, g_socket_listener, G_TYPE_OBJECT);
 
 enum
@@ -142,6 +159,17 @@ g_socket_listener_init (GSocketListener *listener)
   listener->priv->listen_backlog = 10;
 }
 
+/**
+ * g_socket_service_new:
+ *
+ * Creates a new #GSocketListener with no sockets to listen for.
+ * New listeners can be added with e.g. g_socket_listener_add_address()
+ * or g_socket_listener_add_inet_port().
+ *
+ * Returns: a new #GSocketListener.
+ *
+ * Since: 2.22
+ **/
 GSocketListener *
 g_socket_listener_new (void)
 {
@@ -162,6 +190,26 @@ check_listener (GSocketListener *listener,
   return TRUE;
 }
 
+/**
+ * g_socket_listener_add_socket:
+ * @listener: a #GSocketListener
+ * @socket: a listening #GSocket
+ * @source_object: Optional #GObject identifying this source
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Adds @socket to the set of sockets that we try to accept
+ * new clients from. The socket must be bound to a local
+ * address and listened to.
+ *
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * useful if you're listening on multiple addresses and do
+ * different things depending on what address is connected to.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_listener_add_socket (GSocketListener *listener,
 			      GSocket *socket,
@@ -190,6 +238,28 @@ g_socket_listener_add_socket (GSocketListener *listener,
   return TRUE;
 }
 
+/**
+ * g_socket_listener_add_socket:
+ * @listener: a #GSocketListener
+ * @address: a #GSocketAddres
+ * @type: a #GSocketType
+ * @protocol: a protocol name, or %NULL
+ * @source_object: Optional #GObject identifying this source
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Creates a socket of type @type and protocol @protocol, binds
+ * it to @address and adds it to the set of sockets we're accepting
+ * sockets from.
+ *
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * useful if you're listening on multiple addresses and do
+ * different things depending on what address is connected to.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_listener_add_address (GSocketListener *listener,
 			       GSocketAddress *address,
@@ -226,6 +296,26 @@ g_socket_listener_add_address (GSocketListener *listener,
   return TRUE;
 }
 
+/**
+ * g_socket_listener_add_inet_port:
+ * @listener: a #GSocketListener
+ * @port: an ip port number
+ * @source_object: Optional #GObject identifying this source
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Helper function for g_socket_listener_add_address() that
+ * creates a TCP/IP socket listening on IPv4 and IPv6 (if
+ * supported) on the specified port on all interfaces.
+ *
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * useful if you're listening on multiple addresses and do
+ * different things depending on what address is connected to.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_listener_add_inet_port (GSocketListener *listener,
 				 int port,
@@ -342,6 +432,32 @@ accept_callback (GSocket *socket,
   return TRUE;
 }
 
+/**
+ * g_socket_listener_accept_socket:
+ * @listener: a #GSocketListener
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @source_object: location where #GObject pointer will be stored, or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Blocks waiting for a client to connect to any of the sockets added
+ * to the listener. Returns the #GSocket that was accepted.
+ *
+ * If you want to accept the high-level #GSocketConnection, not a #GSocket,
+ * which is often the case, then you should use g_socket_listener_accept()
+ * instead.
+ *
+ * If @source_object is not %NULL it will be filled out with the source
+ * object specified when the corresponding socket or address was added
+ * to the listener.
+ *
+ * If @cancellable is not NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error G_IO_ERROR_CANCELLED will be returned.
+ *
+ * Returns: a #GSocket on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocket *
 g_socket_listener_accept_socket (GSocketListener  *listener,
 				 GCancellable     *cancellable,
@@ -393,6 +509,29 @@ g_socket_listener_accept_socket (GSocketListener  *listener,
   return socket;
 }
 
+/**
+ * g_socket_listener_accept:
+ * @listener: a #GSocketListener
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @source_object: location where #GObject pointer will be stored, or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Blocks waiting for a client to connect to any of the sockets added
+ * to the listener. Returns a #GSocketConnection for the socket that was
+ * accepted.
+ *
+ * If @source_object is not %NULL it will be filled out with the source
+ * object specified when the corresponding socket or address was added
+ * to the listener.
+ *
+ * If @cancellable is not NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error G_IO_ERROR_CANCELLED will be returned.
+ *
+ * Returns: a #GSocketConnection on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocketConnection *
 g_socket_listener_accept (GSocketListener  *listener,
 			  GCancellable     *cancellable,
@@ -462,7 +601,21 @@ accept_ready (GSocket *accept_socket,
   return FALSE;
 }
 
-
+/**
+ * g_socket_listener_accept_socket_async:
+ * @listener: a #GSocketListener
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback
+ * @user_data: user data for the callback
+ *
+ * This is the asynchronous version of g_socket_listener_accept_socket().
+ *
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_listener_accept_socket_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_listener_accept_socket_async (GSocketListener      *listener,
 				       GCancellable         *cancellable,
@@ -493,6 +646,20 @@ g_socket_listener_accept_socket_async (GSocketListener      *listener,
 			       NULL);
 }
 
+/**
+ * g_socket_listener_accept_socket_finish:
+ * @listener: a #GSocketListener
+ * @result: a #GAsyncResult.
+ * @source_object: Optional #GObject identifying this source
+ * @error: a #GError location to store the error occuring, or %NULL to
+ * ignore.
+ *
+ * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
+ *
+ * Returns: a #GSocket on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocket *
 g_socket_listener_accept_socket_finish (GSocketListener   *listener,
 					GAsyncResult      *result,
@@ -519,6 +686,21 @@ g_socket_listener_accept_socket_finish (GSocketListener   *listener,
   return g_object_ref (socket);
 }
 
+/**
+ * g_socket_listener_accept_socket_async:
+ * @listener: a #GSocketListener
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback
+ * @user_data: user data for the callback
+ *
+ * This is the asynchronous version of g_socket_listener_accept().
+ *
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_listener_accept_socket() to get
+ * the result of the operation.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_listener_accept_async (GSocketListener     *listener,
                                 GCancellable        *cancellable,
@@ -531,6 +713,20 @@ g_socket_listener_accept_async (GSocketListener     *listener,
 					 user_data);
 }
 
+/**
+ * g_socket_listener_accept_finish:
+ * @listener: a #GSocketListener
+ * @result: a #GAsyncResult.
+ * @source_object: Optional #GObject identifying this source
+ * @error: a #GError location to store the error occuring, or %NULL to
+ * ignore.
+ *
+ * Finishes an async accept operation. See g_socket_listener_accept_async()
+ *
+ * Returns: a #GSocketConnection on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocketConnection *
 g_socket_listener_accept_finish (GSocketListener *listener,
 				 GAsyncResult *result,
@@ -552,6 +748,17 @@ g_socket_listener_accept_finish (GSocketListener *listener,
   return connection;
 }
 
+/**
+ * g_socket_listener_accept_finish:
+ * @listener: a #GSocketListener
+ * @listen_backlog: an integer
+ *
+ * Sets the listen backlog on the sockets in the listener.
+ *
+ * See g_socket_set_listen_backlog() for details
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_listener_set_backlog (GSocketListener *listener,
 			       int listen_backlog)
@@ -571,6 +778,14 @@ g_socket_listener_set_backlog (GSocketListener *listener,
     }
 }
 
+/**
+ * g_socket_listener_close:
+ * @listener: a #GSocketListener
+ *
+ * Closes all the sockets in the listener.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_listener_close (GSocketListener *listener)
 {
diff --git a/gio/gsocketservice.c b/gio/gsocketservice.c
index 0a89577..effe72d 100644
--- a/gio/gsocketservice.c
+++ b/gio/gsocketservice.c
@@ -46,6 +46,13 @@
  * will block additional incoming connections from being serviced.  If
  * you are interested in writing connection handlers that contain
  * blocking code then see #GThreadedSocketService.
+ *
+ * The socket service runs on the main loop in the main thread, and is
+ * not threadsafe in general. However, the calls to start and stop
+ * the service are threadsafe so these can be used from threads that
+ * handle incomming clients.
+ *
+ * Since: 2.22
  */
 
 #include "config.h"
@@ -133,6 +140,19 @@ g_socket_service_changed (GSocketListener *listener)
   G_UNLOCK (active);
 }
 
+/**
+ * g_socket_service_is_active:
+ * @service: a #GSocketService
+ *
+ * Check whether the service is active or not. An active
+ * service will accept new clients that connect, while
+ * a non-active service will let connecting clients queue
+ * up until the service is started.
+ *
+ * Returns: %TRUE if the service is active, %FALSE otherwise
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_service_is_active (GSocketService *service)
 {
@@ -144,10 +164,21 @@ g_socket_service_is_active (GSocketService *service)
   return active;
 }
 
+/**
+ * g_socket_service_start:
+ * @service: a #GSocketService
+ *
+ * Starts the service, i.e. start accepting connections
+ * from the added sockets when the mainloop runs.
+ *
+ * This call is threadsafe, so it may be called from a thread
+ * handling an incomming client request.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_service_start (GSocketService *service)
 {
-  g_print ("g_socket_service_start\n");
   G_LOCK (active);
 
   if (!service->priv->active)
@@ -163,10 +194,21 @@ g_socket_service_start (GSocketService *service)
   G_UNLOCK (active);
 }
 
+/**
+ * g_socket_service_stop:
+ * @service: a #GSocketService
+ *
+ * Stops the service, i.e. stops accepting connections
+ * from the added sockets when the mainloop runs.
+ *
+ * This call is threadsafe, so it may be called from a thread
+ * handling an incomming client request.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_service_stop (GSocketService  *service)
 {
-  g_print ("g_socket_service_stop\n");
   G_LOCK (active);
 
   if (service->priv->active)
@@ -268,8 +310,13 @@ g_socket_service_ready (GObject      *object,
  * g_socket_service_new:
  * @returns: a new #GSocketService.
  *
- * Creates a new #GSocketService with no listeners.  Listeners must be
- * added with g_socket_service_add_listener().
+ * Creates a new #GSocketService with no sockets to listen for.
+ * New listeners can be added with e.g. g_socket_listener_add_address()
+ * or g_socket_listener_add_inet_port().
+ *
+ * Returns: a new #GSocketService.
+ *
+ * Since: 2.22
  **/
 GSocketService *
 g_socket_service_new (void)