library/org.meshtastic.mqtt/ProbeResult

ProbeResult

Outcome of a one-shot connectivity probe issued via MqttClient.probe.

A probe attempts a full CONNECT/CONNACK handshake against an MqttEndpoint using a transient connection, then tears it down. Unlike MqttClient.connect, a probe never throws for connectivity failures — every outcome (success, broker rejection, transport error, timeout) is reported as a ProbeResult subclass so UI layers can render structured diagnostic feedback.

Cancellation of the calling coroutine is propagated normally and will abort the probe; only kotlinx.coroutines.CancellationException escapes.

Example

when (val result = MqttClient.probe(MqttEndpoint.Tcp("broker.example.com", 1883))) {
    is ProbeResult.Success     -> showOk("Reachable")
    is ProbeResult.Rejected    -> showError("Broker rejected: ${result.reasonCode}")
    is ProbeResult.DnsFailure  -> showError("Host not found")
    is ProbeResult.TcpFailure  -> showError("Connection refused")
    is ProbeResult.TlsFailure  -> showError("TLS handshake failed: ${result.cause.message}")
    is ProbeResult.Timeout     -> showError("Timed out after ${result.durationMs}ms")
    is ProbeResult.Other       -> showError("Connection failed: ${result.cause.message}")
}

Inheritors

Types

DnsFailure

data class DnsFailure(val cause: Throwable) : ProbeResult

Hostname resolution failed — the broker host could not be looked up via DNS.

Other

data class Other(val cause: Throwable) : ProbeResult

Catch-all for failures that don't fit any other category.

Rejected

data class Rejected(val reasonCode: ReasonCode, val message: String, val serverReference: String? = null) : ProbeResult

The broker accepted the TCP/TLS connection but refused the CONNECT request via CONNACK.

Success

data class Success(val serverInfo: ProbeServerInfo) : ProbeResult

The broker accepted the CONNECT and returned a successful CONNACK.

TcpFailure

data class TcpFailure(val cause: Throwable) : ProbeResult

TCP-level failure — connection refused, network unreachable, or socket reset before the MQTT handshake could begin.

Timeout

data class Timeout(val durationMs: Long) : ProbeResult

The probe did not complete within the requested timeout. The transport may have hung mid-handshake (broker accepted the TCP connection but never sent CONNACK).

TlsFailure

data class TlsFailure(val cause: Throwable) : ProbeResult

TLS handshake failed — certificate validation rejected the broker, the broker does not speak TLS on this port, or the negotiated protocol/cipher is unsupported.