Class MqttClient

Namespace

Pamoja.Mqtt

Assembly

Pamoja.Mqtt.dll

An MQTT client transport, the ergonomic facade over the native pamoja core.

public sealed class MqttClient : IAsyncEnumerable<MqttMessage>, IAsyncDisposable, IDisposable

Inheritance

object

MqttClient

Implements

IAsyncEnumerable<MqttMessage>

IAsyncDisposable

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

await using var client = new MqttClient(new MqttClientOptions
{
    ClientId = "sensor-1",
    Host = "localhost",
    Port = 1883,
});
await client.ConnectAsync();
await client.SubscribeAsync("sensors/+/temperature");
await client.PublishAsync("sensors/1/temperature", "21.5");
await foreach (var message in client)
{
    Console.WriteLine($"{message.Topic}: {message.Payload.Length} bytes");
}

Remarks

The native C ABI is synchronous, so every operation runs on the thread pool and is awaited here; failures surface as PamojaException. Construct the client with broker settings, ConnectAsync(), then PublishAsync(string, ReadOnlyMemory<byte>), SubscribeAsync(string), and read inbound messages with RecvAsync() or by iterating the client with await foreach.

Constructors

MqttClient(MqttClientOptions)

Creates a disconnected client from the given options.

public MqttClient(MqttClientOptions options)

Parameters

options MqttClientOptions

The broker connection settings.

Exceptions

ArgumentNullException

options is null.

PamojaException

The native client could not be created.

Methods

ConnectAsync()

Connects to the broker and starts the background event loop.

public Task ConnectAsync()

Returns

Task

A task that completes once connected.

Exceptions

PamojaException

The connection could not be established.

DisconnectAsync()

Closes the connection and stops the background event loop.

public Task DisconnectAsync()

Returns

Task

A task that completes once the client has disconnected.

Exceptions

PamojaException

The disconnect failed.

Dispose()

Releases the native client.

public void Dispose()

DisposeAsync()

Disconnects (best-effort) and releases the native client.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that completes once the client has been released.

GetAsyncEnumerator(CancellationToken)

Iterates incoming messages, so the client can be used with await foreach.

public IAsyncEnumerator<MqttMessage> GetAsyncEnumerator(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Stops iteration when cancelled.

Returns

IAsyncEnumerator<MqttMessage>

An async enumerator over incoming messages.

IsConnectedAsync()

Reports whether the client currently holds an active connection.

public Task<bool> IsConnectedAsync()

Returns

Task<bool>

A task resolving to the connection state.

Messages(CancellationToken)

Yields messages from subscribed topics until the connection ends.

public IAsyncEnumerable<MqttMessage> Messages(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Stops iteration when cancelled.

Returns

IAsyncEnumerable<MqttMessage>

An async stream over incoming messages.

PublishAsync(string, ReadOnlyMemory<byte>)

Publishes a payload to a topic.

public Task PublishAsync(string topic, ReadOnlyMemory<byte> payload)

Parameters

topic string

The destination topic.

payload ReadOnlyMemory<byte>

The message body.

Returns

Task

A task that completes once the payload is handed to the transport.

Exceptions

PamojaException

The payload could not be sent.

PublishAsync(string, string)

Publishes a UTF-8 string payload to a topic.

public Task PublishAsync(string topic, string payload)

Parameters

topic string

The destination topic.

payload string

The message body, encoded as UTF-8.

Returns

Task

A task that completes once the payload is handed to the transport.

Exceptions

PamojaException

The payload could not be sent.

RecvAsync()

Awaits the next message from any subscribed topic.

public Task<MqttMessage?> RecvAsync()

Returns

Task<MqttMessage>

The next message, or null once the connection has ended.

Exceptions

PamojaException

The client is not connected.

SubscribeAsync(string)

Subscribes to a topic filter.

public Task SubscribeAsync(string topic)

Parameters

topic string

The topic or wildcard filter to subscribe to.

Returns

Task

A task that completes once the subscription is registered.

Exceptions

PamojaException

The subscription was rejected.