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(MatchRule, Action<Notification>, bool, ObserverFlags, object?)

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

public ValueTask<IDisposable> AddMatchAsync(MatchRule rule, Action<Notification> handler, bool emitOnCapturedContext = true, ObserverFlags flags = ObserverFlags.None, object? state = null)

Parameters

rule MatchRule

The match rule defining which messages to receive.

handler Action<Notification>

Callback invoked for matched messages and completion notifications.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

AddMatchAsync(MatchRule, Action<Notification>, SynchronizationContext?, ObserverFlags, object?)

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

public ValueTask<IDisposable> AddMatchAsync(MatchRule rule, Action<Notification> handler, SynchronizationContext? synchronizationContext, ObserverFlags flags, object? state)

Parameters

rule MatchRule

The match rule defining which messages to receive.

handler Action<Notification>

Callback invoked for matched messages and completion notifications.

synchronizationContext SynchronizationContext

The synchronization context to invoke the handler on.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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.

[Obsolete("Use the overload that accepts Action<Notification<T>> instead.")]
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 matched messages and completion notifications.

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 current synchronization context.

flags ObserverFlags

Observer behavior flags.

Returns

ValueTask<IDisposable>

IDisposable that stops 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.

[Obsolete("Use the overload that accepts Action<Notification<T>> instead.")]
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 matched messages and completion notifications.

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 stops 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.

[Obsolete("Use the overload that accepts Action<Notification<T>> instead.")]
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 matched messages and completion notifications.

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 current synchronization context.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

The type of value read from matched messages.

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

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

public ValueTask<IDisposable> AddMatchAsync<T>(MatchRule rule, MessageValueReader<T> reader, Action<Notification<T>> handler, bool emitOnCapturedContext = true, ObserverFlags flags = ObserverFlags.None, object? state = null)

Parameters

rule MatchRule

The match rule defining which messages to receive.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Notification<T>>

Callback invoked for matched messages and completion notifications.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

The type of value read from matched messages.

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

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

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

Parameters

rule MatchRule

The match rule defining which messages to receive.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Notification<T>>

Callback invoked for matched messages and completion notifications.

synchronizationContext SynchronizationContext

The synchronization context to invoke the handler on.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

The type of value read from matched messages.

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

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

Exceptions

DBusOwnerChangedException

The message destination uses an owner identifier from NameOwnerWatcher and the owner of the name has changed.

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.

Exceptions

DBusOwnerChangedException

The message destination uses an owner identifier from NameOwnerWatcher and the owner of the name has changed.

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.

Remarks

Owner identifier destinations from NameOwnerWatcher are not supported by this API.

WatchNameOwnerAsync(string)

Watches for the owner of a D-Bus well-known name.

public Task<NameOwnerWatcher> WatchNameOwnerAsync(string name)

Parameters

name string

The well-known name to watch.

Returns

Task<NameOwnerWatcher>

A NameOwnerWatcher that can be used to wait for the name owner.

Exceptions

ArgumentException

name is a unique connection name or an owner identifier.

InvalidOperationException

The connection is not connected to a bus, or name is the D-Bus service name.

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

Watches for property changes.

[Obsolete("Use the overload that accepts Action<Notification<T>> instead.")]
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

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Exception, T>

Callback invoked for matched signals and completion notifications.

readerState object

Optional state passed to the reader delegate.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

flags ObserverFlags

Observer behavior flags.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

WatchPropertiesChangedAsync<T>(string?, string?, string, MessageValueReader<T>, Action<Notification<T>>, SynchronizationContext?, ObserverFlags, object?)

Watches for property changes.

public ValueTask<IDisposable> WatchPropertiesChangedAsync<T>(string? sender, string? path, string @interface, MessageValueReader<T> reader, Action<Notification<T>> handler, SynchronizationContext? synchronizationContext, ObserverFlags flags, object? state)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Notification<T>>

Callback invoked for matched signals and completion notifications.

