Class DBusConnection

Namespace

Tmds.DBus.Protocol

Assembly

Tmds.DBus.Protocol.dll

Represents a client connection to a D-Bus message bus or peer.

public sealed class DBusConnection : IDisposable

Inheritance

object

DBusConnection

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

DBusConnection(string)

Initializes a new instance of the DBusConnection class.

public DBusConnection(string address)

Parameters

address string

The D-Bus address to connect to.

DBusConnection(DBusConnectionOptions)

Initializes a new instance of the DBusConnection class.

public DBusConnection(DBusConnectionOptions connectionOptions)

Parameters

connectionOptions DBusConnectionOptions

The connection options.

Properties

Session

Gets a shared connection to the session bus.

public static DBusConnection Session { get; }

Property Value

DBusConnection

System

Gets a shared connection to the system bus.

public static DBusConnection System { get; }

Property Value

DBusConnection

UniqueName

Gets the unique name assigned to this connection by the bus.

public string? UniqueName { get; }

Property Value

string

Methods

AddMatchAsync<T>(MatchRule, MessageValueReader<T>, Action<Exception?, T, object?, object?>, object?, object?, bool, ObserverFlags)

Adds an observer to receive D-Bus messages matching the specified criteria.

public ValueTask<IDisposable> AddMatchAsync<T>(MatchRule rule, MessageValueReader<T> reader, Action<Exception?, T, object?, object?> handler, object? readerState, object? handlerState, bool emitOnCapturedContext, ObserverFlags flags)

Parameters

rule MatchRule

The match rule defining which messages to receive.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Exception, T, object, object>

Callback invoked for each matched message.

readerState object

Optional state passed to the reader delegate.

handlerState object

Optional state passed to the handler delegate.

emitOnCapturedContext bool

Whether to invoke the handler on the captured synchronization context.

flags ObserverFlags

Observer behavior flags.

Returns

ValueTask<IDisposable>

IDisposable that removes the observer when disposed.

Type Parameters

T

The type of value read from matched messages.

AddMatchAsync<T>(MatchRule, MessageValueReader<T>, Action<Exception?, T, object?, object?>, object?, object?, SynchronizationContext?, ObserverFlags)

Adds an observer to receive D-Bus messages matching the specified criteria.

public ValueTask<IDisposable> AddMatchAsync<T>(MatchRule rule, MessageValueReader<T> reader, Action<Exception?, T, object?, object?> handler, object? readerState, object? handlerState, SynchronizationContext? synchronizationContext, ObserverFlags flags)

Parameters

rule MatchRule

The match rule defining which messages to receive.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Exception, T, object, object>

Callback invoked for each matched message.

readerState object

Optional state passed to the reader delegate.

handlerState object

Optional state passed to the handler delegate.

synchronizationContext SynchronizationContext

The synchronization context to invoke the handler on.

flags ObserverFlags

Observer behavior flags.

Returns

ValueTask<IDisposable>

IDisposable that removes the observer when disposed.

Type Parameters

T

The type of value read from matched messages.

AddMatchAsync<T>(MatchRule, MessageValueReader<T>, Action<Exception?, T, object?, object?>, ObserverFlags, object?, object?, bool)

Adds an observer to receive D-Bus messages matching the specified criteria.

public ValueTask<IDisposable> AddMatchAsync<T>(MatchRule rule, MessageValueReader<T> reader, Action<Exception?, T, object?, object?> handler, ObserverFlags flags, object? readerState = null, object? handlerState = null, bool emitOnCapturedContext = true)

Parameters

rule MatchRule

The match rule defining which messages to receive.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Exception, T, object, object>

Callback invoked for each matched message.

flags ObserverFlags

Observer behavior flags.

readerState object

Optional state passed to the reader delegate.

handlerState object

Optional state passed to the handler delegate.

emitOnCapturedContext bool

Whether to invoke the handler on the captured synchronization context.

Returns

ValueTask<IDisposable>

IDisposable that removes the observer when disposed.

Type Parameters

T

The type of value read from matched messages.

AddMethodHandler(IMethodHandler)

Adds an IMethodHandler to handle incoming method calls.

public void AddMethodHandler(IMethodHandler methodHandler)

Parameters

methodHandler IMethodHandler

The method handler to add.

AddMethodHandler(IPathMethodHandler)

Adds an IPathMethodHandler to handle incoming method calls.

public void AddMethodHandler(IPathMethodHandler methodHandler)

Parameters

methodHandler IPathMethodHandler

The method handler to add.

AddMethodHandlers(IReadOnlyList<IMethodHandler>)

Adds multiple IMethodHandler instances to handle incoming method calls.

