gi-gio-2.0.32: 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.DBusAuthObserver

Contents

- Exported types
- Methods
  - allowMechanism
  - authorizeAuthenticatedPeer
  - new
- Signals
  - allowMechanism
  - authorizeAuthenticatedPeer

Description

`GDBusAuthObserver` provides a mechanism for participating in how a `DBusServer` (or a `DBusConnection`) authenticates remote peers.

Simply instantiate a `GDBusAuthObserver` and connect to the signals you are interested in. Note that new signals may be added in the future.

## Controlling Authentication Mechanisms

By default, a `GDBusServer` or server-side `GDBusConnection` will allow any authentication mechanism to be used. If you only want to allow D-Bus connections with the `EXTERNAL` mechanism, which makes use of credentials passing and is the recommended mechanism for modern Unix platforms such as Linux and the BSD family, you would use a signal handler like this:

### c code

    static gboolean
    on_allow_mechanism (GDBusAuthObserver *observer,
                        const gchar       *mechanism,
                        gpointer           user_data)
    {
      if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
        {
          return TRUE;
        }

      return FALSE;
    }

## Controlling Authorization

By default, a `GDBusServer` or server-side `GDBusConnection` will accept connections from any successfully authenticated user (but not from anonymous connections using the `ANONYMOUS` mechanism). If you only want to allow D-Bus connections from processes owned by the same uid as the server, since GLib 2.68, you should use the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag. It’s equivalent to the following signal handler:

### c code

    static gboolean
    on_authorize_authenticated_peer (GDBusAuthObserver *observer,
                                     GIOStream         *stream,
                                     GCredentials      *credentials,
                                     gpointer           user_data)
    {
      gboolean authorized;

      authorized = FALSE;
      if (credentials != NULL)
        {
          GCredentials *own_credentials;
          own_credentials = g_credentials_new ();
          if (g_credentials_is_same_user (credentials, own_credentials, NULL))
            authorized = TRUE;
          g_object_unref (own_credentials);
        }

      return authorized;
    }

Since: 2.26

Synopsis

- newtype DBusAuthObserver = DBusAuthObserver (ManagedPtr DBusAuthObserver)
- class (GObject o, IsDescendantOf DBusAuthObserver o) => IsDBusAuthObserver o
- toDBusAuthObserver :: (MonadIO m, IsDBusAuthObserver o) => o -> m DBusAuthObserver
- dBusAuthObserverAllowMechanism :: (HasCallStack, MonadIO m, IsDBusAuthObserver a) => a -> Text -> m Bool
- dBusAuthObserverAuthorizeAuthenticatedPeer :: (HasCallStack, MonadIO m, IsDBusAuthObserver a, IsIOStream b, IsCredentials c) => a -> b -> Maybe c -> m Bool
- dBusAuthObserverNew :: (HasCallStack, MonadIO m) => m DBusAuthObserver
- type DBusAuthObserverAllowMechanismCallback = Text -> IO Bool
- afterDBusAuthObserverAllowMechanism :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAllowMechanismCallback) -> m SignalHandlerId
- onDBusAuthObserverAllowMechanism :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAllowMechanismCallback) -> m SignalHandlerId
- type DBusAuthObserverAuthorizeAuthenticatedPeerCallback = IOStream -> Maybe Credentials -> IO Bool
- afterDBusAuthObserverAuthorizeAuthenticatedPeer :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAuthorizeAuthenticatedPeerCallback) -> m SignalHandlerId
- onDBusAuthObserverAuthorizeAuthenticatedPeer :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAuthorizeAuthenticatedPeerCallback) -> m SignalHandlerId

# Exported types

newtype DBusAuthObserver Source #

Memory-managed wrapper type.

Constructors

DBusAuthObserver (ManagedPtr DBusAuthObserver) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf DBusAuthObserver o) => IsDBusAuthObserver o Source #

Type class for types which can be safely cast to `DBusAuthObserver`, for instance with `toDBusAuthObserver`.

#### Instances

Instances details

(GObject o, IsDescendantOf DBusAuthObserver o) => IsDBusAuthObserver o Source # |
Instance details Defined in GI.Gio.Objects.DBusAuthObserver

toDBusAuthObserver :: (MonadIO m, IsDBusAuthObserver o) => o -> m DBusAuthObserver Source #

Cast to `DBusAuthObserver`, 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

allowMechanism, authorizeAuthenticatedPeer, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## allowMechanism

dBusAuthObserverAllowMechanism Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusAuthObserver a) |
=> a | `observer`: A `DBusAuthObserver`.
-> Text | `mechanism`: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
-> m Bool | Returns: `True` if `mechanism` can be used to authenticate the other peer, `False` if not.

Emits the DBusAuthObserver::allowMechanism signal on `observer`.

Since: 2.34

## authorizeAuthenticatedPeer

dBusAuthObserverAuthorizeAuthenticatedPeer Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusAuthObserver a, IsIOStream b, IsCredentials c) |
=> a | `observer`: A `DBusAuthObserver`.
-> b | `stream`: A `IOStream` for the `DBusConnection`.
-> Maybe c | `credentials`: Credentials received from the peer or `Nothing`.
-> m Bool | Returns: `True` if the peer is authorized, `False` if not.

Emits the DBusAuthObserver::authorizeAuthenticatedPeer signal on `observer`.

Since: 2.26

## new

dBusAuthObserverNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m DBusAuthObserver | Returns: A `DBusAuthObserver`. Free with `objectUnref`.

Creates a new `DBusAuthObserver` object.

Since: 2.26

# Signals

## allowMechanism

type DBusAuthObserverAllowMechanismCallback Source #

Arguments

= Text | `mechanism`: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
-> IO Bool | Returns: `True` if `mechanism` can be used to authenticate the other peer, `False` if not.

Emitted to check if `mechanism` is allowed to be used.

Since: 2.34

afterDBusAuthObserverAllowMechanism :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAllowMechanismCallback) -> m SignalHandlerId Source #

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

    after dBusAuthObserver #allowMechanism 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.

onDBusAuthObserverAllowMechanism :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAllowMechanismCallback) -> m SignalHandlerId Source #

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

    on dBusAuthObserver #allowMechanism callback

## authorizeAuthenticatedPeer

type DBusAuthObserverAuthorizeAuthenticatedPeerCallback Source #

Arguments

= IOStream | `stream`: A `IOStream` for the `DBusConnection`.
-> Maybe Credentials | `credentials`: Credentials received from the peer or `Nothing`.
-> IO Bool | Returns: `True` if the peer is authorized, `False` if not.

Emitted to check if a peer that is successfully authenticated is authorized.

Since: 2.26

afterDBusAuthObserverAuthorizeAuthenticatedPeer :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAuthorizeAuthenticatedPeerCallback) -> m SignalHandlerId Source #

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

    after dBusAuthObserver #authorizeAuthenticatedPeer 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.

onDBusAuthObserverAuthorizeAuthenticatedPeer :: (IsDBusAuthObserver a, MonadIO m) => a -> ((?self :: a) => DBusAuthObserverAuthorizeAuthenticatedPeerCallback) -> m SignalHandlerId Source #

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

    on dBusAuthObserver #authorizeAuthenticatedPeer callback