synchronizationContext SynchronizationContext

The synchronization context to invoke the handler on.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

Watches for property changes.

public ValueTask<IDisposable> WatchPropertiesChangedAsync<T>(string? sender, string? path, string @interface, MessageValueReader<T> reader, Action<Notification<T>> handler, ObserverFlags flags, bool emitOnCapturedContext = true, object? state = null)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Notification<T>>

Callback invoked for matched signals and completion notifications.

flags ObserverFlags

Observer behavior flags.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

Watches for a D-Bus signal.

[Obsolete("Use the overload that accepts Action<Notification> instead.")]
public ValueTask<IDisposable> WatchSignalAsync(string? sender, string? path, string @interface, string signal, Action<Exception?> handler, object? readerState, bool emitOnCapturedContext, ObserverFlags flags)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

signal string

The signal name.

handler Action<Exception>

Callback invoked for matched signals and completion notifications.

readerState object

Optional state passed to the reader delegate.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

flags ObserverFlags

Observer behavior flags.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

WatchSignalAsync(string?, string?, string, string, Action<Notification>, SynchronizationContext?, ObserverFlags, object?)

Watches for a D-Bus signal.

public ValueTask<IDisposable> WatchSignalAsync(string? sender, string? path, string @interface, string signal, Action<Notification> handler, SynchronizationContext? synchronizationContext, ObserverFlags flags, object? state)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

signal string

The signal name.

handler Action<Notification>

Callback invoked for matched signals and completion notifications.

synchronizationContext SynchronizationContext

The synchronization context to invoke the handler on.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

Watches for a D-Bus signal.

public ValueTask<IDisposable> WatchSignalAsync(string? sender, string? path, string @interface, string signal, Action<Notification> handler, ObserverFlags flags, bool emitOnCapturedContext = true, object? state = null)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

signal string

The signal name.

handler Action<Notification>

Callback invoked for matched signals and completion notifications.

flags ObserverFlags

Observer behavior flags.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

Watches for a D-Bus signal.

[Obsolete("Use the overload that accepts Action<Notification<T>> instead.")]
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

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

signal string

The signal name.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Exception, T>

Callback invoked for matched signals and completion notifications.

readerState object

Optional state passed to the reader delegate.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

flags ObserverFlags

Observer behavior flags.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

WatchSignalAsync<T>(string?, string?, string, string, MessageValueReader<T>, Action<Notification<T>>, SynchronizationContext?, ObserverFlags, object?)

Watches for a D-Bus signal.

public ValueTask<IDisposable> WatchSignalAsync<T>(string? sender, string? path, string @interface, string signal, MessageValueReader<T> reader, Action<Notification<T>> handler, SynchronizationContext? synchronizationContext, ObserverFlags flags, object? state)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

signal string

The signal name.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Notification<T>>

Callback invoked for matched signals and completion notifications.

synchronizationContext SynchronizationContext

The synchronization context to invoke the handler on.

flags ObserverFlags

Observer behavior flags.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.

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

Watches for a D-Bus signal.

public ValueTask<IDisposable> WatchSignalAsync<T>(string? sender, string? path, string @interface, string signal, MessageValueReader<T> reader, Action<Notification<T>> handler, ObserverFlags flags, bool emitOnCapturedContext = true, object? state = null)

Parameters

sender string

The sender to match (optional).

path string

The object path to match (optional).

interface string

The interface name.

signal string

The signal name.

reader MessageValueReader<T>

Delegate to read values from matched messages.

handler Action<Notification<T>>

Callback invoked for matched signals and completion notifications.

flags ObserverFlags

Observer behavior flags.

emitOnCapturedContext bool

Whether to invoke the handler on the current synchronization context.

state object

Optional state object.

Returns

ValueTask<IDisposable>

IDisposable that stops the observer when disposed.

Type Parameters

T

Remarks

The handler must not throw exceptions. If the handler throws, the connection will be disconnected.