AWS IoT Device SDK C++ v2  1.34.0
AWS IoT Device SDK C++ v2
Public Member Functions | Static Public Member Functions | Public Attributes | Friends | List of all members
Aws::Crt::Mqtt::MqttConnection Class Referencefinal

#include <MqttConnection.h>

Inheritance diagram for Aws::Crt::Mqtt::MqttConnection:

Public Member Functions

 ~MqttConnection ()
 
 MqttConnection (const MqttConnection &)=delete
 
 MqttConnection (MqttConnection &&)=delete
 
MqttConnectionoperator= (const MqttConnection &)=delete
 
MqttConnectionoperator= (MqttConnection &&)=delete
 
 operator bool () const noexcept
 
int LastError () const noexcept
 
bool SetWill (const char *topic, QOS qos, bool retain, const ByteBuf &payload) noexcept
 
bool SetLogin (const char *username, const char *password) noexcept
 
bool SetWebsocketProxyOptions (const Http::HttpClientConnectionProxyOptions &proxyOptions) noexcept
 
bool SetHttpProxyOptions (const Http::HttpClientConnectionProxyOptions &proxyOptions) noexcept
 
bool SetReconnectTimeout (uint64_t min_seconds, uint64_t max_seconds) noexcept
 
bool Connect (const char *clientId, bool cleanSession, uint16_t keepAliveTimeSecs=0, uint32_t pingTimeoutMs=0, uint32_t protocolOperationTimeoutMs=0) noexcept
 
bool Disconnect () noexcept
 
uint16_t Subscribe (const char *topicFilter, QOS qos, OnMessageReceivedHandler &&onMessage, OnSubAckHandler &&onSubAck) noexcept
 
uint16_t Subscribe (const char *topicFilter, QOS qos, OnPublishReceivedHandler &&onPublish, OnSubAckHandler &&onSubAck) noexcept
 
uint16_t Subscribe (const Vector< std::pair< const char *, OnMessageReceivedHandler >> &topicFilters, QOS qos, OnMultiSubAckHandler &&onOpComplete) noexcept
 
uint16_t Subscribe (const Vector< std::pair< const char *, OnPublishReceivedHandler >> &topicFilters, QOS qos, OnMultiSubAckHandler &&onOpComplete) noexcept
 
bool SetOnMessageHandler (OnMessageReceivedHandler &&onMessage) noexcept
 
bool SetOnMessageHandler (OnPublishReceivedHandler &&onPublish) noexcept
 
uint16_t Unsubscribe (const char *topicFilter, OnOperationCompleteHandler &&onOpComplete) noexcept
 
uint16_t Publish (const char *topic, QOS qos, bool retain, const ByteBuf &payload, OnOperationCompleteHandler &&onOpComplete) noexcept
 
const MqttConnectionOperationStatisticsGetOperationStatistics () noexcept
 

Static Public Member Functions

static std::shared_ptr< Crt::Mqtt::MqttConnectionNewConnectionFromMqtt5Client (std::shared_ptr< Mqtt5::Mqtt5Client > mqtt5client) noexcept
 

Public Attributes

OnConnectionInterruptedHandler OnConnectionInterrupted
 
OnConnectionResumedHandler OnConnectionResumed
 
OnConnectionCompletedHandler OnConnectionCompleted
 
OnDisconnectHandler OnDisconnect
 
OnWebSocketHandshakeIntercept WebsocketInterceptor
 
OnConnectionClosedHandler OnConnectionClosed
 
OnConnectionSuccessHandler OnConnectionSuccess
 
OnConnectionFailureHandler OnConnectionFailure
 

Friends

class MqttClient
 
class Mqtt5::Mqtt5ClientCore
 

Detailed Description

Represents a persistent Mqtt Connection. The memory is owned by MqttClient or Mqtt5Client.

To get a new instance of this class, use MqttClient::NewConnection or Mqtt5Client::NewConnection. Unless specified all function arguments need only to live through the duration of the function call.

