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/gnetworkservice.h>
40 #include <gio/gsocketaddress.h>
46 * SECTION:gsocketclient
47 * @short_description: Helper for connecting to a network service
49 * @see_also: #GSocketConnection, #GSocketListener
51 * #GSocketClient is a high-level utility class for connecting to a
52 * network host using a connection oriented socket type.
54 * You create a #GSocketClient object, set any options you want, then
55 * call a sync or async connect operation, which returns a #GSocketConnection
56 * subclass on success.
58 * The type of the #GSocketConnection object returned depends on the type of
59 * the underlying socket that is in use. For instance, for a TCP/IP connection
60 * it will be a #GTcpConnection.
66 G_DEFINE_TYPE (GSocketClient, g_socket_client, G_TYPE_OBJECT);
77 struct _GSocketClientPrivate
81 GSocketProtocol protocol;
82 GSocketAddress *local_address;
86 create_socket (GSocketClient *client,
87 GSocketAddress *dest_address,
93 family = client->priv->family;
94 if (family == G_SOCKET_FAMILY_INVALID &&
95 client->priv->local_address != NULL)
96 family = g_socket_address_get_family (client->priv->local_address);
97 if (family == G_SOCKET_FAMILY_INVALID)
98 family = g_socket_address_get_family (dest_address);
100 socket = g_socket_new (family,
102 client->priv->protocol,
107 if (client->priv->local_address)
109 if (!g_socket_bind (socket,
110 client->priv->local_address,
114 g_object_unref (socket);
123 g_socket_client_init (GSocketClient *client)
125 client->priv = G_TYPE_INSTANCE_GET_PRIVATE (client,
126 G_TYPE_SOCKET_CLIENT,
127 GSocketClientPrivate);
128 client->priv->type = G_SOCKET_TYPE_STREAM;
132 * g_socket_client_new:
134 * Creates a new #GSocketClient with the default options.
136 * Returns: a #GSocketClient.
137 * Free the returned object with g_object_unref().
142 g_socket_client_new (void)
144 return g_object_new (G_TYPE_SOCKET_CLIENT, NULL);
148 g_socket_client_finalize (GObject *object)
150 GSocketClient *client = G_SOCKET_CLIENT (object);
152 if (client->priv->local_address)
153 g_object_unref (client->priv->local_address);
155 if (G_OBJECT_CLASS (g_socket_client_parent_class)->finalize)
156 (*G_OBJECT_CLASS (g_socket_client_parent_class)->finalize) (object);
160 g_socket_client_get_property (GObject *object,
165 GSocketClient *client = G_SOCKET_CLIENT (object);
170 g_value_set_enum (value, client->priv->family);
174 g_value_set_enum (value, client->priv->type);
178 g_value_set_enum (value, client->priv->protocol);
181 case PROP_LOCAL_ADDRESS:
182 g_value_set_object (value, client->priv->local_address);
186 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
191 g_socket_client_set_property (GObject *object,
196 GSocketClient *client = G_SOCKET_CLIENT (object);
201 g_socket_client_set_family (client, g_value_get_enum (value));
205 g_socket_client_set_socket_type (client, g_value_get_enum (value));
209 g_socket_client_set_protocol (client, g_value_get_enum (value));
212 case PROP_LOCAL_ADDRESS:
213 g_socket_client_set_local_address (client, g_value_get_object (value));
217 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
222 * g_socket_client_get_family:
223 * @client: a #GSocketClient.
225 * Gets the socket family of the socket client.
227 * See g_socket_client_set_family() for details.
229 * Returns: a #GSocketFamily
234 g_socket_client_get_family (GSocketClient *client)
236 return client->priv->family;
240 * g_socket_client_set_family:
241 * @client: a #GSocketClient.
242 * @family: a #GSocketFamily
244 * Sets the socket family of the socket client.
245 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
246 * then the sockets created by this object will be of the specified
249 * This might be useful for instance if you want to force the local
250 * connection to be an ipv4 socket, even though the address might
251 * be an ipv6 mapped to ipv4 address.
256 g_socket_client_set_family (GSocketClient *client,
257 GSocketFamily family)
259 if (client->priv->family == family)
262 client->priv->family = family;
263 g_object_notify (G_OBJECT (client), "family");
267 * g_socket_client_get_socket_type:
268 * @client: a #GSocketClient.
270 * Gets the socket type of the socket client.
272 * See g_socket_client_set_socket_type() for details.
274 * Returns: a #GSocketFamily
279 g_socket_client_get_socket_type (GSocketClient *client)
281 return client->priv->type;
285 * g_socket_client_set_socket_type:
286 * @client: a #GSocketClient.
287 * @type: a #GSocketType
289 * Sets the socket type of the socket client.
290 * The sockets created by this object will be of the specified
293 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
294 * as GSocketClient is used for connection oriented services.
299 g_socket_client_set_socket_type (GSocketClient *client,
302 if (client->priv->type == type)
305 client->priv->type = type;
306 g_object_notify (G_OBJECT (client), "type");
310 * g_socket_client_get_protocol:
311 * @client: a #GSocketClient.
313 * Gets the protocol name type of the socket client.
315 * See g_socket_client_set_protocol() for details.
317 * Returns: a #GSocketProtocol
322 g_socket_client_get_protocol (GSocketClient *client)
324 return client->priv->protocol;
328 * g_socket_client_set_protocol:
329 * @client: a #GSocketClient.
330 * @protocol: a #GSocketProtocol
332 * Sets the protocol of the socket client.
333 * The sockets created by this object will use of the specified
336 * If @protocol is %0 that means to use the default
337 * protocol for the socket family and type.
342 g_socket_client_set_protocol (GSocketClient *client,
343 GSocketProtocol protocol)
345 if (client->priv->protocol == protocol)
348 client->priv->protocol = protocol;
349 g_object_notify (G_OBJECT (client), "protocol");
353 * g_socket_client_get_local_address:
354 * @client: a #GSocketClient.
356 * Gets the local address of the socket client.
358 * See g_socket_client_set_local_address() for details.
360 * Returns: a #GSocketAddres or %NULL. don't free
365 g_socket_client_get_local_address (GSocketClient *client)
367 return client->priv->local_address;
371 * g_socket_client_set_local_address:
372 * @client: a #GSocketClient.
373 * @address: a #GSocketAddress, or %NULL
375 * Sets the local address of the socket client.
376 * The sockets created by this object will bound to the
377 * specified address (if not %NULL) before connecting.
379 * This is useful if you want to ensure the the local
380 * side of the connection is on a specific port, or on
381 * a specific interface.
386 g_socket_client_set_local_address (GSocketClient *client,
387 GSocketAddress *address)
390 g_object_ref (address);
392 if (client->priv->local_address)
394 g_object_unref (client->priv->local_address);
396 client->priv->local_address = address;
397 g_object_notify (G_OBJECT (client), "local-address");
401 g_socket_client_class_init (GSocketClientClass *class)
403 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
405 g_type_class_add_private (class, sizeof (GSocketClientPrivate));
407 gobject_class->finalize = g_socket_client_finalize;
408 gobject_class->set_property = g_socket_client_set_property;
409 gobject_class->get_property = g_socket_client_get_property;
411 g_object_class_install_property (gobject_class, PROP_FAMILY,
412 g_param_spec_enum ("family",
414 P_("The sockets address family to use for socket construction"),
415 G_TYPE_SOCKET_FAMILY,
416 G_SOCKET_FAMILY_INVALID,
417 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
419 g_object_class_install_property (gobject_class, PROP_TYPE,
420 g_param_spec_enum ("type",
422 P_("The sockets type to use for socket construction"),
424 G_SOCKET_TYPE_STREAM,
425 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
427 g_object_class_install_property (gobject_class, PROP_PROTOCOL,
428 g_param_spec_enum ("protocol",
429 P_("Socket protocol"),
430 P_("The protocol to use for socket construction, or 0 for default"),
431 G_TYPE_SOCKET_PROTOCOL,
432 G_SOCKET_PROTOCOL_DEFAULT,
433 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
435 g_object_class_install_property (gobject_class, PROP_LOCAL_ADDRESS,
436 g_param_spec_object ("local-address",
438 P_("The local address constructed sockets will be bound to"),
439 G_TYPE_SOCKET_ADDRESS,
440 G_PARAM_CONSTRUCT | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
444 * g_socket_client_connect:
445 * @client: a #GSocketClient.
446 * @connectable: a #GSocketConnectable specifying the remote address.
447 * @cancellable: optional #GCancellable object, %NULL to ignore.
448 * @error: #GError for error reporting, or %NULL to ignore.
450 * Tries to resolve the @connectable and make a network connection to it..
452 * Upon a successful connection, a new #GSocketConnection is constructed
453 * and returned. The caller owns this new object and must drop their
454 * reference to it when finished with it.
456 * The type of the #GSocketConnection object returned depends on the type of
457 * the underlying socket that is used. For instance, for a TCP/IP connection
458 * it will be a #GTcpConnection.
460 * The socket created will be the same family as the the address that the
461 * @connectable resolves to, unless family is set with g_socket_client_set_family()
462 * or indirectly via g_socket_client_set_local_address(). The socket type
463 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
464 * g_socket_client_set_socket_type().
466 * If a local address is specified with g_socket_client_set_local_address() the
467 * socket will be bound to this address before connecting.
469 * Returns: a #GSocketConnection on success, %NULL on error.
474 g_socket_client_connect (GSocketClient *client,
475 GSocketConnectable *connectable,
476 GCancellable *cancellable,
479 GSocketConnection *connection = NULL;
480 GSocketAddressEnumerator *enumerator;
481 GError *last_error, *tmp_error;
484 enumerator = g_socket_connectable_enumerate (connectable);
485 while (connection == NULL)
487 GSocketAddress *address;
490 if (g_cancellable_is_cancelled (cancellable))
492 g_clear_error (error);
493 g_cancellable_set_error_if_cancelled (cancellable, error);
498 address = g_socket_address_enumerator_next (enumerator, cancellable,
504 g_clear_error (&last_error);
505 g_propagate_error (error, tmp_error);
509 g_propagate_error (error, tmp_error);
512 g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
513 _("Unknown error on connect"));
517 /* clear error from previous attempt */
518 g_clear_error (&last_error);
520 socket = create_socket (client, address, &last_error);
523 if (g_socket_connect (socket, address, &last_error))
524 connection = g_socket_connection_factory_create_connection (socket);
526 g_object_unref (socket);
529 g_object_unref (address);
531 g_object_unref (enumerator);
537 * g_socket_client_connect_to_host:
538 * @client: a #SocketClient
539 * @host_and_port: the name and optionally port of the host to connect to
540 * @default_port: the default port to connect to
541 * @cancellable: a #GCancellable, or %NULL
542 * @error: a pointer to a #GError, or %NULL
544 * This is a helper function for g_socket_client_connect().
546 * Attempts to create a TCP connection to the named host.
548 * @host_and_port may be in any of a number of recognised formats: an IPv6
549 * address, an IPv4 address, or a domain name (in which case a DNS
550 * lookup is performed). Quoting with [] is supported for all address
551 * types. A port override may be specified in the usual way with a
552 * colon. Ports may be given as decimal numbers or symbolic names (in
553 * which case an /etc/services lookup is performed).
555 * If no port override is given in @host_and_port then @default_port will be
556 * used as the port number to connect to.
558 * In general, @host_and_port is expected to be provided by the user (allowing
559 * them to give the hostname, and a port overide if necessary) and
560 * @default_port is expected to be provided by the application.
562 * In the case that an IP address is given, a single connection
563 * attempt is made. In the case that a name is given, multiple
564 * connection attempts may be made, in turn and according to the
565 * number of address records in DNS, until a connection succeeds.
567 * Upon a successful connection, a new #GSocketConnection is constructed
568 * and returned. The caller owns this new object and must drop their
569 * reference to it when finished with it.
571 * In the event of any failure (DNS error, service not found, no hosts
572 * connectable) %NULL is returned and @error (if non-%NULL) is set
575 Returns: a #GSocketConnection on success, %NULL on error.
580 g_socket_client_connect_to_host (GSocketClient *client,
581 const char *host_and_port,
583 GCancellable *cancellable,
586 GSocketConnectable *connectable;
587 GSocketConnection *connection;
589 connectable = g_network_address_parse (host_and_port, default_port, error);
590 if (connectable == NULL)
593 connection = g_socket_client_connect (client, connectable,
595 g_object_unref (connectable);
601 * g_socket_client_connect_to_service:
602 * @client: a #GSocketConnection
603 * @domain: a domain name
604 * @service: the name of the service to connect to
605 * @cancellable: a #GCancellable, or %NULL
606 * @error: a pointer to a #GError, or %NULL
607 * @returns: a #GSocketConnection if successful, or %NULL on error
609 * Attempts to create a TCP connection to a service.
611 * This call looks up the SRV record for @service at @domain for the
612 * "tcp" protocol. It then attempts to connect, in turn, to each of
613 * the hosts providing the service until either a connection succeeds
614 * or there are no hosts remaining.
616 * Upon a successful connection, a new #GSocketConnection is constructed
617 * and returned. The caller owns this new object and must drop their
618 * reference to it when finished with it.
620 * In the event of any failure (DNS error, service not found, no hosts
621 * connectable) %NULL is returned and @error (if non-%NULL) is set
625 g_socket_client_connect_to_service (GSocketClient *client,
628 GCancellable *cancellable,
631 GSocketConnectable *connectable;
632 GSocketConnection *connection;
634 connectable = g_network_service_new (service, "tcp", domain);
635 connection = g_socket_client_connect (client, connectable,
637 g_object_unref (connectable);
644 GSimpleAsyncResult *result;
645 GCancellable *cancellable;
646 GSocketClient *client;
648 GSocketAddressEnumerator *enumerator;
649 GSocket *current_socket;
652 } GSocketClientAsyncConnectData;
655 g_socket_client_async_connect_complete (GSocketClientAsyncConnectData *data)
657 GSocketConnection *connection;
659 if (data->last_error)
661 g_simple_async_result_set_from_error (data->result, data->last_error);
662 g_error_free (data->last_error);
666 g_assert (data->current_socket);
668 g_socket_set_blocking (data->current_socket, TRUE);
670 connection = g_socket_connection_factory_create_connection (data->current_socket);
671 g_simple_async_result_set_op_res_gpointer (data->result,
676 g_simple_async_result_complete (data->result);
677 g_object_unref (data->result);
682 g_socket_client_enumerator_callback (GObject *object,
683 GAsyncResult *result,
687 set_last_error (GSocketClientAsyncConnectData *data,
690 g_clear_error (&data->last_error);
691 data->last_error = error;
695 g_socket_client_socket_callback (GSocket *socket,
696 GIOCondition condition,
697 GSocketClientAsyncConnectData *data)
699 GError *error = NULL;
701 if (g_cancellable_is_cancelled (data->cancellable))
703 /* Cancelled, return done with last error being cancelled */
704 g_clear_error (&data->last_error);
705 g_object_unref (data->current_socket);
706 data->current_socket = NULL;
707 g_cancellable_set_error_if_cancelled (data->cancellable,
712 /* socket is ready for writing means connect done, did it succeed? */
713 if (!g_socket_check_connect_result (data->current_socket, &error))
715 set_last_error (data, error);
718 g_socket_address_enumerator_next_async (data->enumerator,
720 g_socket_client_enumerator_callback,
727 g_socket_client_async_connect_complete (data);
733 g_socket_client_enumerator_callback (GObject *object,
734 GAsyncResult *result,
737 GSocketClientAsyncConnectData *data = user_data;
738 GSocketAddress *address;
740 GError *tmp_error = NULL;
742 if (g_cancellable_is_cancelled (data->cancellable))
744 g_clear_error (&data->last_error);
745 g_cancellable_set_error_if_cancelled (data->cancellable, &data->last_error);
746 g_socket_client_async_connect_complete (data);
750 address = g_socket_address_enumerator_next_finish (data->enumerator,
756 set_last_error (data, tmp_error);
757 else if (data->last_error == NULL)
758 g_set_error (&data->last_error, G_IO_ERROR, G_IO_ERROR_FAILED,
759 _("Unknown error on connect"));
761 g_socket_client_async_connect_complete (data);
765 g_clear_error (&data->last_error);
767 socket = create_socket (data->client, address, &data->last_error);
770 g_socket_set_blocking (socket, FALSE);
771 if (g_socket_connect (socket, address, &tmp_error))
773 data->current_socket = socket;
774 g_socket_client_async_connect_complete (data);
776 g_object_unref (address);
779 else if (g_error_matches (tmp_error, G_IO_ERROR, G_IO_ERROR_PENDING))
783 data->current_socket = socket;
784 g_error_free (tmp_error);
786 source = g_socket_create_source (socket, G_IO_OUT,
788 g_source_set_callback (source,
789 (GSourceFunc) g_socket_client_socket_callback,
791 g_source_attach (source, NULL);
792 g_source_unref (source);
794 g_object_unref (address);
799 data->last_error = tmp_error;
800 g_object_unref (socket);
802 g_object_unref (address);
805 g_socket_address_enumerator_next_async (data->enumerator,
807 g_socket_client_enumerator_callback,
812 * g_socket_client_connect_async:
813 * @client: a #GTcpClient
814 * @connectable: a #GSocketConnectable specifying the remote address.
815 * @cancellable: a #GCancellable, or %NULL
816 * @callback: a #GAsyncReadyCallback
817 * @user_data: user data for the callback
819 * This is the asynchronous version of g_socket_client_connect().
821 * When the operation is finished @callback will be
822 * called. You can then call g_socket_client_connect_finish() to get
823 * the result of the operation.
828 g_socket_client_connect_async (GSocketClient *client,
829 GSocketConnectable *connectable,
830 GCancellable *cancellable,
831 GAsyncReadyCallback callback,
834 GSocketClientAsyncConnectData *data;
836 g_return_if_fail (G_IS_SOCKET_CLIENT (client));
838 data = g_slice_new (GSocketClientAsyncConnectData);
840 data->result = g_simple_async_result_new (G_OBJECT (client),
842 g_socket_client_connect_async);
843 data->client = client;
845 data->cancellable = g_object_ref (cancellable);
847 data->cancellable = NULL;
848 data->last_error = NULL;
849 data->enumerator = g_socket_connectable_enumerate (connectable);
851 g_socket_address_enumerator_next_async (data->enumerator, cancellable,
852 g_socket_client_enumerator_callback,
857 * g_socket_client_connect_to_host_async:
858 * @client: a #GTcpClient
859 * @host_and_port: the name and optionally the port of the host to connect to
860 * @default_port: the default port to connect to
861 * @cancellable: a #GCancellable, or %NULL
862 * @callback: a #GAsyncReadyCallback
863 * @user_data: user data for the callback
865 * This is the asynchronous version of g_socket_client_connect_to_host().
867 * When the operation is finished @callback will be
868 * called. You can then call g_socket_client_connect_to_host_finish() to get
869 * the result of the operation.
874 g_socket_client_connect_to_host_async (GSocketClient *client,
875 const char *host_and_port,
877 GCancellable *cancellable,
878 GAsyncReadyCallback callback,
881 GSocketConnectable *connectable;
885 connectable = g_network_address_parse (host_and_port, default_port,
887 if (connectable == NULL)
889 g_simple_async_report_gerror_in_idle (G_OBJECT (client),
890 callback, user_data, error);
891 g_error_free (error);
895 g_socket_client_connect_async (client,
896 connectable, cancellable,
897 callback, user_data);
898 g_object_unref (connectable);
903 * g_socket_client_connect_to_service_async:
904 * @client: a #GSocketClient
905 * @domain: a domain name
906 * @service: the name of the service to connect to
907 * @cancellable: a #GCancellable, or %NULL
908 * @callback: a #GAsyncReadyCallback
909 * @user_data: user data for the callback
911 * This is the asynchronous version of
912 * g_socket_client_connect_to_service().
915 g_socket_client_connect_to_service_async (GSocketClient *client,
918 GCancellable *cancellable,
919 GAsyncReadyCallback callback,
922 GSocketConnectable *connectable;
924 connectable = g_network_service_new (service, "tcp", domain);
925 g_socket_client_connect_async (client,
926 connectable, cancellable,
927 callback, user_data);
928 g_object_unref (connectable);
932 * g_socket_client_connect_finish:
933 * @client: a #GSocketClient.
934 * @result: a #GAsyncResult.
935 * @error: a #GError location to store the error occuring, or %NULL to
938 * Finishes an async connect operation. See g_socket_client_connect_async()
940 * Returns: a #GSocketConnection on success, %NULL on error.
945 g_socket_client_connect_finish (GSocketClient *client,
946 GAsyncResult *result,
949 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
951 if (g_simple_async_result_propagate_error (simple, error))
954 return g_object_ref (g_simple_async_result_get_op_res_gpointer (simple));
958 * g_socket_client_connect_to_host_finish:
959 * @client: a #GSocketClient.
960 * @result: a #GAsyncResult.
961 * @error: a #GError location to store the error occuring, or %NULL to
964 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
966 * Returns: a #GSocketConnection on success, %NULL on error.
971 g_socket_client_connect_to_host_finish (GSocketClient *client,
972 GAsyncResult *result,
975 return g_socket_client_connect_finish (client, result, error);
979 * g_socket_client_connect_to_service_finish:
980 * @client: a #GSocketClient.
981 * @result: a #GAsyncResult.
982 * @error: a #GError location to store the error occuring, or %NULL to
985 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
987 * Returns: a #GSocketConnection on success, %NULL on error.
992 g_socket_client_connect_to_service_finish (GSocketClient *client,
993 GAsyncResult *result,
996 return g_socket_client_connect_finish (client, result, error);
999 #define __G_SOCKET_CLIENT_C__
1000 #include "gioaliasdef.c"