[gnio] Add docs and minor cleanups of GUnixConnection and GTcpConnection
- From: Alexander Larsson <alexl src gnome org>
- To: svn-commits-list gnome org
- Subject: [gnio] Add docs and minor cleanups of GUnixConnection and GTcpConnection
- Date: Fri, 15 May 2009 13:57:43 -0400 (EDT)
commit 1fbf0cc97fbca474b074aa72ca2943c8f32eab8c
Author: Alexander Larsson <alexl redhat com>
Date: Fri May 15 14:09:11 2009 +0200
Add docs and minor cleanups of GUnixConnection and GTcpConnection
---
gio/gtcpconnection.c | 18 +++---
gio/gtcpconnection.h | 29 +++++++--
gio/gunixconnection.c | 151 +++++++++++++++++++++++++++++++++++++++++++++----
gio/gunixconnection.h | 100 +++++++-------------------------
4 files changed, 194 insertions(+), 104 deletions(-)
diff --git a/gio/gtcpconnection.c b/gio/gtcpconnection.c
index c04b5c8..b823f2d 100644
--- a/gio/gtcpconnection.c
+++ b/gio/gtcpconnection.c
@@ -1,4 +1,5 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
+ *
* Copyright © 2008, 2009 Codethink Limited
*
* This program is free software: you can redistribute it and/or modify
@@ -13,21 +14,22 @@
* SECTION: gtcpconnection
* @title: GTcpConnection
* @short_description: a TCP #GSocketConnection
- * @see_also: #GSocketConnection, #GTcpClient, #GTcpListener.
+ * @see_also: #GSocketConnection.
*
- * This is the subclass of #GSocketConnection that is created by
- * #GTcpClient and #GTcpListener.
+ * This is the subclass of #GSocketConnection that is created
+ * for TCP/IP sockets.
*
- * It is currently completely useless; it offers no additional
- * functionality over its base class.
+ * It is currently empty; it offers no additional functionality
+ * over its base class.
*
* Eventually, some TCP-specific socket stuff will be added.
+ *
+ * Since: 2.22
**/
+#include "config.h"
#include "gtcpconnection.h"
-#include "gsocketconnection.h"
-
G_DEFINE_TYPE_WITH_CODE (GTcpConnection, g_tcp_connection,
G_TYPE_SOCKET_CONNECTION,
g_socket_connection_factory_register_type (g_define_type_id,
diff --git a/gio/gtcpconnection.h b/gio/gtcpconnection.h
index f7a123d..b55738f 100644
--- a/gio/gtcpconnection.h
+++ b/gio/gtcpconnection.h
@@ -1,4 +1,5 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
+ *
* Copyright © 2008, 2009 Codethink Limited
*
* This program is free software: you can redistribute it and/or modify
@@ -6,7 +7,15 @@
* 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: Ryan Lortie <desrt desrt ca>
*/
@@ -15,10 +24,9 @@
#error "Only <gio/gio.h> can be included directly."
#endif
-#ifndef _gtcpconnection_h_
-#define _gtcpconnection_h_
+#ifndef __G_TCP_CONNECTION_H__
+#define __G_TCP_CONNECTION_H__
-#include <glib-object.h>
#include <gio/gsocketconnection.h>
G_BEGIN_DECLS
@@ -35,9 +43,16 @@ G_BEGIN_DECLS
#define G_TCP_CONNECTION_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), \
G_TYPE_TCP_CONNECTION, GTcpConnectionClass))
+/**
+ * GTcpConnection:
+ *
+ * A #GSocketConnection for TCP/IP connections.
+ *
+ * Since: 2.22
+ **/
+typedef struct _GTcpConnection GTcpConnection;
typedef struct _GTcpConnectionPrivate GTcpConnectionPrivate;
typedef struct _GTcpConnectionClass GTcpConnectionClass;
-typedef struct _GTcpConnection GTcpConnection;
struct _GTcpConnectionClass
{
@@ -54,4 +69,4 @@ GType g_tcp_connection_get_type (void);
G_END_DECLS
-#endif /* _gtcpconnection_h_ */
+#endif /* __G_TCP_CONNECTION_H__ */
diff --git a/gio/gunixconnection.c b/gio/gunixconnection.c
index 0f8a6fe..477fdd6 100644
--- a/gio/gunixconnection.c
+++ b/gio/gunixconnection.c
@@ -1,4 +1,5 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
+ *
* Copyright © 2009 Codethink Limited
*
* This program is free software: you can redistribute it and/or modify
@@ -11,8 +12,24 @@
* Authors: Ryan Lortie <desrt desrt ca>
*/
+#include "config.h"
#include "gunixconnection.h"
+/**
+ * SECTION: gunixconnection
+ * @title: GUnixConnection
+ * @short_description: a TCP #GSocketConnection
+ * @see_also: #GSocketConnection.
+ *
+ * This is the subclass of #GSocketConnection that is created
+ * for UNIX domain sockets.
+ *
+ * It contains functions to do some of the unix socket specific
+ * functionallity like passing file descriptors.
+ *
+ * Since: 2.22
+ **/
+
#include <gio/gsocketcontrolmessage.h>
#include <gio/gunixfdmessage.h>
#include <gio/gsocket.h>
@@ -26,6 +43,25 @@ G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection,
0);
);
+/**
+ * g_unix_connection_send_fd:
+ * @connection: a #GUnixConnection.
+ * @fd: a file descriptor
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Passes a file descriptor to the recieving side of the
+ * connection. The recieving end has to call g_unix_connection_receive_fd()
+ * to accept the file descriptor.
+ *
+ * As well as sending the fd this also writes a single byte to the
+ * stream, as this is required for fd passing to work on some
+ * implementations.
+ *
+ * Returns: a %TRUE on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
gboolean
g_unix_connection_send_fd (GUnixConnection *connection,
gint fd,
@@ -64,6 +100,24 @@ g_unix_connection_send_fd (GUnixConnection *connection,
return result;
}
+/**
+ * g_unix_connection_receive_fd:
+ * @connection: a #GUnixConnection.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Recieves a file descriptor from the sending end of the
+ * connection. The sending end has to call g_unix_connection_send_fd()
+ * for this to work.
+ *
+ * As well as reading the fd this also reads a single byte from the
+ * stream, as this is required for fd passing to work on some
+ * implementations.
+ *
+ * Returns: a file descriptor on success, -1 on error.
+ *
+ * Since: 2.22
+ **/
gint
g_unix_connection_receive_fd (GUnixConnection *connection,
GCancellable *cancellable,
@@ -84,7 +138,7 @@ g_unix_connection_receive_fd (GUnixConnection *connection,
{
g_object_unref (socket);
- return FALSE;
+ return -1;
}
g_object_unref (socket);
@@ -93,8 +147,8 @@ g_unix_connection_receive_fd (GUnixConnection *connection,
{
gint i;
- g_set_error (error, 0, 0,
- "Unexpecting 1 control message, got %d", nscm);
+ g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
+ _("Expecting 1 control message, got %d"), nscm);
for (i = 0; i < nscm; i++)
g_object_unref (scms[i]);
@@ -104,10 +158,10 @@ g_unix_connection_receive_fd (GUnixConnection *connection,
return -1;
}
- if G_UNLIKELY (!G_IS_UNIX_FD_MESSAGE (scms[0]))
+ if (!G_IS_UNIX_FD_MESSAGE (scms[0]))
{
- g_set_error_literal (error, 0, 0,
- "Unexpected type of ancillary data");
+ g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
+ _("Unexpected type of ancillary data"));
g_object_unref (scms[0]);
g_free (scms);
@@ -124,8 +178,8 @@ g_unix_connection_receive_fd (GUnixConnection *connection,
{
gint i;
- g_set_error (error, 0, 0,
- "Expecting one fd, but got %d\n", nfd);
+ g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
+ _("Expecting one fd, but got %d\n"), nfd);
for (i = 0; i < nfd; i++)
close (fds[i]);
@@ -140,8 +194,8 @@ g_unix_connection_receive_fd (GUnixConnection *connection,
if (fd < 0)
{
- g_set_error (error, 0, 0,
- "Received invalid fd");
+ g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
+ _("Received invalid fd"));
fd = -1;
}
@@ -157,3 +211,78 @@ static void
g_unix_connection_class_init (GUnixConnectionClass *class)
{
}
+
+/* TODO: Other stuff we might want to add are:
+void g_unix_connection_send_fd_async (GUnixConnection *connection,
+ gint fd,
+ gboolean close,
+ gint io_priority,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_unix_connection_send_fd_finish (GUnixConnection *connection,
+ GError **error);
+
+gboolean g_unix_connection_send_fds (GUnixConnection *connection,
+ gint *fds,
+ gint nfds,
+ GError **error);
+void g_unix_connection_send_fds_async (GUnixConnection *connection,
+ gint *fds,
+ gint nfds,
+ gint io_priority,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_unix_connection_send_fds_finish (GUnixConnection *connection,
+ GError **error);
+
+void g_unix_connection_receive_fd_async (GUnixConnection *connection,
+ gint io_priority,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gint g_unix_connection_receive_fd_finish (GUnixConnection *connection,
+ GError **error);
+
+
+gboolean g_unix_connection_send_credentials (GUnixConnection *connection,
+ GError **error);
+void g_unix_connection_send_credentials_async (GUnixConnection *connection,
+ gint io_priority,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_unix_connection_send_credentials_finish (GUnixConnection *connection,
+ GError **error);
+
+gboolean g_unix_connection_send_fake_credentials (GUnixConnection *connection,
+ guint64 pid,
+ guint64 uid,
+ guint64 gid,
+ GError **error);
+void g_unix_connection_send_fake_credentials_async (GUnixConnection *connection,
+ guint64 pid,
+ guint64 uid,
+ guint64 gid,
+ gint io_priority,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_unix_connection_send_fake_credentials_finish (GUnixConnection *connection,
+ GError **error);
+
+gboolean g_unix_connection_receive_credentials (GUnixConnection *connection,
+ guint64 *pid,
+ guint64 *uid,
+ guint64 *gid,
+ GError **error);
+void g_unix_connection_receive_credentials_async (GUnixConnection *connection,
+ gint io_priority,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_unix_connection_receive_credentials_finish (GUnixConnection *connection,
+ guint64 *pid,
+ guint64 *uid,
+ guint64 *gid,
+ GError **error);
+
+gboolean g_unix_connection_create_pair (GUnixConnection **one,
+ GUnixConnection **two,
+ GError **error);
+*/
diff --git a/gio/gunixconnection.h b/gio/gunixconnection.h
index 5c1a9db..b51ef90 100644
--- a/gio/gunixconnection.h
+++ b/gio/gunixconnection.h
@@ -1,4 +1,5 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
+ *
* Copyright © 2009 Codethink Limited
*
* This program is free software: you can redistribute it and/or modify
@@ -6,13 +7,21 @@
* 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: Ryan Lortie <desrt desrt ca>
*/
-#ifndef _gunixconnection_h_
-#define _gunixconnection_h_
+#ifndef __G_UNIX_CONNECTION_H__
+#define __G_UNIX_CONNECTION_H__
#include <gio/gsocketconnection.h>
#include <gio/giotypes.h>
@@ -31,9 +40,16 @@ G_BEGIN_DECLS
#define G_UNIX_CONNECTION_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), \
G_TYPE_UNIX_CONNECTION, GUnixConnectionClass))
+/**
+ * GTcpConnection:
+ *
+ * A #GSocketConnection for UNIX domain socket connections.
+ *
+ * Since: 2.22
+ **/
+typedef struct _GUnixConnection GUnixConnection;
typedef struct _GUnixConnectionPrivate GUnixConnectionPrivate;
typedef struct _GUnixConnectionClass GUnixConnectionClass;
-typedef struct _GUnixConnection GUnixConnection;
struct _GUnixConnectionClass
{
@@ -52,82 +68,10 @@ gboolean g_unix_connection_send_fd (GUnixCo
gint fd,
GCancellable *cancellable,
GError **error);
-void g_unix_connection_send_fd_async (GUnixConnection *connection,
- gint fd,
- gboolean close,
- gint io_priority,
- GAsyncReadyCallback callback,
- gpointer user_data);
-gboolean g_unix_connection_send_fd_finish (GUnixConnection *connection,
- GError **error);
-
-gboolean g_unix_connection_send_fds (GUnixConnection *connection,
- gint *fds,
- gint nfds,
- GError **error);
-void g_unix_connection_send_fds_async (GUnixConnection *connection,
- gint *fds,
- gint nfds,
- gint io_priority,
- GAsyncReadyCallback callback,
- gpointer user_data);
-gboolean g_unix_connection_send_fds_finish (GUnixConnection *connection,
- GError **error);
-
gint g_unix_connection_receive_fd (GUnixConnection *connection,
GCancellable *cancellable,
GError **error);
-void g_unix_connection_receive_fd_async (GUnixConnection *connection,
- gint io_priority,
- GAsyncReadyCallback callback,
- gpointer user_data);
-gint g_unix_connection_receive_fd_finish (GUnixConnection *connection,
- GError **error);
-
-
-gboolean g_unix_connection_send_credentials (GUnixConnection *connection,
- GError **error);
-void g_unix_connection_send_credentials_async (GUnixConnection *connection,
- gint io_priority,
- GAsyncReadyCallback callback,
- gpointer user_data);
-gboolean g_unix_connection_send_credentials_finish (GUnixConnection *connection,
- GError **error);
-
-gboolean g_unix_connection_send_fake_credentials (GUnixConnection *connection,
- guint64 pid,
- guint64 uid,
- guint64 gid,
- GError **error);
-void g_unix_connection_send_fake_credentials_async (GUnixConnection *connection,
- guint64 pid,
- guint64 uid,
- guint64 gid,
- gint io_priority,
- GAsyncReadyCallback callback,
- gpointer user_data);
-gboolean g_unix_connection_send_fake_credentials_finish (GUnixConnection *connection,
- GError **error);
-
-gboolean g_unix_connection_receive_credentials (GUnixConnection *connection,
- guint64 *pid,
- guint64 *uid,
- guint64 *gid,
- GError **error);
-void g_unix_connection_receive_credentials_async (GUnixConnection *connection,
- gint io_priority,
- GAsyncReadyCallback callback,
- gpointer user_data);
-gboolean g_unix_connection_receive_credentials_finish (GUnixConnection *connection,
- guint64 *pid,
- guint64 *uid,
- guint64 *gid,
- GError **error);
-
-gboolean g_unix_connection_create_pair (GUnixConnection **one,
- GUnixConnection **two,
- GError **error);
G_END_DECLS
-#endif /* _gunixconnection_h_ */
+#endif /* __G_UNIX_CONNECTION_H__ */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
