gi-gio-2.0.35: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
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

`GDBusServer` 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 `busOwnName`.

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

Note that a minimal `GDBusServer` will accept connections from any peer. In many use-cases it will be necessary to add a `DBusAuthObserver` that only accepts connections that have successfully authenticated as the same user that is running the `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the server.

Since: 2.26

Synopsis

- newtype DBusServer = DBusServer (ManagedPtr DBusServer)
- class (GObject o, IsDescendantOf DBusServer o) => IsDBusServer o
- toDBusServer :: (MonadIO m, IsDBusServer o) => o -> m 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, MonadIO m) => Text -> m (GValueConstruct o)
- getDBusServerAddress :: (MonadIO m, IsDBusServer o) => o -> m (Maybe Text)
- constructDBusServerAuthenticationObserver :: (IsDBusServer o, MonadIO m, IsDBusAuthObserver a) => a -> m (GValueConstruct o)
- getDBusServerAuthenticationObserver :: (MonadIO m, IsDBusServer o) => o -> m (Maybe DBusAuthObserver)
- getDBusServerClientAddress :: (MonadIO m, IsDBusServer o) => o -> m Text
- constructDBusServerFlags :: (IsDBusServer o, MonadIO m) => [DBusServerFlags] -> m (GValueConstruct o)
- getDBusServerFlags :: (MonadIO m, IsDBusServer o) => o -> m [DBusServerFlags]
- constructDBusServerGuid :: (IsDBusServer o, MonadIO m) => Text -> m (GValueConstruct o)
- getDBusServerGuid :: (MonadIO m, IsDBusServer o) => o -> m Text
- type DBusServerNewConnectionCallback = DBusConnection -> IO Bool
- afterDBusServerNewConnection :: (IsDBusServer a, MonadIO m) => a -> ((?self :: a) => DBusServerNewConnectionCallback) -> m SignalHandlerId
- onDBusServerNewConnection :: (IsDBusServer a, MonadIO m) => a -> ((?self :: a) => DBusServerNewConnectionCallback) -> m SignalHandlerId

# Exported types

newtype DBusServer Source #

Memory-managed wrapper type.

Constructors

DBusServer (ManagedPtr DBusServer) |

#### Instances

Instances details

Eq DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer Methods (==) :: DBusServer -> DBusServer -> Bool Source # (/=) :: DBusServer -> DBusServer -> Bool Source #
GObject DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer
ManagedPtrNewtype DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer Methods toManagedPtr :: DBusServer -> ManagedPtr DBusServer Source #
TypedObject DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer Methods glibType :: IO GType Source #
HasParentTypes DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer
IsGValue (Maybe DBusServer) Source # | Convert `DBusServer` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Objects.DBusServer Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe DBusServer -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe DBusServer) Source #
type ParentTypes DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer type ParentTypes DBusServer = '[Object, Initable]

class (GObject o, IsDescendantOf DBusServer o) => IsDBusServer o Source #

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

#### Instances

Instances details

(GObject o, IsDescendantOf DBusServer o) => IsDBusServer o 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`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, init, isActive, isFloating, notify, notifyByPspec, ref, refSink, runDispose, start, stealData, stealQdata, stop, thawNotify, unref, watchClosure.

#### Getters

getClientAddress, getData, getFlags, getGuid, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

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

This is valid and non-empty if initializing the `DBusServer` succeeded.

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`, as provided to `dBusServerNewSync`.

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.

To have control over the available authentication mechanisms and the users that are authorized to connect, it is strongly recommended to provide a non-`Nothing` `DBusAuthObserver`.

Connect to the DBusServer::newConnection 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. There is currently no 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, MonadIO m) => Text -> m (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, MonadIO m, IsDBusAuthObserver a) => a -> m (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, MonadIO m) => [DBusServerFlags] -> m (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.

See DBusConnection:guid for more details.

Since: 2.26

constructDBusServerGuid :: (IsDBusServer o, MonadIO m) => Text -> m (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 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 -> ((?self :: a) => DBusServerNewConnectionCallback) -> m SignalHandlerId Source #

Connect a signal handler for the newConnection signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dBusServer #newConnection callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

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

Connect a signal handler for the newConnection signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dBusServer #newConnection callback