GI.Gio.Objects.DBusServer

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 GDBus can be found in gdbus-example-peer.c.

Note that a minimal DBusServer 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 DBusServer. Since GLib 2.68 this can be achieved more simply by passing the DBusServerFlagsAuthenticationRequireSameUser flag to the server.

Since: 2.26

Exported types

newtype DBusServer

Memory-managed wrapper type.

Constructors

DBusServer (ManagedPtr DBusServer)

Instances

Eq DBusServer

Defined in GI.Gio.Objects.DBusServer

Methods

(==) :: DBusServer -> DBusServer -> Bool

(/=) :: DBusServer -> DBusServer -> Bool

GObject DBusServer

Defined in GI.Gio.Objects.DBusServer

ManagedPtrNewtype DBusServer

Defined in GI.Gio.Objects.DBusServer

Methods

toManagedPtr :: DBusServer -> ManagedPtr DBusServer

TypedObject DBusServer

Defined in GI.Gio.Objects.DBusServer

Methods

glibType :: IO GType

HasParentTypes DBusServer

Defined in GI.Gio.Objects.DBusServer

IsGValue (Maybe DBusServer)

Convert DBusServer to and from GValue. See toGValue and fromGValue.

Defined in GI.Gio.Objects.DBusServer

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe DBusServer -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe DBusServer)

type ParentTypes DBusServer

Defined in GI.Gio.Objects.DBusServer

type ParentTypes DBusServer = '[Object, Initable]

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

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

Instances

(GObject o, IsDescendantOf DBusServer o) => IsDBusServer o

Defined in GI.Gio.Objects.DBusServer

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

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

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

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

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

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

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

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

Arguments

:: (HasCallStack, MonadIO m, IsDBusServer a)

=> a

server: A DBusServer.

-> m ()

Starts server.

Since: 2.26

stop

dBusServerStop

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

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)

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)

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)

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)

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

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)

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]

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)

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

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

get dBusServer #guid

Signals

newConnection

type DBusServerNewConnectionCallback

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

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

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