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

IsGValue SocketService

Convert SocketService to and from GValue with toGValue and fromGValue.

Defined in GI.Gio.Objects.SocketService

Methods

toGValue :: SocketService -> IO GValue

fromGValue :: GValue -> IO 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

GObject SocketService

Defined in GI.Gio.Objects.SocketService

HasParentTypes SocketService

Defined in GI.Gio.Objects.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

Overloaded methods

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 C_SocketServiceIncomingCallback = Ptr () -> Ptr SocketConnection -> Ptr Object -> Ptr () -> IO CInt

Type for the callback on the (unwrapped) C side.

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

genClosure_SocketServiceIncoming :: MonadIO m => SocketServiceIncomingCallback -> m (GClosure C_SocketServiceIncomingCallback)

Wrap the callback into a GClosure.

mk_SocketServiceIncomingCallback :: C_SocketServiceIncomingCallback -> IO (FunPtr C_SocketServiceIncomingCallback)

Generate a function pointer callable from C code, from a C_SocketServiceIncomingCallback.

noSocketServiceIncomingCallback :: Maybe SocketServiceIncomingCallback

A convenience synonym for Nothing :: Maybe SocketServiceIncomingCallback.

onSocketServiceIncoming :: (IsSocketService a, MonadIO m) => 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

wrap_SocketServiceIncomingCallback :: SocketServiceIncomingCallback -> C_SocketServiceIncomingCallback

Wrap a SocketServiceIncomingCallback into a C_SocketServiceIncomingCallback.