See also
MqttClient::NewConnection
Mqtt5Client::NewConnection

Constructor & Destructor Documentation

◆ ~MqttConnection()

Aws::Crt::Mqtt::MqttConnection::~MqttConnection ( )

◆ MqttConnection() [1/2]

Aws::Crt::Mqtt::MqttConnection::MqttConnection ( const MqttConnection )
delete

◆ MqttConnection() [2/2]

Aws::Crt::Mqtt::MqttConnection::MqttConnection ( MqttConnection &&  )
delete

Member Function Documentation

◆ Connect()

bool Aws::Crt::Mqtt::MqttConnection::Connect ( const char *  clientId,
bool  cleanSession,
uint16_t  keepAliveTimeSecs = 0,
uint32_t  pingTimeoutMs = 0,
uint32_t  protocolOperationTimeoutMs = 0 
)
noexcept

Initiates the connection, OnConnectionCompleted will be invoked in an event-loop thread.

Parameters
clientIdclient identifier to use when establishing the mqtt connection
cleanSessionfalse to attempt to rejoin an existing session for the client id, true to skip and start with a new session
keepAliveTimeSecstime interval to space mqtt pings apart by
pingTimeoutMstimeout in milliseconds before the keep alive ping is considered to have failed
protocolOperationTimeoutMstimeout in milliseconds to give up waiting for a response packet for an operation. Necessary due to throttling properties on certain server implementations that do not return an ACK for throttled operations.
Returns
true if the connection attempt was successfully started (implying a callback will be invoked with the eventual result), false if it could not be started (no callback will happen)

◆ Disconnect()

bool Aws::Crt::Mqtt::MqttConnection::Disconnect ( )
noexcept

Initiates disconnect, OnDisconnectHandler will be invoked in an event-loop thread.

Returns
success/failure in initiating disconnect

◆ GetOperationStatistics()

const MqttConnectionOperationStatistics & Aws::Crt::Mqtt::MqttConnection::GetOperationStatistics ( )
noexcept

Get the statistics about the current state of the connection's queue of operations

Returns
MqttConnectionOperationStatistics

◆ LastError()

int Aws::Crt::Mqtt::MqttConnection::LastError ( ) const
noexcept
Returns
the value of the last aws error encountered by operations on this instance.

◆ NewConnectionFromMqtt5Client()

std::shared_ptr< MqttConnection > Aws::Crt::Mqtt::MqttConnection::NewConnectionFromMqtt5Client ( std::shared_ptr< Mqtt5::Mqtt5Client mqtt5client)
staticnoexcept

Create a new MqttConnection object from the Mqtt5Client.

Parameters
mqtt5clientThe shared ptr of Mqtt5Client
Returns
std::shared_ptr<Crt::Mqtt::MqttConnection>

As we passed the std::shared_ptr<Mqtt5Client> by value, this function scope would keep a reference of the Mqtt5Client thus the underlying c client. Therefore we directly access the c client here. Other than that, we should never directly access the underlying c client without acquire the reference.

◆ operator bool()

Aws::Crt::Mqtt::MqttConnection::operator bool ( ) const
noexcept
Returns
true if the instance is in a valid state, false otherwise.

◆ operator=() [1/2]

MqttConnection& Aws::Crt::Mqtt::MqttConnection::operator= ( const MqttConnection )
delete

◆ operator=() [2/2]

MqttConnection& Aws::Crt::Mqtt::MqttConnection::operator= ( MqttConnection &&  )
delete

◆ Publish()

uint16_t Aws::Crt::Mqtt::MqttConnection::Publish ( const char *  topic,
QOS  qos,
bool  retain,
const ByteBuf payload,
OnOperationCompleteHandler &&  onOpComplete 
)
noexcept

Publishes to a topic.

Parameters
topictopic to publish to
qosQOS to publish the message with
retainshould this message replace the current retained message of the topic?
payloadpayload of the message
onOpCompletecompletion callback to invoke when the operation is complete. If QoS is 0, then the callback is invoked when the message is passed to the tls handler, otherwise it's invoked on receipt of the final response from the server.
Returns
packet id of the publish request, or 0 if the attempt failed synchronously

