summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlexander Larsson <alexl@redhat.com>2009-05-15 10:39:51 (GMT)
committerAlexander Larsson <alexl@redhat.com>2009-05-15 10:39:51 (GMT)
commitda63c7108f9a78df883a7c4baeaf314050bf7e78 (patch)
tree93bcc4c46d45a0261a17cf32dbc576795fbf430e
parent92d7e13ce4996f0e63b647c752e5e71d4a1530b0 (diff)
downloadgnio-da63c7108f9a78df883a7c4baeaf314050bf7e78.tar.gz
gnio-da63c7108f9a78df883a7c4baeaf314050bf7e78.tar.xz
Add docs to GSocketConnection
-rw-r--r--gio/gsocketconnection.c75
-rw-r--r--gio/gsocketconnection.h28
2 files changed, 89 insertions, 14 deletions
diff --git a/gio/gsocketconnection.c b/gio/gsocketconnection.c
index 4ec8045..df9eb0d 100644
--- a/gio/gsocketconnection.c
+++ b/gio/gsocketconnection.c
@@ -1,7 +1,8 @@
-/* GNIO - GLib Network Layer of GIO
+/* GIO - GLib Input, Output and Streaming Library
*
* Copyright © 2008 Christian Kellner, Samuel Cormier-Iijima
* © 2008 codethink
+ * Copyright © 2009 Red Hat, Inc
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
@@ -21,16 +22,10 @@
* Authors: Christian Kellner <gicmo@gnome.org>
* Samuel Cormier-Iijima <sciyoshi@gmail.com>
* Ryan Lortie <desrt@desrt.ca>
+ * Alexander Larsson <alexl@redhat.com>
*/
-/* TODO: On glib merge, switch this */
#include "config.h"
-#if 0
-#include "glibintl.h"
-#else
-#include <glib/gi18n-lib.h>
-#define P_(String) _(String)
-#endif
#include "gsocketconnection.h"
@@ -41,6 +36,28 @@
#include "gunixconnection.h"
#include "gtcpconnection.h"
+/**
+ * SECTION:gsocketconnection
+ * @short_description: High-level socket connection stream
+ * @include: gio/gio.h
+ * @see_also: #GIOStream, #GSocketClient, #GSocketListener
+ *
+ * #GSocketConnection is a #GIOStream for a connected socket. They
+ * can be created either by #GSocketClient when connecting to a host,
+ * or by #GSocketListener when accepting a new client.
+ *
+ * The type of the #GSocketConnection object returned from these calls depends
+ * on the type of the underlying socket that is in use. For instance, for a
+ * TCP/IP connection it will be a #GTcpConnection.
+ *
+ * Chosing what type of object to construct is done with the socket connection
+ * factory, and it is possible for 3rd parties to register custom socket connection
+ * types for specific combination of socket family/type/protocol using
+ * g_socket_connection_factory_register_type().
+ *
+ * Since: 2.22
+ **/
+
G_DEFINE_TYPE (GSocketConnection,
g_socket_connection, G_TYPE_IO_STREAM);
@@ -293,6 +310,21 @@ connection_factory_equal (gconstpointer _a,
static GHashTable *connection_factories = NULL;
G_LOCK_DEFINE_STATIC(connection_factories);
+/**
+ * g_socket_connection_factory_register_type:
+ * @g_type: a #GType, inheriting from G_SOCKET_CONNECTION
+ * @family: a #GSocketFamily.
+ * @type: a #GSocketType
+ * @protocol: a protocol id
+ *
+ * Looks up the #GType to be used when creating socket connections on
+ * sockets with the specified @family,@type and @protocol_id.
+ *
+ * If no type is registered, the #GSocketConnection base type is returned.
+ *
+ * Returns: a #GType
+ * Since: 2.22
+ **/
void
g_socket_connection_factory_register_type (GType g_type,
GSocketFamily family,
@@ -301,6 +333,8 @@ g_socket_connection_factory_register_type (GType g_type,
{
ConnectionFactory *factory;
+ g_return_if_fail (g_type_is_a (g_type, G_TYPE_SOCKET_CONNECTION));
+
G_LOCK (connection_factories);
if (connection_factories == NULL)
@@ -331,6 +365,20 @@ init_builtin_types (void)
a_type = g_tcp_connection_get_type ();
}
+/**
+ * g_socket_connection_factory_lookup_type:
+ * @family: a #GSocketFamily.
+ * @type: a #GSocketType
+ * @protocol_id: a protocol id
+ *
+ * Looks up the #GType to be used when creating socket connections on
+ * sockets with the specified @family,@type and @protocol_id.
+ *
+ * If no type is registered, the #GSocketConnection base type is returned.
+ *
+ * Returns: a #GType
+ * Since: 2.22
+ **/
GType
g_socket_connection_factory_lookup_type (GSocketFamily family,
GSocketType type,
@@ -361,6 +409,17 @@ g_socket_connection_factory_lookup_type (GSocketFamily family,
return g_type;
}
+/**
+ * g_socket_connection_factory_create_connection:
+ * @socket: a #GSocket.
+ *
+ * Creates a #GSocketConnection subclass of the right type for
+ * @socket.
+ *
+ * Returns: a #GSocketConnection
+ *
+ * Since: 2.22
+ **/
GSocketConnection *
g_socket_connection_factory_create_connection (GSocket *socket)
{
diff --git a/gio/gsocketconnection.h b/gio/gsocketconnection.h
index ecbcccd..a3c3809 100644
--- a/gio/gsocketconnection.h
+++ b/gio/gsocketconnection.h
@@ -1,4 +1,4 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
* Copyright © 2008 Christian Kellner, Samuel Cormier-Iijima
* Copyright © 2009 Codethink Limited
*
@@ -7,19 +7,28 @@
* by the Free Software Foundation; either version 2 of the licence or (at
* your option) any later version.
*
- * See the included COPYING file for more information.
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General
+ * Public License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+ * Boston, MA 02111-1307, USA.
*
* Authors: Christian Kellner <gicmo@gnome.org>
* Samuel Cormier-Iijima <sciyoshi@gmail.com>
* Ryan Lortie <desrt@desrt.ca>
+ * Alexander Larsson <alexl@redhat.com>
*/
#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
#error "Only <gio/gio.h> can be included directly."
#endif
-#ifndef _gsocketconnection_h_
-#define _gsocketconnection_h_
+#ifndef __G_SOCKET_CONNECTION_H__
+#define __G_SOCKET_CONNECTION_H__
#include <glib-object.h>
#include <gio/gsocket.h>
@@ -39,9 +48,16 @@ G_BEGIN_DECLS
#define G_SOCKET_CONNECTION_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), \
G_TYPE_SOCKET_CONNECTION, GSocketConnectionClass))
+/**
+ * GSocketConnection:
+ *
+ * A socket connection GIOStream object for connection-oriented sockets.
+ *
+ * Since: 2.22
+ **/
+typedef struct _GSocketConnection GSocketConnection;
typedef struct _GSocketConnectionPrivate GSocketConnectionPrivate;
typedef struct _GSocketConnectionClass GSocketConnectionClass;
-typedef struct _GSocketConnection GSocketConnection;
struct _GSocketConnectionClass
{
@@ -69,4 +85,4 @@ GSocketConnection *g_socket_connection_factory_create_connection (GSocket
G_END_DECLS
-#endif /* _gsocketconnection_h_ */
+#endif /* __G_SOCKET_CONNECTION_H__ */