Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (inaki@blueleaf.cc)
Safe Haskell	None
Language	Haskell2010

GI.Gio.Objects.SocketService

Contents

Exported types
Methods
Properties
- active
Signals
- incoming

Description

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

Synopsis

newtype SocketService = SocketService (ManagedPtr SocketService)
class (GObject o, IsDescendantOf SocketService o) => IsSocketService o
toSocketService :: (MonadIO m, IsSocketService o) => o -> m SocketService
noSocketService :: Maybe SocketService
socketServiceIsActive :: (HasCallStack, MonadIO m, IsSocketService a) => a -> m Bool
socketServiceNew :: (HasCallStack, MonadIO m) => m SocketService
socketServiceStart :: (HasCallStack, MonadIO m, IsSocketService a) => a -> m ()
socketServiceStop :: (HasCallStack, MonadIO m, IsSocketService a) => a -> m ()
constructSocketServiceActive :: IsSocketService o => Bool -> IO (GValueConstruct o)
getSocketServiceActive :: (MonadIO m, IsSocketService o) => o -> m Bool
setSocketServiceActive :: (MonadIO m, IsSocketService o) => o -> Bool -> m ()
type C_SocketServiceIncomingCallback = Ptr () -> Ptr SocketConnection -> Ptr Object -> Ptr () -> IO CInt
type SocketServiceIncomingCallback = SocketConnection -> Maybe Object -> IO Bool
afterSocketServiceIncoming :: (IsSocketService a, MonadIO m) => a -> SocketServiceIncomingCallback -> m SignalHandlerId
genClosure_SocketServiceIncoming :: MonadIO m => SocketServiceIncomingCallback -> m (GClosure C_SocketServiceIncomingCallback)
mk_SocketServiceIncomingCallback :: C_SocketServiceIncomingCallback -> IO (FunPtr C_SocketServiceIncomingCallback)
noSocketServiceIncomingCallback :: Maybe SocketServiceIncomingCallback
onSocketServiceIncoming :: (IsSocketService a, MonadIO m) => a -> SocketServiceIncomingCallback -> m SignalHandlerId
wrap_SocketServiceIncomingCallback :: SocketServiceIncomingCallback -> C_SocketServiceIncomingCallback

Exported types

newtype SocketService Source #

Memory-managed wrapper type.

Constructors

SocketService (ManagedPtr SocketService)

Instances

GObject SocketService Source #
Instance details Defined in GI.Gio.Objects.SocketService Methods gobjectType :: IO GType #
HasParentTypes SocketService Source #
Instance details Defined in GI.Gio.Objects.SocketService
type ParentTypes SocketService Source #
Instance details Defined in GI.Gio.Objects.SocketService type ParentTypes SocketService = SocketListener ': (Object ': ([] :: [Type]))

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

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

Instances

(GObject o, IsDescendantOf SocketService o) => IsSocketService o Source #
Instance details Defined in GI.Gio.Objects.SocketService

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

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

noSocketService :: Maybe SocketService Source #

A convenience alias for Nothing :: Maybe SocketService.

Methods

isActive

socketServiceIsActive Source #

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

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

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

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 => Bool -> IO (GValueConstruct o) Source #

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

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 () Source #

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

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

type SocketServiceIncomingCallback Source #

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

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) Source #

Wrap the callback into a GClosure.

mk_SocketServiceIncomingCallback :: C_SocketServiceIncomingCallback -> IO (FunPtr C_SocketServiceIncomingCallback) Source #

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

noSocketServiceIncomingCallback :: Maybe SocketServiceIncomingCallback Source #

A convenience synonym for Nothing :: Maybe SocketServiceIncomingCallback.

onSocketServiceIncoming :: (IsSocketService a, MonadIO m) => a -> SocketServiceIncomingCallback -> m SignalHandlerId Source #

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

Wrap a SocketServiceIncomingCallback into a C_SocketServiceIncomingCallback.