gi-gio-2.0.27: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.SocketService

Contents

- Exported types
- Methods
  - Overloaded methods
  - isActive
  - new
  - start
  - stop
- 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 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

Synopsis

- newtype SocketService = SocketService (ManagedPtr SocketService)
- class (GObject o, IsDescendantOf SocketService o) => IsSocketService o
- toSocketService :: (MonadIO m, IsSocketService o) => o -> m 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, MonadIO m) => Bool -> m (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

Instances details

Eq SocketService Source # |
Instance details Defined in GI.Gio.Objects.SocketService Methods (==) :: SocketService -> SocketService -> Bool # (/=) :: SocketService -> SocketService -> Bool #
GObject SocketService Source # |
Instance details Defined in GI.Gio.Objects.SocketService
TypedObject SocketService Source # |
Instance details Defined in GI.Gio.Objects.SocketService Methods glibType :: IO GType Source #
ManagedPtrNewtype SocketService Source # |
Instance details Defined in GI.Gio.Objects.SocketService Methods toManagedPtr :: SocketService -> ManagedPtr SocketService Source #
IsGValue SocketService Source # | Convert `SocketService` to and from `GValue` with `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Objects.SocketService Methods toGValue :: SocketService -> IO GValue Source # fromGValue :: GValue -> IO SocketService Source #
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]

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

Instances details

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

# Methods

## Overloaded 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, MonadIO m) => Bool -> m (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`.