gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.DBusServer

Contents

- Exported types
- Methods
  - getClientAddress
  - getFlags
  - getGuid
  - isActive
  - newSync
  - start
  - stop
- Properties
  - active
  - address
  - authenticationObserver
  - clientAddress
  - flags
  - guid
- Signals
  - newConnection

Description

`DBusServer` is a helper for listening to and accepting D-Bus connections. This can be used to create a new D-Bus server, allowing two peers to use the D-Bus protocol for their own specialized communication. A server instance provided in this way will not perform message routing or implement the org.freedesktop.DBus interface.

To just export an object on a well-known name on a message bus, such as the session or system bus, you should instead use `g_bus_own_name()`.

An example of peer-to-peer communication with G-DBus can be found in gdbus-example-peer.c.

Since: 2.26

Synopsis

- newtype DBusServer = DBusServer (ManagedPtr DBusServer)
- class GObject o => IsDBusServer o
- toDBusServer :: (MonadIO m, IsDBusServer o) => o -> m DBusServer
- noDBusServer :: Maybe DBusServer
- dBusServerGetClientAddress :: (HasCallStack, MonadIO m, IsDBusServer a) => a -> m Text
- dBusServerGetFlags :: (HasCallStack, MonadIO m, IsDBusServer a) => a -> m [DBusServerFlags]
- dBusServerGetGuid :: (HasCallStack, MonadIO m, IsDBusServer a) => a -> m Text
- dBusServerIsActive :: (HasCallStack, MonadIO m, IsDBusServer a) => a -> m Bool
- dBusServerNewSync :: (HasCallStack, MonadIO m, IsDBusAuthObserver a, IsCancellable b) => Text -> [DBusServerFlags] -> Text -> Maybe a -> Maybe b -> m DBusServer
- dBusServerStart :: (HasCallStack, MonadIO m, IsDBusServer a) => a -> m ()
- dBusServerStop :: (HasCallStack, MonadIO m, IsDBusServer a) => a -> m ()
- getDBusServerActive :: (MonadIO m, IsDBusServer o) => o -> m Bool
- constructDBusServerAddress :: IsDBusServer o => Text -> IO (GValueConstruct o)
- getDBusServerAddress :: (MonadIO m, IsDBusServer o) => o -> m (Maybe Text)
- constructDBusServerAuthenticationObserver :: (IsDBusServer o, IsDBusAuthObserver a) => a -> IO (GValueConstruct o)
- getDBusServerAuthenticationObserver :: (MonadIO m, IsDBusServer o) => o -> m (Maybe DBusAuthObserver)
- getDBusServerClientAddress :: (MonadIO m, IsDBusServer o) => o -> m Text
- constructDBusServerFlags :: IsDBusServer o => [DBusServerFlags] -> IO (GValueConstruct o)
- getDBusServerFlags :: (MonadIO m, IsDBusServer o) => o -> m [DBusServerFlags]
- constructDBusServerGuid :: IsDBusServer o => Text -> IO (GValueConstruct o)
- getDBusServerGuid :: (MonadIO m, IsDBusServer o) => o -> m Text
- type C_DBusServerNewConnectionCallback = Ptr () -> Ptr DBusConnection -> Ptr () -> IO CInt
- type DBusServerNewConnectionCallback = DBusConnection -> IO Bool
- afterDBusServerNewConnection :: (IsDBusServer a, MonadIO m) => a -> DBusServerNewConnectionCallback -> m SignalHandlerId
- genClosure_DBusServerNewConnection :: DBusServerNewConnectionCallback -> IO Closure
- mk_DBusServerNewConnectionCallback :: C_DBusServerNewConnectionCallback -> IO (FunPtr C_DBusServerNewConnectionCallback)
- noDBusServerNewConnectionCallback :: Maybe DBusServerNewConnectionCallback
- onDBusServerNewConnection :: (IsDBusServer a, MonadIO m) => a -> DBusServerNewConnectionCallback -> m SignalHandlerId
- wrap_DBusServerNewConnectionCallback :: DBusServerNewConnectionCallback -> C_DBusServerNewConnectionCallback