public void AddMethodHandlers(IReadOnlyList<IMethodHandler> methodHandlers)

Parameters

methodHandlers IReadOnlyList<IMethodHandler>

The method handlers to add.

AddMethodHandlers(IReadOnlyList<IPathMethodHandler>)

Adds multiple IPathMethodHandler instances to handle incoming method calls.

public void AddMethodHandlers(IReadOnlyList<IPathMethodHandler> methodHandlers)

Parameters

methodHandlers IReadOnlyList<IPathMethodHandler>

The method handlers to add.

AsConnection()

Returns a Connection instance wrapping this DBusConnection.

public Connection AsConnection()

Returns

Connection

A Connection instance.

BecomeMonitorAsync(Action<Exception?, DisposableMessage>, IEnumerable<MatchRule>?)

Becomes a monitor that receives all messages on the bus.

public Task BecomeMonitorAsync(Action<Exception?, DisposableMessage> handler, IEnumerable<MatchRule>? rules = null)

Parameters

handler Action<Exception, DisposableMessage>

The handler invoked for each message received.

rules IEnumerable<MatchRule>

Optional match rules to filter which messages to receive.

Returns

Task

CallMethodAsync(MessageBuffer)

Calls a D-Bus method asynchronously without returning a response value.

public Task CallMethodAsync(MessageBuffer message)

Parameters

message MessageBuffer

The method call message.

Returns

Task

CallMethodAsync<T>(MessageBuffer, MessageValueReader<T>, object?)

Calls a D-Bus method asynchronously and returns a response value.

public Task<T> CallMethodAsync<T>(MessageBuffer message, MessageValueReader<T> reader, object? readerState = null)

Parameters

message MessageBuffer

The method call message.

reader MessageValueReader<T>

The delegate to read the return value from the reply.

readerState object

Optional state passed to the reader delegate.

Returns

Task<T>

Value read from the reply.

Type Parameters

T

The type of the return value.

ConnectAsync()

Establishes the connection.

public ValueTask ConnectAsync()

Returns

ValueTask

DisconnectedAsync()

Returns a task that completes when the connection has disconnected.

public Task<Exception?> DisconnectedAsync()

Returns

Task<Exception>

Exception with the disconnect reason, or null if disposed normally.

Dispose()

Disposes the connection and releases all resources.

public void Dispose()

GetMessageWriter()

Gets a message writer for creating D-Bus messages.

public MessageWriter GetMessageWriter()

Returns

MessageWriter

A new MessageWriter instance.

ListActivatableServicesAsync()

Gets all service names that can be activated on the bus.

public Task<string[]> ListActivatableServicesAsync()

Returns

Task<string[]>

ListServicesAsync()

Lists all currently registered service names on the bus.

public Task<string[]> ListServicesAsync()

Returns

Task<string[]>

A Task containing an array of service names.

MonitorBusAsync(string, IEnumerable<MatchRule>?, CancellationToken)

Monitors a D-Bus bus and returns an IAsyncEnumerable<T> for the observed messages.

public static IAsyncEnumerable<DisposableMessage> MonitorBusAsync(string address, IEnumerable<MatchRule>? rules = null, CancellationToken ct = default)

Parameters

address string

The D-Bus address to connect to.

rules IEnumerable<MatchRule>

Optional match rules to filter which messages to receive.

ct CancellationToken

Cancellation token to stop monitoring.

Returns

IAsyncEnumerable<DisposableMessage>

QueueNameRequestAsync(string, RequestNameOptions)

Enqueues for ownership of a name.

public Task QueueNameRequestAsync(string name, RequestNameOptions options)

Parameters

name string

The name to request.

options RequestNameOptions

Options for requesting the name.

Returns

Task

QueueNameRequestAsync(string, RequestNameOptions, Action<string, object?>?, Action<string, object?>?, object?, bool)

Enqueues for ownership of a name with callbacks for acquisition and loss notifications.

public Task QueueNameRequestAsync(string name, RequestNameOptions options = RequestNameOptions.Default, Action<string, object?>? onAcquired = null, Action<string, object?>? onLost = null, object? actionState = null, bool emitOnCapturedContext = true)

Parameters

name string

The well-known name to request.

options RequestNameOptions

Options for requesting the name.

onAcquired Action<string, object>

Callback invoked when the name is acquired.

onLost Action<string, object>

Callback invoked when the name is lost to another bus user.

actionState object

State object passed to the callbacks.

emitOnCapturedContext bool

Whether to invoke callbacks on the captured synchronization context.

Returns

Task

ReleaseNameAsync(string)

Releases ownership of a name.

public Task<bool> ReleaseNameAsync(string serviceName)