◆ SetHttpProxyOptions()

bool Aws::Crt::Mqtt::MqttConnection::SetHttpProxyOptions ( const Http::HttpClientConnectionProxyOptions proxyOptions)
noexcept

Sets http proxy options. In order to use an http proxy with mqtt either (1) Websockets are used (2) Mqtt-over-tls is used and the ALPN list of the tls context contains a tag that resolves to mqtt

Parameters
proxyOptionsproxy configuration for making the mqtt connection
Returns
success/failure

◆ SetLogin()

bool Aws::Crt::Mqtt::MqttConnection::SetLogin ( const char *  username,
const char *  password 
)
noexcept

Sets login credentials for the connection. The must get set before the Connect call if it is to be used.

Parameters
usernameuser name to add to the MQTT CONNECT packet
passwordpassword to add to the MQTT CONNECT packet
Returns
success/failure

◆ SetOnMessageHandler() [1/2]

bool Aws::Crt::Mqtt::MqttConnection::SetOnMessageHandler ( OnMessageReceivedHandler &&  onMessage)
noexcept

Installs a handler for all incoming publish messages, regardless of if Subscribe has been called on the topic.

Parameters
onMessagecallback to invoke for all received messages
Returns
success/failure

◆ SetOnMessageHandler() [2/2]

bool Aws::Crt::Mqtt::MqttConnection::SetOnMessageHandler ( OnPublishReceivedHandler &&  onPublish)
noexcept

◆ SetReconnectTimeout()

bool Aws::Crt::Mqtt::MqttConnection::SetReconnectTimeout ( uint64_t  min_seconds,
uint64_t  max_seconds 
)
noexcept

Customize time to wait between reconnect attempts. The time will start at min and multiply by 2 until max is reached. The time resets back to min after a successful connection. This function should only be called before Connect().

Parameters
min_secondsminimum time to wait before attempting a reconnect
max_secondsmaximum time to wait before attempting a reconnect
Returns
success/failure

◆ SetWebsocketProxyOptions()

bool Aws::Crt::Mqtt::MqttConnection::SetWebsocketProxyOptions ( const Http::HttpClientConnectionProxyOptions proxyOptions)
noexcept
Deprecated:
Sets websocket proxy options. Replaced by SetHttpProxyOptions.

◆ SetWill()

bool Aws::Crt::Mqtt::MqttConnection::SetWill ( const char *  topic,
QOS  qos,
bool  retain,
const ByteBuf payload 
)
noexcept

Sets LastWill for the connection.

Parameters
topictopic the will message should be published to
qosQOS the will message should be published with
retaintrue if the will publish should be treated as a retained publish
payloadpayload of the will message
Returns
success/failure in setting the will

◆ Subscribe() [1/4]

uint16_t Aws::Crt::Mqtt::MqttConnection::Subscribe ( const char *  topicFilter,
QOS  qos,
OnMessageReceivedHandler &&  onMessage,
OnSubAckHandler &&  onSubAck 
)
noexcept

Subscribes to topicFilter. OnMessageReceivedHandler will be invoked from an event-loop thread upon an incoming Publish message. OnSubAckHandler will be invoked upon receipt of a suback message.

Parameters
topicFiltertopic filter to subscribe to
qosmaximum qos client is willing to receive matching messages on
onMessagecallback to invoke when a message is received based on matching this filter
onSubAckcallback to invoke with the server's response to the subscribe request
Returns
packet id of the subscribe request, or 0 if the attempt failed synchronously

◆ Subscribe() [2/4]

uint16_t Aws::Crt::Mqtt::MqttConnection::Subscribe ( const char *  topicFilter,
QOS  qos,
OnPublishReceivedHandler &&  onPublish,
OnSubAckHandler &&  onSubAck 
)
noexcept
Deprecated:
Use alternate Subscribe()