# Exported types

newtype DBusServer Source #

Memory-managed wrapper type.

Constructors

DBusServer (ManagedPtr DBusServer) |

Instances

GObject DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer Methods gobjectType :: DBusServer -> IO GType Source #
IsObject DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer
IsInitable DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer
IsDBusServer DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer

class GObject o => IsDBusServer o Source #

Type class for types which can be safely cast to `DBusServer`, for instance with `toDBusServer`.

Instances

(GObject a, (UnknownAncestorError DBusServer a :: Constraint)) => IsDBusServer a Source # |
Instance details Defined in GI.Gio.Objects.DBusServer
IsDBusServer DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer

toDBusServer :: (MonadIO m, IsDBusServer o) => o -> m DBusServer Source #

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

noDBusServer :: Maybe DBusServer Source #

A convenience alias for `Nothing` :: `Maybe` `DBusServer`.

# Methods

## getClientAddress

dBusServerGetClientAddress Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a) |
=> a | `server`: A `DBusServer`.
-> m Text | Returns: A D-Bus address string. Do not free, the string is owned by `server`.

Gets a D-Bus address string that can be used by clients to connect to `server`.

Since: 2.26

## getFlags

dBusServerGetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a) |
=> a | `server`: A `DBusServer`.
-> m [DBusServerFlags] | Returns: A set of flags from the `DBusServerFlags` enumeration.

Gets the flags for `server`.

Since: 2.26

## getGuid

dBusServerGetGuid Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a) |
=> a | `server`: A `DBusServer`.
-> m Text | Returns: A D-Bus GUID. Do not free this string, it is owned by `server`.

Gets the GUID for `server`.

Since: 2.26

## isActive

dBusServerIsActive Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a) |
=> a | `server`: A `DBusServer`.
-> m Bool | Returns: `True` if server is active, `False` otherwise.

Gets whether `server` is active.

Since: 2.26

## newSync

dBusServerNewSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusAuthObserver a, IsCancellable b) |
=> Text | `address`: A D-Bus address.
-> [DBusServerFlags] | `flags`: Flags from the `DBusServerFlags` enumeration.
-> Text | `guid`: A D-Bus GUID.
-> Maybe a | `observer`: A `DBusAuthObserver` or `Nothing`.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> m DBusServer | Returns: A `DBusServer` or `Nothing` if `error` is set. Free with `objectUnref`. (Can throw `GError`)

Creates a new D-Bus server that listens on the first address in `address` that works.

Once constructed, you can use `dBusServerGetClientAddress` to get a D-Bus address string that clients can use to connect.

Connect to the `DBusServer`::`new-connection` signal to handle incoming connections.

The returned `DBusServer` isn't active - you have to start it with `dBusServerStart`.

`DBusServer` is used in this [example][gdbus-peer-to-peer].

This is a synchronous failable constructor. See `g_dbus_server_new()` for the asynchronous version.

Since: 2.26

## start

dBusServerStart Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a) |
=> a | `server`: A `DBusServer`.
-> m () |

Starts `server`.

Since: 2.26

## stop

dBusServerStop Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a) |
=> a | `server`: A `DBusServer`.
-> m () |

Stops `server`.

Since: 2.26

# Properties

## active

Whether the server is currently active.

Since: 2.26

getDBusServerActive :: (MonadIO m, IsDBusServer o) => o -> m Bool Source #

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

    get dBusServer #active

## address

The D-Bus address to listen on.

Since: 2.26

constructDBusServerAddress :: IsDBusServer o => Text -> IO (GValueConstruct o) Source #

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

getDBusServerAddress :: (MonadIO m, IsDBusServer o) => o -> m (Maybe Text) Source #

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

    get dBusServer #address

## authenticationObserver

A `DBusAuthObserver` object to assist in the authentication process or `Nothing`.

Since: 2.26

constructDBusServerAuthenticationObserver :: (IsDBusServer o, IsDBusAuthObserver a) => a -> IO (GValueConstruct o) Source #

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

getDBusServerAuthenticationObserver :: (MonadIO m, IsDBusServer o) => o -> m (Maybe DBusAuthObserver) Source #

Get the value of the “`authentication-observer`” property. When overloading is enabled, this is equivalent to

    get dBusServer #authenticationObserver

## clientAddress

The D-Bus address that clients can use.

Since: 2.26

getDBusServerClientAddress :: (MonadIO m, IsDBusServer o) => o -> m Text Source #

Get the value of the “`client-address`” property. When overloading is enabled, this is equivalent to

    get dBusServer #clientAddress

## flags

Flags from the `DBusServerFlags` enumeration.

Since: 2.26

constructDBusServerFlags :: IsDBusServer o => [DBusServerFlags] -> IO (GValueConstruct o) Source #

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

getDBusServerFlags :: (MonadIO m, IsDBusServer o) => o -> m [DBusServerFlags] Source #

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

    get dBusServer #flags

## guid

The guid of the server.

Since: 2.26

constructDBusServerGuid :: IsDBusServer o => Text -> IO (GValueConstruct o) Source #

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

getDBusServerGuid :: (MonadIO m, IsDBusServer o) => o -> m Text Source #

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

    get dBusServer #guid

# Signals

## newConnection

type C_DBusServerNewConnectionCallback = Ptr () -> Ptr DBusConnection -> Ptr () -> IO CInt Source #

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

type DBusServerNewConnectionCallback Source #

Arguments

= DBusConnection | `connection`: A `DBusConnection` for the new connection.
-> IO Bool | Returns: `True` to claim `connection`, `False` to let other handlers run.

Emitted when a new authenticated connection has been made. Use `dBusConnectionGetPeerCredentials` to figure out what identity (if any), was authenticated.

If you want to accept the connection, take a reference to the `connection` object and return `True`. When you are done with the connection call `dBusConnectionClose` and give up your reference. Note that the other peer may disconnect at any time - a typical thing to do when accepting a connection is to listen to the `DBusConnection`::`closed` signal.

If `DBusServer`:`flags` contains `DBusServerFlagsRunInThread` then the signal is emitted in a new thread dedicated to the connection. Otherwise the signal is emitted in the [thread-default main context][g-main-context-push-thread-default] of the thread that `server` was constructed in.

You are guaranteed that signal handlers for this signal runs before incoming messages on `connection` are processed. This means that it's suitable to call `g_dbus_connection_register_object()` or similar from the signal handler.

Since: 2.26

afterDBusServerNewConnection :: (IsDBusServer a, MonadIO m) => a -> DBusServerNewConnectionCallback -> m SignalHandlerId Source #

Connect a signal handler for the “`new-connection`” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dBusServer #newConnection callback

genClosure_DBusServerNewConnection :: DBusServerNewConnectionCallback -> IO Closure Source #

Wrap the callback into a `Closure`.

mk_DBusServerNewConnectionCallback :: C_DBusServerNewConnectionCallback -> IO (FunPtr C_DBusServerNewConnectionCallback) Source #

Generate a function pointer callable from C code, from a `C_DBusServerNewConnectionCallback`.

noDBusServerNewConnectionCallback :: Maybe DBusServerNewConnectionCallback Source #

A convenience synonym for ``Nothing` :: `Maybe` `DBusServerNewConnectionCallback``.

onDBusServerNewConnection :: (IsDBusServer a, MonadIO m) => a -> DBusServerNewConnectionCallback -> m SignalHandlerId Source #

Connect a signal handler for the “`new-connection`” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dBusServer #newConnection callback

wrap_DBusServerNewConnectionCallback :: DBusServerNewConnectionCallback -> C_DBusServerNewConnectionCallback Source #

Wrap a `DBusServerNewConnectionCallback` into a `C_DBusServerNewConnectionCallback`.