:right-sidebar: True

SocketService
===================================================================

.. currentmodule:: gi.repository.Gio


.. versionadded:: 2.22




.. class:: SocketService(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gio.SocketListener`, :class:`~gi.repository.GObject.Object`


Subclasses: :class:`~gi.repository.Gio.ThreadedSocketService`




A ``GSocketService`` is an object that represents a service that
is provided to the network or over local sockets.  When a new
connection is made to the service the :obj:`~gi.repository.Gio.SocketService.signals.incoming`
signal is emitted.

A ``GSocketService`` is a subclass of :obj:`~gi.repository.Gio.SocketListener` and you need
to add the addresses you want to accept connections on with the
:obj:`~gi.repository.Gio.SocketListener` APIs.

There are two options for implementing a network service based on
``GSocketService``\. The first is to create the service using
:obj:`~gi.repository.Gio.SocketService.new` and to connect to the
:obj:`~gi.repository.Gio.SocketService.signals.incoming` signal. The second is to subclass
``GSocketService`` and override the default signal handler implementation.

In either case, the handler must immediately return, or else it
will block additional incoming connections from being serviced.
If you are interested in writing connection handlers that contain
blocking code then see :obj:`~gi.repository.Gio.ThreadedSocketService`\.

The socket service runs on the main loop of the
thread-default context (see
:obj:`~gi.repository.GLib.MainContext.push_thread_default`\) of the thread it is
created in, and is not threadsafe in general. However, the calls to start and
stop the service are thread-safe so these can be used from threads that
handle incoming clients.


Constructors
------------

.. rst-class:: interim-class

.. class:: SocketService
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gio.SocketService

      Creates a new :obj:`~gi.repository.Gio.SocketService` with no sockets to listen for.
      New listeners can be added with e.g. :func:`~gi.repository.Gio.SocketListener.add_address`
      or :func:`~gi.repository.Gio.SocketListener.add_inet_port`.

      New services are created active, there is no need to call
      :func:`~gi.repository.Gio.SocketService.start`, unless :func:`~gi.repository.Gio.SocketService.stop` has been
      called before.


      .. versionadded:: 2.22












Methods
-------

.. rst-class:: interim-class

.. class:: SocketService
   :no-index:


   .. method:: do_incoming(self, connection: ~gi.repository.Gio.SocketConnection, source_object: ~gi.repository.GObject.Object) -> bool

      







      :param connection: 

      :param source_object: 




   .. method:: is_active() -> bool

      Check whether the service is active or not. An active
      service will accept new clients that connect, while
      a non-active service will let connecting clients queue
      up until the service is started.



      .. versionadded:: 2.22








   .. method:: start() -> None

      Restarts the service, i.e. start accepting connections
      from the added sockets when the mainloop runs. This only needs
      to be called after the service has been stopped from
      :func:`~gi.repository.Gio.SocketService.stop`.

      This call is thread-safe, so it may be called from a thread
      handling an incoming client request.



      .. versionadded:: 2.22








   .. method:: stop() -> None

      Stops the service, i.e. stops accepting connections
      from the added sockets when the mainloop runs.

      This call is thread-safe, so it may be called from a thread
      handling an incoming client request.

      Note that this only stops accepting new connections; it does not
      close the listening sockets, and you can call
      :func:`~gi.repository.Gio.SocketService.start` again later to begin listening again. To
      close the listening sockets, call :func:`~gi.repository.Gio.SocketListener.close`. (This
      will happen automatically when the :obj:`~gi.repository.Gio.SocketService` is finalized.)

      This must be called before calling :func:`~gi.repository.Gio.SocketListener.close` as
      the socket service will start accepting connections immediately
      when a new socket is added.



      .. versionadded:: 2.22












Properties
----------

.. rst-class:: interim-class

.. class:: SocketService
   :no-index:
   

   .. attribute:: props.active
      :type: bool

      Whether the service is currently accepting connections.


      .. versionadded:: 2.46









Signals
-------

.. rst-class:: interim-class

.. class:: SocketService.signals
   :no-index:
   

   .. method:: incoming(connection: ~gi.repository.Gio.SocketConnection, source_object: ~gi.repository.GObject.Object | None = None) -> bool

      The ::incoming signal is emitted when a new incoming connection
      to ``service`` needs to be handled. The handler must initiate the
      handling of ``connection``\, but may not block; in essence,
      asynchronous operations must be used.

      ``connection`` will be unreffed once the signal handler returns,
      so you need to ref it yourself if you are planning to use it.


      .. versionadded:: 2.22





      :param connection: a new :obj:`~gi.repository.Gio.SocketConnection` object

      :param source_object: the source_object passed to
         :func:`~gi.repository.Gio.SocketListener.add_address`








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

.. rst-class:: interim-class

.. class:: SocketService
   :no-index:
   

   .. method:: do_incoming(connection: ~gi.repository.Gio.SocketConnection, source_object: ~gi.repository.GObject.Object) -> bool

      signal emitted when new connections are accepted






      :param connection: 

      :param source_object: 








Fields
------

.. rst-class:: interim-class

.. class:: SocketService
   :no-index:
   

   .. attribute:: parent_instance

      






   .. attribute:: priv