Class Discover

Namespace

KasaTapoClient

Assembly

KasaTapoClient.dll

Provides discovery helpers similar to python-kasa's Discover entry point.

public static class Discover

Inheritance

object

Discover

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Methods

ConnectAsync(DeviceConfiguration, bool, CancellationToken)

Connects using a complete device configuration and optionally loads the initial device state.

public static Task<KasaDevice> ConnectAsync(DeviceConfiguration configuration, bool updateState, CancellationToken cancellationToken = default)

Parameters

configuration DeviceConfiguration

The device configuration.

updateState bool

true to load device state before returning; otherwise, false.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<KasaDevice>

A device instance ready for direct commands.

Remarks

If a connect for this device identity (host/port) is already in flight from another concurrent caller — using an equivalent configuration (same credentials, timeout, and connection options) — this call joins that same in-flight attempt and returns its resulting KasaDevice instance instead of opening a second, redundant connection. This coalescing only applies while a connect is actively in progress; it does not cache or share device instances across separate, non-overlapping calls; "updateState" only applies to the caller that actually initiates the underlying connect. Each call that does not overlap an in-flight connect for the same identity, or that specifies a materially different configuration than the in-flight connect for that identity, receives its own new, independently owned KasaDevice instance, which the caller is responsible for disposing when done.

Exceptions

TimeoutException

Thrown when automatic transport resolution cannot obtain a matching discovery result for the configured host.

ConnectAsync(DeviceConfiguration, CancellationToken)

Connects using a complete device configuration and returns a ready-to-use device instance.

public static Task<KasaDevice> ConnectAsync(DeviceConfiguration configuration, CancellationToken cancellationToken = default)

Parameters

configuration DeviceConfiguration

The device configuration.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<KasaDevice>

A device instance with current system information loaded.

Remarks

See the remarks on ConnectAsync(DeviceConfiguration, bool, CancellationToken) for details on in-flight connect coalescing.

Exceptions

TimeoutException

Thrown when automatic transport resolution cannot obtain a matching discovery result for the configured host.

ConnectAsync(DiscoveryResult, bool, DeviceCredentials?, TimeSpan?, CancellationToken)

Connects to a discovered device using the connection parameters parsed from its discovery result.

public static Task<KasaDevice> ConnectAsync(DiscoveryResult discoveryResult, bool updateState = true, DeviceCredentials? credentials = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

discoveryResult DiscoveryResult

The discovery result to connect with.

updateState bool

true to load device state before returning; otherwise, false.

credentials DeviceCredentials

Optional credentials used by newer authenticated devices.

timeout TimeSpan?

The per-operation timeout. If null, a five second timeout is used.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<KasaDevice>

A connected device instance.

Exceptions

ArgumentNullException

Thrown when discoveryResult is null.

CreateConfiguration(DiscoveryResult, DeviceCredentials?, TimeSpan?)

Creates a device configuration directly from a discovery result.

public static DeviceConfiguration CreateConfiguration(DiscoveryResult discoveryResult, DeviceCredentials? credentials = null, TimeSpan? timeout = null)

Parameters

discoveryResult DiscoveryResult

The discovery result to convert.

credentials DeviceCredentials

Optional credentials used by newer authenticated devices.

timeout TimeSpan?

The per-operation timeout. If null, a five second timeout is used.

Returns

DeviceConfiguration

A device configuration derived from the discovery metadata.

Exceptions

ArgumentNullException

Thrown when discoveryResult is null.

DiscoverAsync(TimeSpan?, string, CancellationToken)

Broadcasts a discovery request and returns all responses collected within the timeout window.

public static Task<IReadOnlyList<DiscoveryResult>> DiscoverAsync(TimeSpan? timeout = null, string target = "255.255.255.255", CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan?

The discovery timeout. If null, a three second timeout is used.

target string

The discovery target address. The default is the IPv4 broadcast address.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<IReadOnlyList<DiscoveryResult>>

A read-only collection of discovery responses.

Exceptions

OperationCanceledException

Thrown when the discovery operation is canceled.

DiscoverLegacyAsync(TimeSpan?, string, CancellationToken)

Broadcasts only the legacy UDP discovery request on port 9999.

public static Task<IReadOnlyList<DiscoveryResult>> DiscoverLegacyAsync(TimeSpan? timeout = null, string target = "255.255.255.255", CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan?

target string

cancellationToken CancellationToken

Returns

Task<IReadOnlyList<DiscoveryResult>>

DiscoverSingleAsync(string, int, DeviceCredentials?, DeviceConnectionOptions?, TimeSpan?, CancellationToken)

Connects to a single device host and returns a ready-to-use device instance.

public static Task<KasaDevice> DiscoverSingleAsync(string host, int port = 9999, DeviceCredentials? credentials = null, DeviceConnectionOptions? connectionOptions = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

host string

The device host name or IP address.

port int

The device control port.

credentials DeviceCredentials

Optional credentials used by newer authenticated devices.

connectionOptions DeviceConnectionOptions

Transport-specific connection options used to select the device protocol.

timeout TimeSpan?

The per-operation timeout. If null, a five second timeout is used.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<KasaDevice>

A device instance with current system information loaded.

Exceptions

TimeoutException

Thrown when automatic transport resolution cannot obtain a matching discovery result for host.

GetOrConnectSharedAsync(DeviceConfiguration, bool, CancellationToken)

Returns a long-lived KasaDevice instance shared by every caller that requests the same device identity (host/port), connecting only if no live shared instance already exists for that identity.

public static Task<KasaDevice> GetOrConnectSharedAsync(DeviceConfiguration configuration, bool updateState = true, CancellationToken cancellationToken = default)

Parameters

configuration DeviceConfiguration

The device configuration.

updateState bool

true to load device state when a new connection is created; otherwise, false.

cancellationToken CancellationToken

The cancellation token for the operation.

Returns

Task<KasaDevice>

A shared device instance.

Remarks

Unlike ConnectAsync(DeviceConfiguration, bool, CancellationToken), which always returns an instance newly and exclusively owned by the calling code (except while a connect is actively in flight), this method is an explicit, opt-in way for multiple, independent call sites that are known to target the same device to reuse a single connection instead of each opening their own. This matters for devices that reject or reset additional concurrent sessions.

The returned instance is shared. Do not call Dispose() on it unless you are certain no other caller still depends on it - disposing a shared instance affects every other holder immediately. If you need an instance that only you own and control the lifetime of, use ConnectAsync(DeviceConfiguration, bool, CancellationToken) instead.

If the previously cached instance for this identity has been disposed (by any holder), this method transparently creates and caches a fresh replacement rather than returning a dead instance - the same recovery model LegacyTransport already uses for stale/idle connections. There is no reference counting; callers are responsible for coordinating who, if anyone, disposes the shared instance and when.

If a live shared instance already exists for this identity but was created from a materially different configuration (different credentials, timeout, or connection options) than the one passed to this call, the mismatch is treated the same as a disposed instance: a fresh, independent connection is created and becomes the new shared instance for this identity, rather than silently returning an instance built from a different caller's configuration.