Class NameOwnerWatcher

Namespace

Tmds.DBus.Protocol

Assembly

Tmds.DBus.Protocol.dll

Tracks the current owner of a well-known name.

public sealed class NameOwnerWatcher : IDisposable

Inheritance

object

NameOwnerWatcher

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

On D-Bus, well-known names (like org.freedesktop.NetworkManager) can change owners when services restart or are replaced. This class enables callers to detect owner changes so they can direct messages to a specific owner instance and react when that owner goes away.

The owner identifier string returned by GetCurrentOwner() and WaitForOwnerAsync(CancellationToken) is an opaque string that combines the well-known name with the unique name of the current owner. It can be used as the destination when making method calls or as the sender in a MatchRule to ensure communication is bound to a specific owner. Use GetOwnerBusName(string) to extract the unique bus name from the owner identifier.

Methods

Dispose()

Disposes the watcher and releases the subscription.

public void Dispose()

Remarks

This method is not thread-safe and must not be called concurrently with other instance methods.

GetCurrentOwner()

Returns the current owner identifier, or null if the well-known name has no owner or the connection has disconnected.

public string? GetCurrentOwner()

Returns

string

GetOwnerBusName(string)

Extracts the unique bus name of the owner from an owner identifier string.

public static string GetOwnerBusName(string ownerIdentifier)

Parameters

ownerIdentifier string

An owner identifier string as returned by GetCurrentOwner() or WaitForOwnerAsync(CancellationToken).

Returns

string

The unique bus name (e.g. :1.42).

Exceptions

ArgumentException

Thrown when the string is not a valid owner identifier.

GetOwnerChangedCancellationToken(string)

Returns a CancellationToken that is cancelled when the owner changes from currentOwner. If the owner has already changed or the connection has disconnected, the returned token is already cancelled.

public CancellationToken GetOwnerChangedCancellationToken(string currentOwner)

Parameters

currentOwner string

The expected current owner.

Returns

CancellationToken

A cancellation token that is cancelled when the owner changes.

WaitForOwnerAsync(CancellationToken)

Waits until the well-known name has an owner and returns the owner identifier. If the name already has an owner, returns immediately.

public Task<string> WaitForOwnerAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<string>

The owner identifier of the current owner.