GI.Gio.Objects.SocketService

A SocketService 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 SocketService::incoming signal is emitted.

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

There are two options for implementing a network service based on SocketService. The first is to create the service using socketServiceNew and to connect to the SocketService::incoming signal. The second is to subclass SocketService 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 ThreadedSocketService.

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

Since: 2.22

Exported types

newtype SocketService

Memory-managed wrapper type.

Constructors

SocketService (ManagedPtr SocketService)

Instances

Eq SocketService

Defined in GI.Gio.Objects.SocketService

Methods

(==) :: SocketService -> SocketService -> Bool

(/=) :: SocketService -> SocketService -> Bool

GObject SocketService

Defined in GI.Gio.Objects.SocketService

ManagedPtrNewtype SocketService

Defined in GI.Gio.Objects.SocketService

Methods

toManagedPtr :: SocketService -> ManagedPtr SocketService

TypedObject SocketService

Defined in GI.Gio.Objects.SocketService

Methods

glibType :: IO GType

HasParentTypes SocketService

Defined in GI.Gio.Objects.SocketService

IsGValue (Maybe SocketService)

Convert SocketService to and from GValue. See toGValue and fromGValue.

Defined in GI.Gio.Objects.SocketService

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe SocketService -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe SocketService)

type ParentTypes SocketService

Defined in GI.Gio.Objects.SocketService

type ParentTypes SocketService = '[SocketListener, Object]

class (GObject o, IsDescendantOf SocketService o) => IsSocketService o

Type class for types which can be safely cast to SocketService, for instance with toSocketService.

Instances

(GObject o, IsDescendantOf SocketService o) => IsSocketService o

Defined in GI.Gio.Objects.SocketService

toSocketService :: (MonadIO m, IsSocketService o) => o -> m SocketService

Cast to SocketService, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

accept, acceptAsync, acceptFinish, acceptSocket, acceptSocketAsync, acceptSocketFinish, addAddress, addAnyInetPort, addInetPort, addSocket, bindProperty, bindPropertyFull, close, forceFloating, freezeNotify, getv, isActive, isFloating, notify, notifyByPspec, ref, refSink, runDispose, start, stealData, stealQdata, stop, thawNotify, unref, watchClosure.

Getters

getData, getProperty, getQdata.

Setters

setBacklog, setData, setDataFull, setProperty.

isActive

socketServiceIsActive

Arguments

:: (HasCallStack, MonadIO m, IsSocketService a)

=> a

service: a SocketService

-> m Bool

Returns: True if the service is active, False otherwise

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.

Since: 2.22

new

socketServiceNew

Arguments

:: (HasCallStack, MonadIO m)

=> m SocketService

Returns: a new SocketService.

Creates a new SocketService with no sockets to listen for. New listeners can be added with e.g. socketListenerAddAddress or socketListenerAddInetPort.

New services are created active, there is no need to call socketServiceStart, unless socketServiceStop has been called before.

Since: 2.22

start

socketServiceStart

Arguments

:: (HasCallStack, MonadIO m, IsSocketService a)

=> a

service: a SocketService

-> m ()

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

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

Since: 2.22

stop

socketServiceStop

Arguments

:: (HasCallStack, MonadIO m, IsSocketService a)

=> a

service: a SocketService

-> m ()

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

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

Since: 2.22

Properties

active

Whether the service is currently accepting connections.

Since: 2.46

constructSocketServiceActive :: (IsSocketService o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “active” property. This is rarely needed directly, but it is used by new.

getSocketServiceActive :: (MonadIO m, IsSocketService o) => o -> m Bool

Get the value of the “active” property. When overloading is enabled, this is equivalent to

get socketService #active

setSocketServiceActive :: (MonadIO m, IsSocketService o) => o -> Bool -> m ()

Set the value of the “active” property. When overloading is enabled, this is equivalent to

set socketService [ #active := value ]

Signals

incoming

type SocketServiceIncomingCallback

Arguments

 = SocketConnection

connection: a new SocketConnection object

-> Maybe Object

sourceObject: the source_object passed to socketListenerAddAddress

-> IO Bool

Returns: True to stop other handlers from being called

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.

Since: 2.22

afterSocketServiceIncoming :: (IsSocketService a, MonadIO m) => a -> ((?self :: a) => SocketServiceIncomingCallback) -> m SignalHandlerId

Connect a signal handler for the incoming signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after socketService #incoming callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSocketServiceIncoming :: (IsSocketService a, MonadIO m) => a -> ((?self :: a) => SocketServiceIncomingCallback) -> m SignalHandlerId

Connect a signal handler for the incoming signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on socketService #incoming callback