GSocketService

GSocketService — Make it easy to implement a network service

Properties

gboolean active Read / Write / Construct

Signals

gboolean incoming Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GSocketListener
        ╰── GSocketService
            ╰── GThreadedSocketService

Includes

#include <gio/gio.h>

Description

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 “incoming” signal is emitted.

A GSocketService is a subclass of GSocketListener and you need to add the addresses you want to accept connections on with the GSocketListener APIs.

There are two options for implementing a network service based on GSocketService. The first is to create the service using g_socket_service_new() and to connect to the “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 GThreadedSocketService.

The socket service runs on the main loop of the thread-default context 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.

Functions

g_socket_service_new ()

GSocketService *
g_socket_service_new (void);

Creates a new GSocketService with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port().

New services are created active, there is no need to call g_socket_service_start(), unless g_socket_service_stop() has been called before.

Returns

a new GSocketService.

Since: 2.22


g_socket_service_start ()

void
g_socket_service_start (GSocketService *service);

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 g_socket_service_stop().

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

Parameters

service

a GSocketService

 

Since: 2.22


g_socket_service_stop ()

void
g_socket_service_stop (GSocketService *service);

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 g_socket_service_start() again later to begin listening again. To close the listening sockets, call g_socket_listener_close(). (This will happen automatically when the GSocketService is finalized.)

This must be called before calling g_socket_listener_close() as the socket service will start accepting connections immediately when a new socket is added.

Parameters

service

a GSocketService

 

Since: 2.22


g_socket_service_is_active ()

gboolean
g_socket_service_is_active (GSocketService *service);

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.

Parameters

service

a GSocketService

 

Returns

TRUE if the service is active, FALSE otherwise

Since: 2.22

Types and Values

GSocketService

typedef struct _GSocketService GSocketService;

A helper class for handling accepting incoming connections in the glib mainloop.

Since: 2.22

Property Details

The “active” property

  “active”                   gboolean

Whether the service is currently accepting connections.

Owner: GSocketService

Flags: Read / Write / Construct

Default value: TRUE

Since: 2.46

Signal Details

The “incoming” signal

gboolean
user_function (GSocketService    *service,
               GSocketConnection *connection,
               GObject           *source_object,
               gpointer           user_data)

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.

Parameters

service

the GSocketService

 

connection

a new GSocketConnection object

 

source_object

the source_object passed to g_socket_listener_add_address().

[nullable]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to stop other handlers from being called

Flags: Run Last

Since: 2.22