## GSocketService

GSocketService — Make it easy to implement a network service

## Synopsis

                        GSocketService;
    GSocketService *    g_socket_service_new                (void);
    void                g_socket_service_start              (GSocketService *service);
    void                g_socket_service_stop               (GSocketService *service);
    gboolean            g_socket_service_is_active          (GSocketService *service);

## Object Hierarchy

      GObject
       +----GSocketListener
             +----GSocketService
                   +----GThreadedSocketService

## Signals

      "incoming"                                       : Run Last

## 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 in the main thread, and is not threadsafe in general. However, the calls to start and stop the service are threadsafe so these can be used from threads that handle incoming clients.

## Details

### GSocketService

    typedef struct _GSocketService GSocketService;

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

Since 2.22

### 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()`.

Returns : | a new GSocketService.

Since 2.22

### g_socket_service_start ()

    void                g_socket_service_start              (GSocketService *service);

Starts the service, i.e. start accepting connections from the added sockets when the mainloop runs.

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

`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 threadsafe, so it may be called from a thread handling an incoming client request.

`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.

`service` : | a GSocketService
Returns : | `TRUE` if the service is active, `FALSE` otherwise

Since 2.22

## Signal Details

### The `"incoming"` signal

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

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.

`service` : | the GSocketService
`connection` : | a new GSocketConnection object
`source_object` : | the source_object passed to `g_socket_listener_add_address()`
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` to stop other handlers from being called

Since 2.22

## See Also

GThreadedSocketService, GSocketListener.