1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2008, 2009 codethink
4 * Copyright © 2009 Red Hat, Inc
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General
17 * Public License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
19 * Boston, MA 02111-1307, USA.
21 * Authors: Ryan Lortie <desrt@desrt.ca>
22 * Alexander Larsson <alexl@redhat.com>
26 #include "gsocketclient.h"
30 #include <gio/gioenumtypes.h>
31 #include <gio/gsocketaddressenumerator.h>
32 #include <gio/gsocketconnectable.h>
33 #include <gio/gsocketconnection.h>
34 #include <gio/gsimpleasyncresult.h>
35 #include <gio/gcancellable.h>
36 #include <gio/gioerror.h>
37 #include <gio/gsocket.h>
38 #include <gio/gnetworkaddress.h>
39 #include <gio/gsocketaddress.h>
45 * SECTION:gsocketclient
46 * @short_description: Helper for connecting to a network service
48 * @see_also: #GSocketConnection, #GSocketListener
50 * #GSocketClient is a high-level utility class for connecting to a
51 * network host using a connection oriented socket type.
53 * You create a #GSocketClient object, set any options you want, then
54 * call a sync or async connect operation, which returns a #GSocketConnection
55 * subclass on success.
57 * The type of the #GSocketConnection object returned depends on the type of
58 * the underlying socket that is in use. For instance, for a TCP/IP connection
59 * it will be a #GTcpConnection.
65 G_DEFINE_TYPE (GSocketClient, g_socket_client, G_TYPE_OBJECT);
76 struct _GSocketClientPrivate
80 GSocketProtocol protocol;
81 GSocketAddress *local_address;
85 create_socket (GSocketClient *client,
86 GSocketAddress *dest_address,
92 family = client->priv->family;
93 if (family == G_SOCKET_FAMILY_INVALID &&
94 client->priv->local_address != NULL)
95 family = g_socket_address_get_family (client->priv->local_address);
96 if (family == G_SOCKET_FAMILY_INVALID)
97 family = g_socket_address_get_family (dest_address);
99 socket = g_socket_new (family,
101 client->priv->protocol,
106 if (client->priv->local_address)
108 if (!g_socket_bind (socket,
109 client->priv->local_address,
113 g_object_unref (socket);
122 g_socket_client_init (GSocketClient *client)
124 client->priv = G_TYPE_INSTANCE_GET_PRIVATE (client,
125 G_TYPE_SOCKET_CLIENT,
126 GSocketClientPrivate);
127 client->priv->type = G_SOCKET_TYPE_STREAM;
131 * g_socket_client_new:
133 * Creates a new #GSocketClient with the default options.
135 * Returns: a #GSocketClient.
136 * Free the returned object with g_object_unref().
141 g_socket_client_new (void)
143 return g_object_new (G_TYPE_SOCKET_CLIENT, NULL);
147 g_socket_client_finalize (GObject *object)
149 GSocketClient *client = G_SOCKET_CLIENT (object);
151 if (client->priv->local_address)
152 g_object_unref (client->priv->local_address);
154 if (G_OBJECT_CLASS (g_socket_client_parent_class)->finalize)
155 (*G_OBJECT_CLASS (g_socket_client_parent_class)->finalize) (object);
159 g_socket_client_get_property (GObject *object,
164 GSocketClient *client = G_SOCKET_CLIENT (object);
169 g_value_set_enum (value, client->priv->family);
173 g_value_set_enum (value, client->priv->type);
177 g_value_set_enum (value, client->priv->protocol);
180 case PROP_LOCAL_ADDRESS:
181 g_value_set_object (value, client->priv->local_address);
185 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
190 g_socket_client_set_property (GObject *object,
195 GSocketClient *client = G_SOCKET_CLIENT (object);
200 g_socket_client_set_family (client, g_value_get_enum (value));
204 g_socket_client_set_socket_type (client, g_value_get_enum (value));
208 g_socket_client_set_protocol (client, g_value_get_enum (value));
211 case PROP_LOCAL_ADDRESS:
212 g_socket_client_set_local_address (client, g_value_get_object (value));
216 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
221 * g_socket_client_get_family:
222 * @client: a #GSocketClient.
224 * Gets the socket family of the socket client.
226 * See g_socket_client_set_family() for details.
228 * Returns: a #GSocketFamily
233 g_socket_client_get_family (GSocketClient *client)
235 return client->priv->family;
239 * g_socket_client_set_family:
240 * @client: a #GSocketClient.
241 * @family: a #GSocketFamily
243 * Sets the socket family of the socket client.
244 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
245 * then the sockets created by this object will be of the specified
248 * This might be useful for instance if you want to force the local
249 * connection to be an ipv4 socket, even though the address might
250 * be an ipv6 mapped to ipv4 address.
255 g_socket_client_set_family (GSocketClient *client,
256 GSocketFamily family)
258 if (client->priv->family == family)
261 client->priv->family = family;
262 g_object_notify (G_OBJECT (client), "family");
266 * g_socket_client_get_socket_type:
267 * @client: a #GSocketClient.
269 * Gets the socket type of the socket client.
271 * See g_socket_client_set_socket_type() for details.
273 * Returns: a #GSocketFamily
278 g_socket_client_get_socket_type (GSocketClient *client)
280 return client->priv->type;
284 * g_socket_client_set_socket_type:
285 * @client: a #GSocketClient.
286 * @type: a #GSocketType
288 * Sets the socket type of the socket client.
289 * The sockets created by this object will be of the specified
292 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
293 * as GSocketClient is used for connection oriented services.
298 g_socket_client_set_socket_type (GSocketClient *client,
301 if (client->priv->type == type)
304 client->priv->type = type;
305 g_object_notify (G_OBJECT (client), "type");
309 * g_socket_client_get_protocol:
310 * @client: a #GSocketClient.
312 * Gets the protocol name type of the socket client.
314 * See g_socket_client_set_protocol() for details.
316 * Returns: a #GSocketProtocol
321 g_socket_client_get_protocol (GSocketClient *client)
323 return client->priv->protocol;
327 * g_socket_client_set_protocol:
328 * @client: a #GSocketClient.
329 * @protocol: a #GSocketProtocol
331 * Sets the protocol of the socket client.
332 * The sockets created by this object will use of the specified
335 * If @protocol is %0 that means to use the default
336 * protocol for the socket family and type.
341 g_socket_client_set_protocol (GSocketClient *client,
342 GSocketProtocol protocol)
344 if (client->priv->protocol == protocol)
347 client->priv->protocol = protocol;
348 g_object_notify (G_OBJECT (client), "protocol");
352 * g_socket_client_get_local_address:
353 * @client: a #GSocketClient.
355 * Gets the local address of the socket client.
357 * See g_socket_client_set_local_address() for details.
359 * Returns: a #GSocketAddres or %NULL. don't free
364 g_socket_client_get_local_address (GSocketClient *client)
366 return client->priv->local_address;
370 * g_socket_client_set_local_address:
371 * @client: a #GSocketClient.
372 * @address: a #GSocketAddress, or %NULL
374 * Sets the local address of the socket client.
375 * The sockets created by this object will bound to the
376 * specified address (if not %NULL) before connecting.
378 * This is useful if you want to ensure the the local
379 * side of the connection is on a specific port, or on
380 * a specific interface.
385 g_socket_client_set_local_address (GSocketClient *client,
386 GSocketAddress *address)
389 g_object_ref (address);
391 if (client->priv->local_address)
393 g_object_unref (client->priv->local_address);
395 client->priv->local_address = address;
396 g_object_notify (G_OBJECT (client), "local-address");
400 g_socket_client_class_init (GSocketClientClass *class)
402 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
404 g_type_class_add_private (class, sizeof (GSocketClientPrivate));
406 gobject_class->finalize = g_socket_client_finalize;
407 gobject_class->set_property = g_socket_client_set_property;
408 gobject_class->get_property = g_socket_client_get_property;
410 g_object_class_install_property (gobject_class, PROP_FAMILY,
411 g_param_spec_enum ("family",
413 P_("The sockets address family to use for socket construction"),
414 G_TYPE_SOCKET_FAMILY,
415 G_SOCKET_FAMILY_INVALID,
416 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
418 g_object_class_install_property (gobject_class, PROP_TYPE,
419 g_param_spec_enum ("type",
421 P_("The sockets type to use for socket construction"),
423 G_SOCKET_TYPE_STREAM,
424 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
426 g_object_class_install_property (gobject_class, PROP_PROTOCOL,
427 g_param_spec_enum ("protocol",
428 P_("Socket protocol"),
429 P_("The protocol to use for socket construction, or 0 for default"),
430 G_TYPE_SOCKET_PROTOCOL,
431 G_SOCKET_PROTOCOL_DEFAULT,
432 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
434 g_object_class_install_property (gobject_class, PROP_LOCAL_ADDRESS,
435 g_param_spec_object ("local-address",
437 P_("The local address constructed sockets will be bound to"),
438 G_TYPE_SOCKET_ADDRESS,
439 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
443 * g_socket_client_connect:
444 * @client: a #GSocketClient.
445 * @connectable: a #GSocketConnectable specifying the remote address.
446 * @cancellable: optional #GCancellable object, %NULL to ignore.
447 * @error: #GError for error reporting, or %NULL to ignore.
449 * Tries to resolve the @connectable and make a network connection to it..
451 * Upon a successful connection, a new #GSocketConnection is constructed
452 * and returned. The caller owns this new object and must drop their
453 * reference to it when finished with it.
455 * The type of the #GSocketConnection object returned depends on the type of
456 * the underlying socket that is used. For instance, for a TCP/IP connection
457 * it will be a #GTcpConnection.
459 * The socket created will be the same family as the the address that the
460 * @connectable resolves to, unless family is set with g_socket_client_set_family()
461 * or indirectly via g_socket_client_set_local_address(). The socket type
462 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
463 * g_socket_client_set_socket_type().
465 * If a local address is specified with g_socket_client_set_local_address() the
466 * socket will be bound to this address before connecting.
468 * Returns: a #GSocketConnection on success, %NULL on error.
473 g_socket_client_connect (GSocketClient *client,
474 GSocketConnectable *connectable,
475 GCancellable *cancellable,
478 GSocketConnection *connection = NULL;
479 GSocketAddressEnumerator *enumerator;
480 GError *last_error, *tmp_error;
483 enumerator = g_socket_connectable_enumerate (connectable);
484 while (connection == NULL)
486 GSocketAddress *address;
489 if (g_cancellable_is_cancelled (cancellable))
491 g_clear_error (error);
492 g_cancellable_set_error_if_cancelled (cancellable, error);
497 address = g_socket_address_enumerator_next (enumerator, cancellable,
503 g_clear_error (&last_error);
504 g_propagate_error (error, tmp_error);
508 g_propagate_error (error, tmp_error);
511 g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
512 _("Unknown error on connect"));
516 /* clear error from previous attempt */
517 g_clear_error (&last_error);
519 socket = create_socket (client, address, &last_error);
522 if (g_socket_connect (socket, address, &last_error))
523 connection = g_socket_connection_factory_create_connection (socket);
525 g_object_unref (socket);
528 g_object_unref (address);
530 g_object_unref (enumerator);
536 * g_socket_client_connect_to_host:
537 * @client: a #SocketClient
538 * @host_and_port: the name and optionally port of the host to connect to
539 * @default_port: the default port to connect to
540 * @cancellable: a #GCancellable, or %NULL
541 * @error: a pointer to a #GError, or %NULL
543 * This is a helper function for g_socket_client_connect().
545 * Attempts to create a TCP connection to the named host.
547 * @host_and_port may be in any of a number of recognised formats: an IPv6
548 * address, an IPv4 address, or a domain name (in which case a DNS
549 * lookup is performed). Quoting with [] is supported for all address
550 * types. A port override may be specified in the usual way with a
551 * colon. Ports may be given as decimal numbers or symbolic names (in
552 * which case an /etc/services lookup is performed).
554 * If no port override is given in @host_and_port then @default_port will be
555 * used as the port number to connect to.
557 * In general, @host_and_port is expected to be provided by the user (allowing
558 * them to give the hostname, and a port overide if necessary) and
559 * @default_port is expected to be provided by the application.
561 * In the case that an IP address is given, a single connection
562 * attempt is made. In the case that a name is given, multiple
563 * connection attempts may be made, in turn and according to the
564 * number of address records in DNS, until a connection succeeds.
566 * Upon a successful connection, a new #GSocketConnection is constructed
567 * and returned. The caller owns this new object and must drop their
568 * reference to it when finished with it.
570 * In the event of any failure (DNS error, service not found, no hosts
571 * connectable) %NULL is returned and @error (if non-%NULL) is set
574 Returns: a #GSocketConnection on success, %NULL on error.
579 g_socket_client_connect_to_host (GSocketClient *client,
580 const char *host_and_port,
582 GCancellable *cancellable,
585 GSocketConnectable *connectable;
586 GSocketConnection *connection;
588 connectable = g_network_address_parse (host_and_port, default_port, error);
589 if (connectable == NULL)
592 connection = g_socket_client_connect (client, connectable,
594 g_object_unref (connectable);
601 GSimpleAsyncResult *result;
602 GCancellable *cancellable;
603 GSocketClient *client;
605 GSocketAddressEnumerator *enumerator;
606 GSocket *current_socket;
609 } GSocketClientAsyncConnectData;
612 g_socket_client_async_connect_complete (GSocketClientAsyncConnectData *data)
614 GSocketConnection *connection;
616 if (data->last_error)
618 g_simple_async_result_set_from_error (data->result, data->last_error);
619 g_error_free (data->last_error);
623 g_assert (data->current_socket);
625 g_socket_set_blocking (data->current_socket, TRUE);
627 connection = g_socket_connection_factory_create_connection (data->current_socket);
628 g_simple_async_result_set_op_res_gpointer (data->result,
633 g_simple_async_result_complete (data->result);
634 g_object_unref (data->result);
639 g_socket_client_enumerator_callback (GObject *object,
640 GAsyncResult *result,
644 set_last_error (GSocketClientAsyncConnectData *data,
647 g_clear_error (&data->last_error);
648 data->last_error = error;
652 g_socket_client_socket_callback (GSocket *socket,
653 GIOCondition condition,
654 GSocketClientAsyncConnectData *data)
656 GError *error = NULL;
658 if (g_cancellable_is_cancelled (data->cancellable))
660 /* Cancelled, return done with last error being cancelled */
661 g_clear_error (&data->last_error);
662 g_object_unref (data->current_socket);
663 data->current_socket = NULL;
664 g_cancellable_set_error_if_cancelled (data->cancellable,
669 /* socket is ready for writing means connect done, did it succeed? */
670 if (!g_socket_check_connect_result (data->current_socket, &error))
672 set_last_error (data, error);
675 g_socket_address_enumerator_next_async (data->enumerator,
677 g_socket_client_enumerator_callback,
684 g_socket_client_async_connect_complete (data);
690 g_socket_client_enumerator_callback (GObject *object,
691 GAsyncResult *result,
694 GSocketClientAsyncConnectData *data = user_data;
695 GSocketAddress *address;
697 GError *tmp_error = NULL;
699 if (g_cancellable_is_cancelled (data->cancellable))
701 g_clear_error (&data->last_error);
702 g_cancellable_set_error_if_cancelled (data->cancellable, &data->last_error);
703 g_socket_client_async_connect_complete (data);
707 address = g_socket_address_enumerator_next_finish (data->enumerator,
713 set_last_error (data, tmp_error);
714 else if (data->last_error == NULL)
715 g_set_error (&data->last_error, G_IO_ERROR, G_IO_ERROR_FAILED,
716 _("Unknown error on connect"));
718 g_socket_client_async_connect_complete (data);
722 g_clear_error (&data->last_error);
724 socket = create_socket (data->client, address, &data->last_error);
727 g_socket_set_blocking (socket, FALSE);
728 if (g_socket_connect (socket, address, &tmp_error))
730 data->current_socket = socket;
731 g_socket_client_async_connect_complete (data);
733 g_object_unref (address);
736 else if (g_error_matches (tmp_error, G_IO_ERROR, G_IO_ERROR_PENDING))
740 data->current_socket = socket;
741 g_error_free (tmp_error);
743 source = g_socket_create_source (socket, G_IO_OUT,
745 g_source_set_callback (source,
746 (GSourceFunc) g_socket_client_socket_callback,
748 g_source_attach (source, NULL);
749 g_source_unref (source);
751 g_object_unref (address);
756 data->last_error = tmp_error;
757 g_object_unref (socket);
759 g_object_unref (address);
762 g_socket_address_enumerator_next_async (data->enumerator,
764 g_socket_client_enumerator_callback,
769 * g_socket_client_connect_async:
770 * @client: a #GTcpClient
771 * @connectable: a #GSocketConnectable specifying the remote address.
772 * @cancellable: a #GCancellable, or %NULL
773 * @callback: a #GAsyncReadyCallback
774 * @user_data: user data for the callback
776 * This is the asynchronous version of g_socket_client_connect().
778 * When the operation is finished @callback will be
779 * called. You can then call g_socket_client_connect_finish() to get
780 * the result of the operation.
785 g_socket_client_connect_async (GSocketClient *client,
786 GSocketConnectable *connectable,
787 GCancellable *cancellable,
788 GAsyncReadyCallback callback,
791 GSocketClientAsyncConnectData *data;
793 g_return_if_fail (G_IS_SOCKET_CLIENT (client));
795 data = g_slice_new (GSocketClientAsyncConnectData);
797 data->result = g_simple_async_result_new (G_OBJECT (client),
799 g_socket_client_connect_async);
800 data->client = client;
802 data->cancellable = g_object_ref (cancellable);
804 data->cancellable = NULL;
805 data->last_error = NULL;
806 data->enumerator = g_socket_connectable_enumerate (connectable);
808 g_socket_address_enumerator_next_async (data->enumerator, cancellable,
809 g_socket_client_enumerator_callback,
814 * g_socket_client_connect_to_host_async:
815 * @client: a #GTcpClient
816 * @host_and_port: the name and optionally the port of the host to connect to
817 * @default_port: the default port to connect to
818 * @cancellable: a #GCancellable, or %NULL
819 * @callback: a #GAsyncReadyCallback
820 * @user_data: user data for the callback
822 * This is the asynchronous version of g_socket_client_connect_to_host().
824 * When the operation is finished @callback will be
825 * called. You can then call g_socket_client_connect_to_host_finish() to get
826 * the result of the operation.
831 g_socket_client_connect_to_host_async (GSocketClient *client,
832 const char *host_and_port,
834 GCancellable *cancellable,
835 GAsyncReadyCallback callback,
838 GSocketConnectable *connectable;
842 connectable = g_network_address_parse (host_and_port, default_port,
844 if (connectable == NULL)
846 g_simple_async_report_gerror_in_idle (G_OBJECT (client),
847 callback, user_data, error);
848 g_error_free (error);
852 g_socket_client_connect_async (client,
853 connectable, cancellable,
854 callback, user_data);
855 g_object_unref (connectable);
860 * g_socket_client_connect_finish:
861 * @client: a #GSocketClient.
862 * @result: a #GAsyncResult.
863 * @error: a #GError location to store the error occuring, or %NULL to
866 * Finishes an async connect operation. See g_socket_client_connect_async()
868 * Returns: a #GSocketConnection on success, %NULL on error.
873 g_socket_client_connect_finish (GSocketClient *client,
874 GAsyncResult *result,
877 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
879 if (g_simple_async_result_propagate_error (simple, error))
882 return g_object_ref (g_simple_async_result_get_op_res_gpointer (simple));
886 * g_socket_client_connect_to_host_finish:
887 * @client: a #GSocketClient.
888 * @result: a #GAsyncResult.
889 * @error: a #GError location to store the error occuring, or %NULL to
892 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
894 * Returns: a #GSocketConnection on success, %NULL on error.
899 g_socket_client_connect_to_host_finish (GSocketClient *client,
900 GAsyncResult *result,
903 return g_socket_client_connect_finish (client, result, error);
906 #define __G_SOCKET_CLIENT_C__
907 #include "gioaliasdef.c"