Skip to content

Commit

Permalink
Mqtt5 GA API Review (#575)
Browse files Browse the repository at this point in the history
  • Loading branch information
@xiazhvera
xiazhvera authored Dec 4, 2023
1 parent 6f2cede commit 0c64f25
Show file tree
Hide file tree
Showing 9 changed files with 372 additions and 47 deletions.
4 changes: 2 additions & 2 deletions bin/mqtt5_canary/main.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -426,14 +426,14 @@ static int s_AwsMqtt5CanaryOperationSubscribe(struct AwsMqtt5CanaryTestClient *t
.WithNoLocal(false)
.WithQOS(Mqtt5::QOS::AWS_MQTT5_QOS_AT_LEAST_ONCE)
.WithRetainHandlingType(Mqtt5::RetainHandlingType::AWS_MQTT5_RHT_SEND_ON_SUBSCRIBE)
.WithRetain(false);
.WithRetainAsPublished(false);

Mqtt5::Subscription subscription2;
subscription2.WithTopicFilter(testClient->sharedTopic)
.WithNoLocal(false)
.WithQOS(Mqtt5::QOS::AWS_MQTT5_QOS_AT_LEAST_ONCE)
.WithRetainHandlingType(Mqtt5::RetainHandlingType::AWS_MQTT5_RHT_SEND_ON_SUBSCRIBE)
.WithRetain(false);
.WithRetainAsPublished(false);

std::shared_ptr<Mqtt5::SubscribePacket> packet = std::make_shared<Mqtt5::SubscribePacket>(allocator);
packet->WithSubscription(std::move(subscription1));
Expand Down
38 changes: 25 additions & 13 deletions include/aws/crt/mqtt/Mqtt5Client.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ namespace Aws
* Controls how the reconnect delay is modified in order to smooth out the distribution of reconnection
* attempt timepoints for a large set of reconnecting clients.
*/
JitterMode m_reconnectMode;
ExponentialBackoffJitterMode m_reconnectMode;

/**
* Minimum amount of time to wait to reconnect after a disconnect. Exponential backoff is performed
Expand Down Expand Up @@ -383,47 +383,47 @@ namespace Aws
* Notifies the MQTT5 client that you want it to transition to the stopped state, disconnecting any
* existing connection and stopping subsequent reconnect attempts.
*
* @param disconnectOptions (optional) properties of a DISCONNECT packet to send as part of the shutdown
* @param disconnectPacket (optional) properties of a DISCONNECT packet to send as part of the shutdown
* process
*
* @return bool: true if operation succeed, otherwise false
*/
bool Stop(std::shared_ptr<DisconnectPacket> disconnectOptions) noexcept;
bool Stop(std::shared_ptr<DisconnectPacket> disconnectPacket) noexcept;

/**
* Tells the client to attempt to send a PUBLISH packet
*
* @param publishOptions: packet PUBLISH to send to the server
* @param publishPacket: packet PUBLISH to send to the server
* @param onPublishCompletionCallback: callback on publish complete, default to NULL
*
* @return true if the publish operation succeed otherwise false
*/
bool Publish(
std::shared_ptr<PublishPacket> publishOptions,
std::shared_ptr<PublishPacket> publishPacket,
OnPublishCompletionHandler onPublishCompletionCallback = NULL) noexcept;

/**
* Tells the client to attempt to subscribe to one or more topic filters.
*
* @param subscribeOptions: SUBSCRIBE packet to send to the server
* @param subscribePacket: SUBSCRIBE packet to send to the server
* @param onSubscribeCompletionCallback: callback on subscribe complete, default to NULL
*
* @return true if the subscription operation succeed otherwise false
*/
bool Subscribe(
std::shared_ptr<SubscribePacket> subscribeOptions,
std::shared_ptr<SubscribePacket> subscribePacket,
OnSubscribeCompletionHandler onSubscribeCompletionCallback = NULL) noexcept;

/**
* Tells the client to attempt to unsubscribe to one or more topic filters.
*
* @param unsubscribeOptions: UNSUBSCRIBE packet to send to the server
* @param unsubscribePacket: UNSUBSCRIBE packet to send to the server
* @param onUnsubscribeCompletionCallback: callback on unsubscribe complete, default to NULL
*
* @return true if the unsubscription operation succeed otherwise false
*/
bool Unsubscribe(
std::shared_ptr<UnsubscribePacket> unsubscribeOptions,
std::shared_ptr<UnsubscribePacket> unsubscribePacket,
OnUnsubscribeCompletionHandler onUnsubscribeCompletionCallback = NULL) noexcept;

/**
Expand Down Expand Up @@ -517,11 +517,11 @@ namespace Aws
/**
* Sets mqtt5 connection options
*
* @param packetConnect package connection options
* @param connectPacket package connection options
*
* @return this option object
*/
Mqtt5ClientOptions &WithConnectOptions(std::shared_ptr<ConnectPacket> packetConnect) noexcept;
Mqtt5ClientOptions &WithConnectOptions(std::shared_ptr<ConnectPacket> connectPacket) noexcept;

/**
* Sets session behavior. Overrides how the MQTT5 client should behave with respect to MQTT sessions.
Expand Down Expand Up @@ -595,15 +595,27 @@ namespace Aws
*/
Mqtt5ClientOptions &WithConnackTimeoutMs(uint32_t connackTimeoutMs) noexcept;

/**
* @deprecated The function is deprecated, please use `Mqtt5ClientOptions::WithAckTimeoutSec(uint32_t)`
*
* Sets Operation Timeout(Seconds). Time interval to wait for an ack after sending a QoS 1+ PUBLISH,
* SUBSCRIBE, or UNSUBSCRIBE before failing the operation.
*
* @param ackTimeoutSec
*
* @return this option object
*/
Mqtt5ClientOptions &WithAckTimeoutSeconds(uint32_t ackTimeoutSec) noexcept;

/**
* Sets Operation Timeout(Seconds). Time interval to wait for an ack after sending a QoS 1+ PUBLISH,
* SUBSCRIBE, or UNSUBSCRIBE before failing the operation.
*
* @param ackTimeoutSeconds
* @param ackTimeoutSec
*
* @return this option object
*/
Mqtt5ClientOptions &WithAckTimeoutSeconds(uint32_t ackTimeoutSeconds) noexcept;
Mqtt5ClientOptions &WithAckTimeoutSec(uint32_t ackTimeoutSec) noexcept;

/**
* Sets callback for transform HTTP request.
Expand Down
78 changes: 75 additions & 3 deletions include/aws/crt/mqtt/Mqtt5Packets.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -500,10 +500,18 @@ namespace Aws
uint16_t getReceiveMaximumFromServer() const noexcept;

/**
* @deprecated the function is deprecated, please use
* `NegotiatedSettings::getMaximumPacketSizeToServer()`
*
* @return The maximum packet size the server is willing to accept.
*/
uint32_t getMaximumPacketSizeBytes() const noexcept;

/**
* @return The maximum packet size the server is willing to accept.
*/
uint32_t getMaximumPacketSizeToServer() const noexcept;

/**
* @return returns the maximum allowed topic alias value on publishes sent from client to server
*/
Expand All @@ -521,6 +529,17 @@ namespace Aws
*
* @return The maximum amount of time in seconds between client packets.
*/
uint16_t getServerKeepAliveSec() const noexcept;

/**
* @deprecated The function is deprecated, please use `NegotiatedSettings::getServerKeepAliveSec()`
*
* The maximum amount of time in seconds between client packets. The client should use PINGREQs to
* ensure this limit is not breached. The server will disconnect the client for inactivity if no MQTT
* packet is received in a time interval equal to 1.5 x this value.
*
* @return The maximum amount of time in seconds between client packets.
*/
uint16_t getServerKeepAlive() const noexcept;

/**
Expand Down Expand Up @@ -939,6 +958,8 @@ namespace Aws
const Crt::Optional<uint16_t> &getReceiveMaximum() const noexcept;

/**
* @deprecated The function is deprecated, please use `ConnectPacket::getMaximumPacketSizeToServer()`
*
* Notifies the server of the maximum packet size the client is willing to handle. If
* omitted or null, then no limit beyond the natural limits of MQTT packet size is requested.
*
Expand All @@ -949,6 +970,17 @@ namespace Aws
*/
const Crt::Optional<uint32_t> &getMaximumPacketSizeBytes() const noexcept;

/**
* Notifies the server of the maximum packet size the client is willing to handle. If
* omitted or null, then no limit beyond the natural limits of MQTT packet size is requested.
*
* See [MQTT5 Maximum Packet
* Size](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901050)
*
* @return The maximum packet size the client is willing to handle
*/
const Crt::Optional<uint32_t> &getMaximumPacketSizeToServer() const noexcept;

/**
* A time interval, in seconds, that the server should wait (for a session reconnection) before sending
* the will message associated with the connection's session. If omitted or null, the server will send
Expand Down Expand Up @@ -1175,6 +1207,20 @@ namespace Aws
* @return A time interval, in seconds, that the server will persist this connection's MQTT session
* state for.
*/
const Crt::Optional<uint32_t> &getSessionExpiryIntervalSec() const noexcept;

/**
* @deprecated The function is deprecated, please use `ConnAckPacket::getSessionExpiryIntervalSec()`.
*
* A time interval, in seconds, that the server will persist this connection's MQTT session state
* for. If present, this value overrides any session expiry specified in the preceding CONNECT packet.
*
* See [MQTT5 Session Expiry
* Interval](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901082)
*
* @return A time interval, in seconds, that the server will persist this connection's MQTT session
* state for.
*/
const Crt::Optional<uint32_t> &getSessionExpiryInterval() const noexcept;

/**
Expand Down Expand Up @@ -1304,6 +1350,18 @@ namespace Aws
*
* @return Server-requested override of the keep alive interval, in seconds
*/
const Crt::Optional<uint16_t> &getServerKeepAliveSec() const noexcept;

/**
* @deprecated The function is deprecated, please use `ConnAckPacket::getServerKeepAliveSec()`.
* Server-requested override of the keep alive interval, in seconds. If null, the keep alive value sent
* by the client should be used.
*
* See [MQTT5 Server Keep
* Alive](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901094)
*
* @return Server-requested override of the keep alive interval, in seconds
*/
const Crt::Optional<uint16_t> &getServerKeepAlive() const noexcept;

/**
Expand Down Expand Up @@ -1360,7 +1418,7 @@ namespace Aws
* See [MQTT5 Session Expiry
* Interval](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901082)
*/
Crt::Optional<uint32_t> m_sessionExpiryInterval;
Crt::Optional<uint32_t> m_sessionExpiryIntervalSec;

/**
* The maximum amount of in-flight QoS 1 or 2 messages that the server is willing to handle at once. If
Expand Down Expand Up @@ -1455,7 +1513,7 @@ namespace Aws
* See [MQTT5 Server Keep
* Alive](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901094)
*/
Crt::Optional<uint16_t> m_serverKeepAlive;
Crt::Optional<uint16_t> m_serverKeepAliveSec;

/**
* A value that can be used in the creation of a response topic associated with this connection.
Expand Down Expand Up @@ -1880,6 +1938,20 @@ namespace Aws
* @param retain bool
* @return The Subscription Object after setting the reason string.
*/
Subscription &WithRetainAsPublished(bool retain) noexcept;

/**
* @deprecated The function is deprecated, please use `Subscription::WithRetainAsPublished(bool)`.
*
* Sets should the server not send publishes to a client when that client was the one who sent the
* publish? The value will be default to false.
*
* See [MQTT5 Subscription
* Options](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901169)
*
* @param retain bool
* @return The Subscription Object after setting the reason string.
*/
Subscription &WithRetain(bool retain) noexcept;

/**
Expand Down Expand Up @@ -1937,7 +2009,7 @@ namespace Aws
* See [MQTT5 Subscription
* Options](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901169)
*/
bool m_retain;
bool m_retainAsPublished;

/**
* Should retained messages on matching topics be sent in reaction to this subscription? If undefined,
Expand Down
Loading

0 comments on commit 0c64f25

Please sign in to comment.