:right-sidebar: True SocketClient =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.22 .. class:: SocketClient(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``GSocketClient`` is a lightweight 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, and then call a sync or async connect operation, which returns a :obj:`~gi.repository.Gio.SocketConnection` subclass on success. The type of the :obj:`~gi.repository.Gio.SocketConnection` 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 :obj:`~gi.repository.Gio.TcpConnection`\. As ``GSocketClient`` is a lightweight object, you don't need to cache it. You can just create a new one any time you need one. Constructors ------------ .. rst-class:: interim-class .. class:: SocketClient :no-index: .. classmethod:: new() -> ~gi.repository.Gio.SocketClient Creates a new :obj:`~gi.repository.Gio.SocketClient` with the default options. .. versionadded:: 2.22 Methods ------- .. rst-class:: interim-class .. class:: SocketClient :no-index: .. method:: add_application_proxy(protocol: str) -> None Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the :obj:`~gi.repository.Gio.ProxyResolver`\, :obj:`~gi.repository.Gio.SocketClient` will consider this protocol as supported but will not try to find a :obj:`~gi.repository.Gio.Proxy` instance to handle handshaking. The application must check for this case by calling :func:`~gi.repository.Gio.SocketConnection.get_remote_address` on the returned :obj:`~gi.repository.Gio.SocketConnection`\, and seeing if it's a :obj:`~gi.repository.Gio.ProxyAddress` of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself. This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method. When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake. :param protocol: The proxy protocol .. method:: connect(connectable: ~gi.repository.Gio.SocketConnectable, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.SocketConnection Tries to resolve the ``connectable`` and make a network connection to it. Upon a successful connection, a new :obj:`~gi.repository.Gio.SocketConnection` 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 :obj:`~gi.repository.Gio.SocketConnection` object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a :obj:`~gi.repository.Gio.TcpConnection`\. The socket created will be the same family as the address that the ``connectable`` resolves to, unless family is set with :func:`~gi.repository.Gio.SocketClient.set_family` or indirectly via :func:`~gi.repository.Gio.SocketClient.set_local_address`. The socket type defaults to :const:`~gi.repository.Gio.SocketType.STREAM` but can be set with :func:`~gi.repository.Gio.SocketClient.set_socket_type`. If a local address is specified with :func:`~gi.repository.Gio.SocketClient.set_local_address` the socket will be bound to this address before connecting. .. versionadded:: 2.22 :param connectable: a :obj:`~gi.repository.Gio.SocketConnectable` specifying the remote address. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. .. method:: connect_async(connectable: ~gi.repository.Gio.SocketConnectable, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None This is the asynchronous version of :func:`~gi.repository.Gio.SocketClient.connect`. You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements `RFC 8305 `__ "Happy Eyeballs" recommendations to work around long connection timeouts in networks where IPv6 is broken by performing an IPv4 connection simultaneously without waiting for IPv6 to time out, which is not supported by the synchronous call. (This is not an API guarantee, and may change in the future.) When the operation is finished ``callback`` will be called. You can then call :func:`~gi.repository.Gio.SocketClient.connect_finish` to get the result of the operation. .. versionadded:: 2.22 :param connectable: a :obj:`~gi.repository.Gio.SocketConnectable` specifying the remote address. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` :param user_data: user data for the callback .. method:: connect_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.SocketConnection Finishes an async connect operation. See :func:`~gi.repository.Gio.SocketClient.connect_async` .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: connect_to_host(host_and_port: str, default_port: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.SocketConnection This is a helper function for :func:`~gi.repository.Gio.SocketClient.connect`. Attempts to create a TCP connection to the named host. ``host_and_port`` may be in any of a number of recognized formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed). If no port override is given in ``host_and_port`` then ``default_port`` will be used as the port number to connect to. In general, ``host_and_port`` is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and ``default_port`` is expected to be provided by the application. In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds. Upon a successful connection, a new :obj:`~gi.repository.Gio.SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) :const:`None` is returned and ``error`` (if non-:const:`None`) is set accordingly. .. versionadded:: 2.22 :param host_and_port: the name and optionally port of the host to connect to :param default_port: the default port to connect to :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` .. method:: connect_to_host_async(host_and_port: str, default_port: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None This is the asynchronous version of :func:`~gi.repository.Gio.SocketClient.connect_to_host`. When the operation is finished ``callback`` will be called. You can then call :func:`~gi.repository.Gio.SocketClient.connect_to_host_finish` to get the result of the operation. .. versionadded:: 2.22 :param host_and_port: the name and optionally the port of the host to connect to :param default_port: the default port to connect to :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` :param user_data: user data for the callback .. method:: connect_to_host_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.SocketConnection Finishes an async connect operation. See :func:`~gi.repository.Gio.SocketClient.connect_to_host_async` .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: connect_to_service(domain: str, service: str, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.SocketConnection Attempts to create a TCP connection to a service. This call looks up the SRV record for ``service`` at ``domain`` for the "tcp" protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining. Upon a successful connection, a new :obj:`~gi.repository.Gio.SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) :const:`None` is returned and ``error`` (if non-:const:`None`) is set accordingly. :param domain: a domain name :param service: the name of the service to connect to :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` .. method:: connect_to_service_async(domain: str, service: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None This is the asynchronous version of :func:`~gi.repository.Gio.SocketClient.connect_to_service`. .. versionadded:: 2.22 :param domain: a domain name :param service: the name of the service to connect to :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` :param user_data: user data for the callback .. method:: connect_to_service_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.SocketConnection Finishes an async connect operation. See :func:`~gi.repository.Gio.SocketClient.connect_to_service_async` .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: connect_to_uri(uri: str, default_port: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.SocketConnection This is a helper function for :func:`~gi.repository.Gio.SocketClient.connect`. Attempts to create a TCP connection with a network URI. ``uri`` may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, ``default_port`` will be used. TLS will be negotiated if :obj:`~gi.repository.Gio.SocketClient`\:tls is :const:`True`. (:obj:`~gi.repository.Gio.SocketClient` does not know to automatically assume TLS for certain URI schemes.) Using this rather than :func:`~gi.repository.Gio.SocketClient.connect` or :func:`~gi.repository.Gio.SocketClient.connect_to_host` allows :obj:`~gi.repository.Gio.SocketClient` to determine when to use application-specific proxy protocols. Upon a successful connection, a new :obj:`~gi.repository.Gio.SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) :const:`None` is returned and ``error`` (if non-:const:`None`) is set accordingly. .. versionadded:: 2.26 :param uri: A network URI :param default_port: the default port to connect to :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` .. method:: connect_to_uri_async(uri: str, default_port: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None This is the asynchronous version of :func:`~gi.repository.Gio.SocketClient.connect_to_uri`. When the operation is finished ``callback`` will be called. You can then call :func:`~gi.repository.Gio.SocketClient.connect_to_uri_finish` to get the result of the operation. .. versionadded:: 2.26 :param uri: a network uri :param default_port: the default port to connect to :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` :param user_data: user data for the callback .. method:: connect_to_uri_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.SocketConnection Finishes an async connect operation. See :func:`~gi.repository.Gio.SocketClient.connect_to_uri_async` .. versionadded:: 2.26 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: do_event(self, event: ~gi.repository.Gio.SocketClientEvent, connectable: ~gi.repository.Gio.SocketConnectable, connection: ~gi.repository.Gio.IOStream) -> None :param event: :param connectable: :param connection: .. method:: get_enable_proxy() -> bool Gets the proxy enable state; see :func:`~gi.repository.Gio.SocketClient.set_enable_proxy` .. versionadded:: 2.26 .. method:: get_family() -> ~gi.repository.Gio.SocketFamily Gets the socket family of the socket client. See :func:`~gi.repository.Gio.SocketClient.set_family` for details. .. versionadded:: 2.22 .. method:: get_local_address() -> ~gi.repository.Gio.SocketAddress | None Gets the local address of the socket client. See :func:`~gi.repository.Gio.SocketClient.set_local_address` for details. .. versionadded:: 2.22 .. method:: get_protocol() -> ~gi.repository.Gio.SocketProtocol Gets the protocol name type of the socket client. See :func:`~gi.repository.Gio.SocketClient.set_protocol` for details. .. versionadded:: 2.22 .. method:: get_proxy_resolver() -> ~gi.repository.Gio.ProxyResolver Gets the :obj:`~gi.repository.Gio.ProxyResolver` being used by ``client``\. Normally, this will be the resolver returned by :func:`~gi.repository.Gio.ProxyResolver.get_default`, but you can override it with :func:`~gi.repository.Gio.SocketClient.set_proxy_resolver`. .. versionadded:: 2.36 .. method:: get_socket_type() -> ~gi.repository.Gio.SocketType Gets the socket type of the socket client. See :func:`~gi.repository.Gio.SocketClient.set_socket_type` for details. .. versionadded:: 2.22 .. method:: get_timeout() -> int Gets the I/O timeout time for sockets created by ``client``\. See :func:`~gi.repository.Gio.SocketClient.set_timeout` for details. .. versionadded:: 2.26 .. method:: get_tls() -> bool Gets whether ``client`` creates TLS connections. See :func:`~gi.repository.Gio.SocketClient.set_tls` for details. .. versionadded:: 2.28 .. method:: get_tls_validation_flags() -> ~gi.repository.Gio.TlsCertificateFlags Gets the TLS validation flags used creating TLS connections via ``client``\. This function does not work as originally designed and is impossible to use correctly. See :obj:`~gi.repository.Gio.SocketClient`\:tls-validation-flags for more information. .. versionadded:: 2.28 .. deprecated:: 2.72 Do not attempt to ignore validation errors. .. method:: set_enable_proxy(enable: bool) -> None Sets whether or not ``client`` attempts to make connections via a proxy server. When enabled (the default), :obj:`~gi.repository.Gio.SocketClient` will use a :obj:`~gi.repository.Gio.ProxyResolver` to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation. See also :func:`~gi.repository.Gio.SocketClient.set_proxy_resolver`. .. versionadded:: 2.26 :param enable: whether to enable proxies .. method:: set_family(family: ~gi.repository.Gio.SocketFamily) -> None Sets the socket family of the socket client. If this is set to something other than :const:`~gi.repository.Gio.SocketFamily.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. .. versionadded:: 2.22 :param family: a :obj:`~gi.repository.Gio.SocketFamily` .. method:: set_local_address(address: ~gi.repository.Gio.SocketAddress | None = None) -> None Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not :const:`None`) before connecting. This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface. .. versionadded:: 2.22 :param address: a :obj:`~gi.repository.Gio.SocketAddress`\, or :const:`None` .. method:: set_protocol(protocol: ~gi.repository.Gio.SocketProtocol) -> None Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. If ``protocol`` is :const:`~gi.repository.Gio.SocketProtocol.DEFAULT` that means to use the default protocol for the socket family and type. .. versionadded:: 2.22 :param protocol: a :obj:`~gi.repository.Gio.SocketProtocol` .. method:: set_proxy_resolver(proxy_resolver: ~gi.repository.Gio.ProxyResolver | None = None) -> None Overrides the :obj:`~gi.repository.Gio.ProxyResolver` used by ``client``\. You can call this if you want to use specific proxies, rather than using the system default proxy settings. Note that whether or not the proxy resolver is actually used depends on the setting of :obj:`~gi.repository.Gio.SocketClient`\:enable-proxy, which is not changed by this function (but which is :const:`True` by default) .. versionadded:: 2.36 :param proxy_resolver: a :obj:`~gi.repository.Gio.ProxyResolver`\, or :const:`None` for the default. .. method:: set_socket_type(type: ~gi.repository.Gio.SocketType) -> None 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 :const:`~gi.repository.Gio.SocketType.DATAGRAM`, as GSocketClient is used for connection oriented services. .. versionadded:: 2.22 :param type: a :obj:`~gi.repository.Gio.SocketType` .. method:: set_timeout(timeout: int) -> None Sets the I/O timeout for sockets created by ``client``\. ``timeout`` is a time in seconds, or 0 for no timeout (the default). The timeout value affects the initial connection attempt as well, so setting this may cause calls to :func:`~gi.repository.Gio.SocketClient.connect`, etc, to fail with :const:`~gi.repository.Gio.IOErrorEnum.TIMED_OUT`. .. versionadded:: 2.26 :param timeout: the timeout .. method:: set_tls(tls: bool) -> None Sets whether ``client`` creates TLS (aka SSL) connections. If ``tls`` is :const:`True`, ``client`` will wrap its connections in a :obj:`~gi.repository.Gio.TlsClientConnection` and perform a TLS handshake when connecting. Note that since :obj:`~gi.repository.Gio.SocketClient` must return a :obj:`~gi.repository.Gio.SocketConnection`\, but :obj:`~gi.repository.Gio.TlsClientConnection` is not a :obj:`~gi.repository.Gio.SocketConnection`\, this actually wraps the resulting :obj:`~gi.repository.Gio.TlsClientConnection` in a :obj:`~gi.repository.Gio.TcpWrapperConnection` when returning it. You can use :func:`~gi.repository.Gio.TcpWrapperConnection.get_base_io_stream` on the return value to extract the :obj:`~gi.repository.Gio.TlsClientConnection`\. If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the :obj:`~gi.repository.Gio.TlsConnection`\::accept-certificate signal), you can connect to ``client``\'s :obj:`~gi.repository.Gio.SocketClient`\::event signal and wait for it to be emitted with :const:`~gi.repository.Gio.SocketClientEvent.TLS_HANDSHAKING`, which will give you a chance to see the :obj:`~gi.repository.Gio.TlsClientConnection` before the handshake starts. .. versionadded:: 2.28 :param tls: whether to use TLS .. method:: set_tls_validation_flags(flags: ~gi.repository.Gio.TlsCertificateFlags) -> None Sets the TLS validation flags used when creating TLS connections via ``client``\. The default value is :const:`~gi.repository.Gio.TlsCertificateFlags.VALIDATE_ALL`. This function does not work as originally designed and is impossible to use correctly. See :obj:`~gi.repository.Gio.SocketClient`\:tls-validation-flags for more information. .. versionadded:: 2.28 .. deprecated:: 2.72 Do not attempt to ignore validation errors. :param flags: the validation flags Properties ---------- .. rst-class:: interim-class .. class:: SocketClient :no-index: .. attribute:: props.enable_proxy :type: bool The type of the None singleton. .. versionadded:: 2.22 .. attribute:: props.family :type: ~gi.repository.Gio.SocketFamily The type of the None singleton. .. versionadded:: 2.22 .. attribute:: props.local_address :type: ~gi.repository.Gio.SocketAddress The type of the None singleton. .. versionadded:: 2.22 .. attribute:: props.protocol :type: ~gi.repository.Gio.SocketProtocol The type of the None singleton. .. versionadded:: 2.22 .. attribute:: props.proxy_resolver :type: ~gi.repository.Gio.ProxyResolver The type of the None singleton. .. versionadded:: 2.36 .. attribute:: props.timeout :type: int The type of the None singleton. .. versionadded:: 2.22 .. attribute:: props.tls :type: bool The type of the None singleton. .. versionadded:: 2.22 .. attribute:: props.tls_validation_flags :type: ~gi.repository.Gio.TlsCertificateFlags The type of the None singleton. .. deprecated:: 2.72 Do not attempt to ignore validation errors. .. attribute:: props.type :type: ~gi.repository.Gio.SocketType The type of the None singleton. .. versionadded:: 2.22 Signals ------- .. rst-class:: interim-class .. class:: SocketClient.signals :no-index: .. method:: event(event: ~gi.repository.Gio.SocketClientEvent, connectable: ~gi.repository.Gio.SocketConnectable, connection: ~gi.repository.Gio.IOStream | None = None) -> None The type of the None singleton. .. versionadded:: 2.32 :param event: the event that is occurring :param connectable: the :obj:`~gi.repository.Gio.SocketConnectable` that ``event`` is occurring on :param connection: the current representation of the connection Virtual Methods --------------- .. rst-class:: interim-class .. class:: SocketClient :no-index: .. method:: do_event(event: ~gi.repository.Gio.SocketClientEvent, connectable: ~gi.repository.Gio.SocketConnectable, connection: ~gi.repository.Gio.IOStream) -> None The type of the None singleton. :param event: :param connectable: :param connection: Fields ------ .. rst-class:: interim-class .. class:: SocketClient :no-index: .. attribute:: parent_instance .. attribute:: priv