:right-sidebar: True

SocketConnectable
===================================================================

.. currentmodule:: gi.repository.Gio





.. class:: SocketConnectable(*args, **kwargs)
   :no-contents-entry:





Implementations: :class:`~gi.repository.Gio.InetSocketAddress`, :class:`~gi.repository.Gio.NativeSocketAddress`, :class:`~gi.repository.Gio.NetworkAddress`, :class:`~gi.repository.Gio.NetworkService`, :class:`~gi.repository.Gio.ProxyAddress`, :class:`~gi.repository.Gio.SocketAddress`, :class:`~gi.repository.Gio.UnixSocketAddress`


Objects that describe one or more potential socket endpoints
implement ``GSocketConnectable``\. Callers can then use
:obj:`~gi.repository.Gio.SocketConnectable.enumerate` to get a
:obj:`~gi.repository.Gio.SocketAddressEnumerator` to try out each socket address in turn
until one succeeds, as shown in the sample code below.


.. code-block:: c
    :dedent:

    MyConnectionType *
    connect_to_host (const char    *hostname,
                     guint16        port,
                     GCancellable  *cancellable,
                     GError       **error)
    {
      MyConnection *conn = NULL;
      GSocketConnectable *addr;
      GSocketAddressEnumerator *enumerator;
      GSocketAddress *sockaddr;
      GError *conn_error = NULL;

      addr = g_network_address_new (hostname, port);
      enumerator = g_socket_connectable_enumerate (addr);
      g_object_unref (addr);

      // Try each sockaddr until we succeed. Record the first connection error,
      // but not any further ones (since they'll probably be basically the same
      // as the first).
      while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
        {
          conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
          g_object_unref (sockaddr);
        }
      g_object_unref (enumerator);

      if (conn)
        {
          if (conn_error)
            {
              // We couldn't connect to the first address, but we succeeded
              // in connecting to a later address.
              g_error_free (conn_error);
            }
          return conn;
        }
      else if (error)
        {
          /// Either initial lookup failed, or else the caller cancelled us.
          if (conn_error)
            g_error_free (conn_error);
          return NULL;
        }
      else
        {
          g_error_propagate (error, conn_error);
          return NULL;
        }
    }




Methods
-------

.. rst-class:: interim-class

.. class:: SocketConnectable
   :no-index:


   .. method:: enumerate() -> ~gi.repository.Gio.SocketAddressEnumerator

      Creates a :obj:`~gi.repository.Gio.SocketAddressEnumerator` for ``connectable``\.


      .. versionadded:: 2.22








   .. method:: proxy_enumerate() -> ~gi.repository.Gio.SocketAddressEnumerator

      Creates a :obj:`~gi.repository.Gio.SocketAddressEnumerator` for ``connectable`` that will
      return a :obj:`~gi.repository.Gio.ProxyAddress` for each of its addresses that you must connect
      to via a proxy.

      If ``connectable`` does not implement
      :func:`~gi.repository.Gio.SocketConnectable.proxy_enumerate`, this will fall back to
      calling :func:`~gi.repository.Gio.SocketConnectable.enumerate`.


      .. versionadded:: 2.26








   .. method:: to_string() -> str

      Format a :obj:`~gi.repository.Gio.SocketConnectable` as a string. This is a human-readable format for
      use in debugging output, and is not a stable serialization format. It is not
      suitable for use in user interfaces as it exposes too much information for a
      user.

      If the :obj:`~gi.repository.Gio.SocketConnectable` implementation does not support string formatting,
      the implementation’s type name will be returned as a fallback.


      .. versionadded:: 2.48
















Virtual Methods
---------------

.. rst-class:: interim-class

.. class:: SocketConnectable
   :no-index:
   

   .. method:: do_enumerate() -> ~gi.repository.Gio.SocketAddressEnumerator

      Creates a :obj:`~gi.repository.Gio.SocketAddressEnumerator` for ``connectable``\.


      .. versionadded:: 2.22








   .. method:: do_proxy_enumerate() -> ~gi.repository.Gio.SocketAddressEnumerator

      Creates a :obj:`~gi.repository.Gio.SocketAddressEnumerator` for ``connectable`` that will
      return a :obj:`~gi.repository.Gio.ProxyAddress` for each of its addresses that you must connect
      to via a proxy.

      If ``connectable`` does not implement
      :func:`~gi.repository.Gio.SocketConnectable.proxy_enumerate`, this will fall back to
      calling :func:`~gi.repository.Gio.SocketConnectable.enumerate`.


      .. versionadded:: 2.26








   .. method:: do_to_string() -> str

      Format a :obj:`~gi.repository.Gio.SocketConnectable` as a string. This is a human-readable format for
      use in debugging output, and is not a stable serialization format. It is not
      suitable for use in user interfaces as it exposes too much information for a
      user.

      If the :obj:`~gi.repository.Gio.SocketConnectable` implementation does not support string formatting,
      the implementation’s type name will be returned as a fallback.


      .. versionadded:: 2.48