◆ Subscribe() [3/4]

uint16_t Aws::Crt::Mqtt::MqttConnection::Subscribe ( const Vector< std::pair< const char *, OnMessageReceivedHandler >> &  topicFilters,
QOS  qos,
OnMultiSubAckHandler &&  onOpComplete 
)
noexcept

Subscribes to multiple topicFilters. OnMessageReceivedHandler will be invoked from an event-loop thread upon an incoming Publish message. OnMultiSubAckHandler will be invoked upon receipt of a suback message.

Parameters
topicFilterslist of pairs of topic filters and message callbacks to invoke on a matching publish
qosmaximum qos client is willing to receive matching messages on
onOpCompletecallback to invoke with the server's response to the subscribe request
Returns
packet id of the subscribe request, or 0 if the attempt failed synchronously

◆ Subscribe() [4/4]

uint16_t Aws::Crt::Mqtt::MqttConnection::Subscribe ( const Vector< std::pair< const char *, OnPublishReceivedHandler >> &  topicFilters,
QOS  qos,
OnMultiSubAckHandler &&  onOpComplete 
)
noexcept
Deprecated:
Use alternate Subscribe()

◆ Unsubscribe()

uint16_t Aws::Crt::Mqtt::MqttConnection::Unsubscribe ( const char *  topicFilter,
OnOperationCompleteHandler &&  onOpComplete 
)
noexcept

Unsubscribes from topicFilter. OnOperationCompleteHandler will be invoked upon receipt of an unsuback message.

Parameters
topicFiltertopic filter to unsubscribe the session from
onOpCompletecallback to invoke on receipt of the server's UNSUBACK message
Returns
packet id of the unsubscribe request, or 0 if the attempt failed synchronously

Friends And Related Function Documentation

◆ Mqtt5::Mqtt5ClientCore

friend class Mqtt5::Mqtt5ClientCore
friend

◆ MqttClient

friend class MqttClient
friend

Member Data Documentation

◆ OnConnectionClosed

OnConnectionClosedHandler Aws::Crt::Mqtt::MqttConnection::OnConnectionClosed

Invoked when a connection is disconnected and shutdown successfully.

Note
Currently callbackData will always be nullptr, but this may change in the future to send additional data.
From the user perspective, this callback is indistinguishable from OnDisconnect.

◆ OnConnectionCompleted

OnConnectionCompletedHandler Aws::Crt::Mqtt::MqttConnection::OnConnectionCompleted

Invoked when a connack message is received, or an error occurred.

◆ OnConnectionFailure

OnConnectionFailureHandler Aws::Crt::Mqtt::MqttConnection::OnConnectionFailure

Invoked whenever the connection fails to connect.

This callback is invoked for every failed connect and every failed reconnect.

◆ OnConnectionInterrupted

OnConnectionInterruptedHandler Aws::Crt::Mqtt::MqttConnection::OnConnectionInterrupted

A callback invoked every time the connections is interrupted.

◆ OnConnectionResumed

OnConnectionResumedHandler Aws::Crt::Mqtt::MqttConnection::OnConnectionResumed

A callback invoked every time the connection is resumed.

◆ OnConnectionSuccess

OnConnectionSuccessHandler Aws::Crt::Mqtt::MqttConnection::OnConnectionSuccess

Invoked whenever the connection successfully connects.

This callback is invoked for every successful connect and every successful reconnect.

◆ OnDisconnect

OnDisconnectHandler Aws::Crt::Mqtt::MqttConnection::OnDisconnect

A callback invoked on disconnect.

◆ WebsocketInterceptor

OnWebSocketHandshakeIntercept Aws::Crt::Mqtt::MqttConnection::WebsocketInterceptor

Invoked during websocket handshake to give users opportunity to transform an http request for purposes such as signing/authorization etc... Returning from this function does not continue the websocket handshake since some work flows may be asynchronous. To accommodate that, onComplete must be invoked upon completion of the signing process.


The documentation for this class was generated from the following files: