gi-gio-2.0.18: Gio bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gio.Objects.SocketService

Contents

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

Exported types

class GObject o => IsSocketService o Source #

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

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.

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

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