[gnio] Add docs for GSocketClient
- From: Alexander Larsson <alexl src gnome org>
- To: svn-commits-list gnome org
- Subject: [gnio] Add docs for GSocketClient
- Date: Fri, 15 May 2009 13:57:22 -0400 (EDT)
commit 92d7e13ce4996f0e63b647c752e5e71d4a1530b0
Author: Alexander Larsson <alexl redhat com>
Date: Fri May 15 12:19:31 2009 +0200
Add docs for GSocketClient
---
gio/gsocketclient.c | 294 ++++++++++++++++++++++++++++++++++++++++++++------
gio/gsocketclient.h | 39 ++++++--
2 files changed, 289 insertions(+), 44 deletions(-)
diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c
index 1f6bc83..71385ba 100644
--- a/gio/gsocketclient.c
+++ b/gio/gsocketclient.c
@@ -1,6 +1,7 @@
-/* GNIO - GLib Network Layer of GIO
+/* GIO - GLib Input, Output and Streaming Library
*
* Copyright © 2008, 2009 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
@@ -18,6 +19,7 @@
* Boston, MA 02111-1307, USA.
*
* Authors: Ryan Lortie <desrt desrt ca>
+ * Alexander Larsson <alexl redhat com>
*/
#include "config.h"
@@ -34,6 +36,27 @@
#include <gio/gnetworkaddress.h>
#include <gio/gsocketaddress.h>
+/**
+ * SECTION:gsocketclient
+ * @short_description: High-level client network helper
+ * @include: gio/gio.h
+ * @see_also: #GSocketConnection, #GSocketListener
+ *
+ * #GSocketClient is a high-level utility class for connecting to a
+ * network host using a connection oriented socket type.
+ *
+ * You create a #GSocketClient object, set any options you want, then
+ * call a sync or async connect operation, which returns a #GSocketConnection
+ * subclass on success.
+ *
+ * The type of the #GSocketConnection object returned depends on the type of
+ * the underlying socket that is in use. For instance, for a TCP/IP connection
+ * it will be a #GTcpConnection.
+ *
+ * Since: 2.22
+ **/
+
+
G_DEFINE_TYPE (GSocketClient, g_socket_client, G_TYPE_OBJECT);
enum
@@ -101,6 +124,16 @@ g_socket_client_init (GSocketClient *client)
client->priv->type = G_SOCKET_TYPE_STREAM;
}
+/**
+ * g_socket_client_new:
+ *
+ * Creates a new #GSocketClient with the default options.
+ *
+ * Returns: a #GSocketClient.
+ * Free the returned object with g_object_unref().
+ *
+ * Since: 2.22
+ **/
GSocketClient *
g_socket_client_new (void)
{
@@ -132,23 +165,23 @@ g_socket_client_get_property (GObject *object,
switch (prop_id)
{
case PROP_FAMILY:
- g_value_set_enum (value, client->priv->family);
- break;
+ g_value_set_enum (value, client->priv->family);
+ break;
case PROP_TYPE:
- g_value_set_enum (value, client->priv->type);
- break;
+ g_value_set_enum (value, client->priv->type);
+ break;
case PROP_PROTOCOL:
- g_value_set_string (value, client->priv->protocol);
- break;
+ g_value_set_string (value, client->priv->protocol);
+ break;
case PROP_LOCAL_ADDRESS:
- g_value_set_object (value, client->priv->local_address);
- break;
+ g_value_set_object (value, client->priv->local_address);
+ break;
default:
- G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+ G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
}
}
@@ -183,12 +216,40 @@ g_socket_client_set_property (GObject *object,
}
}
+/**
+ * g_socket_client_get_family:
+ * @socket: a #GSocket.
+ *
+ * Gets the socket family of the socket client.
+ *
+ * See g_socket_client_set_family() for details.
+ *
+ * Returns: a #GSocketFamily
+ *
+ * Since: 2.22
+ **/
GSocketFamily
g_socket_client_get_family (GSocketClient *client)
{
return client->priv->family;
}
+/**
+ * g_socket_client_set_family:
+ * @socket: a #GSocket.
+ * @family: a #GSocketFamily
+ *
+ * Sets the socket family of the socket client.
+ * If this is set to something other than %G_SOCKET_FAMILY_INVALID
+ * then the sockets created by this object will be of the specified
+ * family.
+ *
+ * This might be useful for instance if you want to force the local
+ * connection to be an ipv4 socket, even though the address might
+ * be an ipv6 mapped to ipv4 address.
+ *
+ * Since: 2.22
+ **/
void
g_socket_client_set_family (GSocketClient *client,
GSocketFamily family)
@@ -200,12 +261,38 @@ g_socket_client_set_family (GSocketClient *client,
g_object_notify (G_OBJECT (client), "family");
}
+/**
+ * g_socket_client_get_socket_type:
+ * @socket: a #GSocket.
+ *
+ * Gets the socket type of the socket client.
+ *
+ * See g_socket_client_set_socket_type() for details.
+ *
+ * Returns: a #GSocketFamily
+ *
+ * Since: 2.22
+ **/
GSocketType
g_socket_client_get_socket_type (GSocketClient *client)
{
return client->priv->type;
}
+/**
+ * g_socket_client_set_socket_type:
+ * @socket: a #GSocket.
+ * @type: a #GSocketType
+ *
+ * Sets the socket type of the socket client.
+ * The sockets created by this object will be of the specified
+ * type.
+ *
+ * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
+ * as GSocketClient is used for connection oriented services.
+ *
+ * Since: 2.22
+ **/
void
g_socket_client_set_socket_type (GSocketClient *client,
GSocketType type)
@@ -217,12 +304,38 @@ g_socket_client_set_socket_type (GSocketClient *client,
g_object_notify (G_OBJECT (client), "type");
}
+/**
+ * g_socket_client_get_protocol:
+ * @socket: a #GSocket.
+ *
+ * Gets the protocol name type of the socket client.
+ *
+ * See g_socket_client_set_protocol() for details.
+ *
+ * Returns: a string or %NULL. don't free
+ *
+ * Since: 2.22
+ **/
const char *
g_socket_client_get_protocol (GSocketClient *client)
{
return client->priv->protocol;
}
+/**
+ * g_socket_client_set_protocol:
+ * @socket: a #GSocket.
+ * @protocol: a string, or %NULL
+ *
+ * Sets the protocol of the socket client.
+ * The sockets created by this object will use of the specified
+ * protocol.
+ *
+ * If @protocol is %NULL that means to use the default
+ * protocol for the socket family and type.
+ *
+ * Since: 2.22
+ **/
void
g_socket_client_set_protocol (GSocketClient *client,
const char *protocol)
@@ -235,12 +348,39 @@ g_socket_client_set_protocol (GSocketClient *client,
g_object_notify (G_OBJECT (client), "protocol");
}
+/**
+ * g_socket_client_get_local_address:
+ * @socket: a #GSocket.
+ *
+ * Gets the local address of the socket client.
+ *
+ * See g_socket_client_set_local_address() for details.
+ *
+ * Returns: a #GSocketAddres or %NULL. don't free
+ *
+ * Since: 2.22
+ **/
GSocketAddress *
g_socket_client_get_local_address (GSocketClient *client)
{
return client->priv->local_address;
}
+/**
+ * g_socket_client_set_local_address:
+ * @socket: a #GSocket.
+ * @addres: a #GSocketAddress, or %NULL
+ *
+ * Sets the local address of the socket client.
+ * The sockets created by this object will bound to the
+ * specified address (if not %NULL) before connecting.
+ *
+ * This is useful if you want to ensure the the local
+ * side of the connection is on a specific port, or on
+ * a specific interface.
+ *
+ * Since: 2.22
+ **/
void
g_socket_client_set_local_address (GSocketClient *client,
GSocketAddress *address)
@@ -268,15 +408,15 @@ g_socket_client_class_init (GSocketClientClass *class)
gobject_class->get_property = g_socket_client_get_property;
g_object_class_install_property (gobject_class, PROP_FAMILY,
- g_param_spec_enum ("family",
- P_("Socket family"),
- P_("The sockets address family to use for socket construction"),
- G_TYPE_SOCKET_FAMILY,
- G_SOCKET_FAMILY_INVALID,
- G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ g_param_spec_enum ("family",
+ P_("Socket family"),
+ P_("The sockets address family to use for socket construction"),
+ G_TYPE_SOCKET_FAMILY,
+ G_SOCKET_FAMILY_INVALID,
+ G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
g_object_class_install_property (gobject_class, PROP_TYPE,
- g_param_spec_enum ("type",
+ g_param_spec_enum ("type",
P_("Socket type"),
P_("The sockets type to use for socket construction"),
G_TYPE_SOCKET_TYPE,
@@ -284,25 +424,55 @@ g_socket_client_class_init (GSocketClientClass *class)
G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
g_object_class_install_property (gobject_class, PROP_PROTOCOL,
- g_param_spec_string ("protocol",
+ g_param_spec_string ("protocol",
P_("Socket protocol"),
P_("The protocol to use for socket construction, or %NULL for default"),
NULL,
G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
g_object_class_install_property (gobject_class, PROP_LOCAL_ADDRESS,
- g_param_spec_object ("local-address",
- P_("Local address"),
- P_("The local address constructed sockets will be bound to"),
- G_TYPE_SOCKET_ADDRESS,
- G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ g_param_spec_object ("local-address",
+ P_("Local address"),
+ P_("The local address constructed sockets will be bound to"),
+ G_TYPE_SOCKET_ADDRESS,
+ G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
}
+/**
+ * g_socket_client_connect:
+ * @client: a #GSocketClient.
+ * @connectable: a #GSocketConnectable specifying the remote address.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Tries to resolve the @connectable and make a network connection to it..
+ *
+ * Upon a successful connection, a new #GSocketConnection is constructed
+ * and returned. The caller owns this new object and must drop their
+ * reference to it when finished with it.
+ *
+ * The type of the #GSocketConnection object returned depends on the type of
+ * the underlying socket that is used. For instance, for a TCP/IP connection
+ * it will be a #GTcpConnection.
+ *
+ * The socket created will be the same family as the the address that the
+ * @connectable resolves to, unless family is set with g_socket_client_set_family()
+ * or indirectly via g_socket_client_set_local_address(). The socket type
+ * defaults to %G_SOCKET_TYPE_STREAM but can be set with
+ * g_socket_client_set_socket_type().
+ *
+ * If a local address is specified with g_socket_client_set_local_address() the
+ * socket will be bound to this address before connecting.
+ *
+ * Returns: a #GSocketConnection on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
GSocketConnection *
g_socket_client_connect (GSocketClient *client,
- GSocketConnectable *connectable,
- GCancellable *cancellable,
- GError **error)
+ GSocketConnectable *connectable,
+ GCancellable *cancellable,
+ GError **error)
{
GSocketConnection *connection = NULL;
GSocketAddressEnumerator *enumerator;
@@ -400,6 +570,10 @@ g_socket_client_connect (GSocketClient *client,
* In the event of any failure (DNS error, service not found, no hosts
* connectable) %NULL is returned and @error (if non-%NULL) is set
* accordingly.
+ *
+ Returns: a #GSocketConnection on success, %NULL on error.
+ *
+ * Since: 2.22
**/
GSocketConnection *
g_socket_client_connect_to_host (GSocketClient *client,
@@ -452,8 +626,8 @@ g_socket_client_async_connect_complete (GSocketClientAsyncConnectData *data)
connection = g_socket_connection_factory_create_connection (data->current_socket);
g_simple_async_result_set_op_res_gpointer (data->result,
- connection,
- g_object_unref);
+ connection,
+ g_object_unref);
}
g_simple_async_result_complete (data->result);
@@ -591,12 +765,28 @@ g_socket_client_enumerator_callback (GObject *object,
data);
}
+/**
+ * g_socket_client_connect_to_host_async:
+ * @client: a #GTcpClient
+ * @connectable: a #GSocketConnectable specifying the remote address.
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback
+ * @user_data: user data for the callback
+ *
+ * This is the asynchronous version of g_socket_client_connect().
+ *
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_client_connect_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.22
+ **/
void
g_socket_client_connect_async (GSocketClient *client,
- GSocketConnectable *connectable,
- GCancellable *cancellable,
- GAsyncReadyCallback callback,
- gpointer user_data)
+ GSocketConnectable *connectable,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
{
GSocketClientAsyncConnectData *data;
@@ -605,8 +795,8 @@ g_socket_client_connect_async (GSocketClient *client,
data = g_slice_new (GSocketClientAsyncConnectData);
data->result = g_simple_async_result_new (G_OBJECT (client),
- callback, user_data,
- g_socket_client_connect_async);
+ callback, user_data,
+ g_socket_client_connect_async);
data->client = client;
if (cancellable)
data->cancellable = g_object_ref (cancellable);
@@ -630,6 +820,12 @@ g_socket_client_connect_async (GSocketClient *client,
* @user_data: user data for the callback
*
* This is the asynchronous version of g_socket_client_connect_to_host().
+ *
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_client_connect_to_host_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.22
**/
void
g_socket_client_connect_to_host_async (GSocketClient *client,
@@ -660,10 +856,23 @@ g_socket_client_connect_to_host_async (GSocketClient *client,
}
}
+/**
+ * g_socket_client_connect_finish:
+ * @client: a #GSocketClient.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occuring, or %NULL to
+ * ignore.
+ *
+ * Finishes an async connect operation. See g_socket_client_connect_async()
+ *
+ * Returns: a #GSocketConnection on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
GSocketConnection *
g_socket_client_connect_finish (GSocketClient *client,
- GAsyncResult *result,
- GError **error)
+ GAsyncResult *result,
+ GError **error)
{
GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
@@ -673,6 +882,19 @@ g_socket_client_connect_finish (GSocketClient *client,
return g_object_ref (g_simple_async_result_get_op_res_gpointer (simple));
}
+/**
+ * g_socket_client_connect_to_host_finish:
+ * @client: a #GSocketClient.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occuring, or %NULL to
+ * ignore.
+ *
+ * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
+ *
+ * Returns: a #GSocketConnection on success, %NULL on error.
+ *
+ * Since: 2.22
+ **/
GSocketConnection *
g_socket_client_connect_to_host_finish (GSocketClient *client,
GAsyncResult *result,
diff --git a/gio/gsocketclient.h b/gio/gsocketclient.h
index 98540a4..11146e0 100644
--- a/gio/gsocketclient.h
+++ b/gio/gsocketclient.h
@@ -1,22 +1,33 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
+ *
* Copyright © 2008, 2009 Codethink Limited
+ * Copyright © 2009 Red Hat, Inc
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* 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>
+ * 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 _gsocketclient_h_
-#define _gsocketclient_h_
+#ifndef __G_SOCKET_CLIENT_H__
+#define __G_SOCKET_CLIENT_H__
#include <gio/gsocketconnection.h>
#include <gio/gsocket.h>
@@ -35,15 +46,27 @@ G_BEGIN_DECLS
#define G_SOCKET_CLIENT_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), \
G_TYPE_SOCKET_CLIENT, GSocketClientClass))
+/**
+ * GSocketClient:
+ *
+ * A helper class for network clients to make connections.
+ *
+ * Since: 2.22
+ **/
+typedef struct _GSocketClient GSocketClient;
typedef struct _GSocketClientPrivate GSocketClientPrivate;
typedef struct _GSocketClientClass GSocketClientClass;
-typedef struct _GSocketClient GSocketClient;
struct _GSocketClientClass
{
GObjectClass parent_class;
- gpointer padding[5];
+ /* Padding for future expansion */
+ void (*_g_reserved1) (void);
+ void (*_g_reserved2) (void);
+ void (*_g_reserved3) (void);
+ void (*_g_reserved4) (void);
+ void (*_g_reserved5) (void);
};
struct _GSocketClient
@@ -52,7 +75,7 @@ struct _GSocketClient
GSocketClientPrivate *priv;
};
-GType g_socket_client_get_type (void);
+GType g_socket_client_get_type (void) G_GNUC_CONST;
GSocketClient *g_socket_client_new (void);
@@ -98,4 +121,4 @@ GSocketConnection * g_socket_client_connect_to_host_finish (GSocket
G_END_DECLS
-#endif /* _gsocketclient_h_ */
+#endif /* __G_SOCKET_CLIENT_H___ */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