Parameters

serviceName string

The well-known name to release.

Returns

Task<bool>

A Task containing true if the name was released/dequeued; false if the name was not requested by this connection.

RemoveMethodHandler(string)

Removes a method handler for the specified path.

public void RemoveMethodHandler(string path)

Parameters

path string

The object path of the handler to remove.

RemoveMethodHandlers(IEnumerable<string>)

Removes multiple method handlers for the specified paths.

public void RemoveMethodHandlers(IEnumerable<string> paths)

Parameters

paths IEnumerable<string>

The object paths of the handlers to remove.

RequestNameAsync(string, RequestNameOptions)

Requests ownership of a name.

public Task RequestNameAsync(string name, RequestNameOptions options)

Parameters

name string

The name to request.

options RequestNameOptions

Options for requesting the name.

Returns

Task

RequestNameAsync(string, RequestNameOptions, Action<string, object?>?, object?, bool)

Requests ownership of a name with callback for name loss notification.

public Task RequestNameAsync(string name, RequestNameOptions options = RequestNameOptions.Default, Action<string, object?>? onLost = null, object? actionState = null, bool emitOnCapturedContext = true)

Parameters

name string

The name to request.

options RequestNameOptions

Options for requesting the name.

onLost Action<string, object>

Callback invoked when the name is lost to another connection.

actionState object

State object passed to the callback.

emitOnCapturedContext bool

Whether to invoke the callback on the captured synchronization context.

Returns

Task

TryRequestNameAsync(string, RequestNameOptions)

Tries to request ownership of a name.

public Task<bool> TryRequestNameAsync(string name, RequestNameOptions options)

Parameters

name string

The name to request.

options RequestNameOptions

Options for requesting the name.

Returns

Task<bool>

true if the name was acquired; false if already owned by another bus user.

TryRequestNameAsync(string, RequestNameOptions, Action<string, object?>?, object?, bool)

Tries to request ownership of a name with callback for name loss notification.

public Task<bool> TryRequestNameAsync(string name, RequestNameOptions options = RequestNameOptions.Default, Action<string, object?>? onLost = null, object? actionState = null, bool emitOnCapturedContext = true)

Parameters

name string

The name to request.

options RequestNameOptions

Options for requesting the name.

onLost Action<string, object>

Callback invoked when the name is lost to another connection.

actionState object

State object passed to the callback.

emitOnCapturedContext bool

Whether to invoke the callback on the captured synchronization context.

Returns

Task<bool>

true if the name was acquired; false if already owned by another connection.

TrySendMessage(MessageBuffer)

Sends a D-Bus message.

public bool TrySendMessage(MessageBuffer message)

Parameters

message MessageBuffer

The message to send.

Returns

bool

true if the message was sent; false if not connected.

WatchPropertiesChangedAsync<T>(string?, string?, string, MessageValueReader<T>, Action<Exception?, T>, object?, bool, ObserverFlags)

Watches for property changes.

public ValueTask<IDisposable> WatchPropertiesChangedAsync<T>(string? sender, string? path, string @interface, MessageValueReader<T> reader, Action<Exception?, T> handler, object? readerState, bool emitOnCapturedContext, ObserverFlags flags)

Parameters

sender string

path string

interface string

reader MessageValueReader<T>

handler Action<Exception, T>

readerState object

emitOnCapturedContext bool

flags ObserverFlags

Returns

ValueTask<IDisposable>

Type Parameters

T

WatchSignalAsync(string?, string?, string, string, Action<Exception?>, object?, bool, ObserverFlags)

Watches for a D-Bus signal.

public ValueTask<IDisposable> WatchSignalAsync(string? sender, string? path, string @interface, string signal, Action<Exception?> handler, object? readerState, bool emitOnCapturedContext, ObserverFlags flags)

Parameters

sender string

path string

interface string

signal string

handler Action<Exception>

readerState object

emitOnCapturedContext bool

flags ObserverFlags

Returns

ValueTask<IDisposable>

WatchSignalAsync<T>(string?, string?, string, string, MessageValueReader<T>, Action<Exception?, T>, object?, bool, ObserverFlags)

Watches for a D-Bus signal.

public ValueTask<IDisposable> WatchSignalAsync<T>(string? sender, string? path, string @interface, string signal, MessageValueReader<T> reader, Action<Exception?, T> handler, object? readerState, bool emitOnCapturedContext, ObserverFlags flags)

Parameters

sender string

path string

interface string

signal string

reader MessageValueReader<T>

handler Action<Exception, T>

readerState object

emitOnCapturedContext bool

flags ObserverFlags

Returns

ValueTask<IDisposable>

Type Parameters

T