Module mqtt
API
ballerina/mqtt Ballerina library
Clients
mqtt: Caller
Represents the client that is used to complete received messages.
complete
function complete() returns Error?Completes the received message.
check caller->complete();
Return Type
- Error? -
mqtt:Errorif the message cannot be completed or else()
respond
Send the response for the request message.
check caller->respond({payload: "Hello Response".toBytes()});
Parameters
- response Message - The response message to be sent
Return Type
- Error? -
mqtt:Errorif the message cannot be sent or()
mqtt: Client
Represents the client that is used to publish messages to the server.
Constructor
Creates a new mqtt:Client.
mqtt:Client 'client = check new(mqtt:DEFAULT_URL, "client-unique-id");
init (string serverUri, string clientId, *ClientConfiguration config)- serverUri string - URI of the server to connect to
- clientId string - Unique ID of the client
- config *ClientConfiguration - Optional configuration values to use for the client
publish
function publish(string topic, Message message) returns DeliveryToken|ErrorPublishes a message to a topic.
mqtt:DeliveryToken token = check 'client->publish("mqtt/topic", message);
Return Type
- DeliveryToken|Error -
mqtt:DeliveryTokenor elsemqtt:Errorif an error occurs while publishing
subscribe
function subscribe(string|string[]|Subscription|Subscription[] subscriptions) returns Error?Subscribes to a given topic in the request response scenario.
check 'client->subscribe([{topic: "mqtt/topic1", qos: 0}, {topic: "mqtt/topic2", qos: 1}]);
Parameters
- subscriptions string|string[]|Subscription|Subscription[] - The topics to be subscribed to
Return Type
- Error? -
mqtt:Errorif an error occurs while subscribing or else()
receive
Receives messages from the server.
stream<mqtt:Message, error?> responseStream = check 'client->receive();
Return Type
- T|Error -
stream<Message, error?>or elsemqtt:Errorif an error occurs while receiving the response
close
function close() returns Error?Closes the connection to the server.
check 'client->close();
Return Type
- Error? -
mqtt:Errorif an error occurs while closing or else()
isConnected
Checks if the client is connected to the server.
boolean isConnected = check 'client->isConnected;
Return Type
disconnect
function disconnect() returns Error?Disconnects the client from the server.
check 'client->disconnect();
Return Type
- Error? -
mqtt:Errorif an error occurs while disconnecting or else()
reconnect
function reconnect() returns Error?Reconnects the client to the server.
check 'client->reconnect();
Return Type
- Error? -
mqtt:Errorif an error occurs while reconnecting or else()
Service types
mqtt: Service
The MQTT service type.
Constants
mqtt: DEFAULT_URL
Default url of the MQTT server.
Enums
mqtt: Protocol
Represents protocol options.
Members
Listeners
mqtt: Listener
Represents a MQTT listener endpoint.
Constructor
Creates a new mqtt:Listener.
mqtt:Listener 'listener = check new(mqtt:DEFAULT_URL, "listener-unique-id", "mqtt/topic");
init (string serverUri, string clientId, string|string[]|Subscription|Subscription[] subscriptions, *ListenerConfiguration config)- serverUri string - The URI of the remote MQTT server
- clientId string - The unique client ID to identify the listener
- subscriptions string|string[]|Subscription|Subscription[] - The topics to be subscribed to
- config *ListenerConfiguration -
attach
Attaches a service to the listener.
mqtt:Error? result = 'listener.attach(mqttService);
Parameters
- 'service Service - The service to be attached
Return Type
- Error? - A
errorif an error is encountered while attaching the service or else()
'start
function 'start() returns Error?Starts the registered services.
mqtt:Error? result = 'listener.'start();
Return Type
- Error? - A
errorif an error is encountered while starting the server or else()
gracefulStop
function gracefulStop() returns Error?Stops the MQTT listener gracefully.
mqtt:Error? result = 'listener.gracefulStop();
Return Type
- Error? - A
errorif an error is encountered during the listener-stopping process or else()
immediateStop
function immediateStop() returns Error?Stops the mqtt listener immediately.
mqtt:Error? result = 'listener.immediateStop();
Return Type
- Error? - A
errorif an error is encountered during the listener-stopping process or else()
detach
Detaches a consumer service from the listener.
mqtt:Error? result = 'listener.detach(mqttService);
Parameters
- 'service Service - The service to be detached
Return Type
- Error? - A
errorif an error is encountered while detaching a service or else()
Records
mqtt: CertKey
Represents a combination of certificate, private key, and private key password if encrypted.
Fields
- certFile string - A file containing the certificate
- keyFile string - A file containing the private key
- keyPassword? string - Password of the private key if it is encrypted
mqtt: ClientConfiguration
The configurations related to the client initialization.
Fields
- connectionConfig? ConnectionConfiguration - The related connection configuration
- willDetails? WillDetails - The configurations related to the last will message of the client
mqtt: ConnectionConfiguration
The configurations related to the connection initialization of mqtt:Client and mqtt:Listener.
Fields
- username? string - The username to use for the connection
- password? string - The password to use for the connection
- secureSocket? SecureSocket - The configurations related to secure communication with the MQTT server
- maxReconnectDelay? int - The maximum delay between reconnects in milliseconds
- keepAliveInterval? int - The maximum time interval between messages sent or received in seconds
- connectionTimeout? int - Maximum time interval in seconds the client will wait for the network connection to the MQTT server to be established
- cleanStart? boolean - Whether the client and server should remember state for the client across reconnects
- serverUris? string[] - List of serverURIs the client may connect to
- automaticReconnect? boolean - Whether the client will automatically attempt to reconnect to the server if the connection is lost
mqtt: DeliveryToken
The mechanism for tracking the delivery of a message
Fields
- messageId int - Message ID of the message that was delivered
- topic string - Topic for the message that was delivered
mqtt: ErrorDetails
The error details type for the module.
Fields
- reasonCode? int - The reason code for the error
mqtt: ListenerConfiguration
The configurations related to the listener initialization.
Fields
- connectionConfig? ConnectionConfiguration - The related connection configuration
- manualAcks boolean(default false) - Indicates whether or not the client should automatically ack messages
mqtt: Message
An MQTT message holds the application payload and other metadata.
Fields
- payload byte[] - The payload of the message as a byte array
- qos int(default 1) - Quality of service. 0 - at most once, 1 - at least once, 2 - exactly once
- retained boolean(default false) - Indicates whether this message should/is retained by the server
- duplicate boolean(default false) - Indicates whether or not this message might be a duplicate
- messageId? int - The message ID of the message. This is only set on messages received from the server
- topic? string - The topic this message was received on. This is only set on messages received from the server
- properties? MessageProperties - The properties of the message
mqtt: MessageProperties
Properties of an MQTT message.
Fields
- responseTopic? string - The topic to send the response to in reqeust response scenario
- correlationData? byte[] - The correlation data to uniquely identify the message
mqtt: SecureSocket
Configurations for secure communication with the MQTT server.
Fields
- cert? TrustStore|string - Certificate file that the client trusts or a
crypto:TrustStore
- key? KeyStore|CertKey - Combination of certificate and private key of the client or a
crypto:KeyStore
mqtt: Subscription
An MQTTSubscription which contains the topic and the QoS level.
Fields
- topic string - The topic to subscribe to
- qos int(default 1) - The QoS level to subscribe at
mqtt: WillDetails
The configurations related to the last will message of the client.
Fields
- willMessage Message - The last will message to be sent to the subscribers
- destinationTopic string - The topic to publish the last will message
Errors
mqtt: Error
The common error type for the module.
Import
import ballerina/mqtt;Metadata
Released date: 11 months ago
Version: 1.3.0
Compatibility
Platform: java21
Ballerina version: 2201.11.0-20241209-162400-0c015833
GraalVM compatible: Yes
Pull count
Total: 1
Current verison: 0
Weekly downloads
Keywords
mqtt
client
messaging
network
pubsub
iot
Contributors
Dependencies