From 43eacd1bc0db4f824690af7dd52e074123f6cdd7 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 1 Feb 2024 17:01:28 -0800 Subject: [PATCH 01/33] Add V1 to V1 migration guide --- documents/MIGRATION_GUIDE.md | 1081 ++++++++++++++++++++++++++++++++++ 1 file changed, 1081 insertions(+) create mode 100644 documents/MIGRATION_GUIDE.md diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md new file mode 100644 index 000000000..496c68b71 --- /dev/null +++ b/documents/MIGRATION_GUIDE.md @@ -0,0 +1,1081 @@ +# Migrate from V1 to V2 of the AWS IoT SDK for C++ + +The V2 AWS IoT SDK for C++ is a major rewrite of the V1 code base. It includes many updates, such as improved consistency, ease of use, more detailed information about client status, an offline operation queue control, etc. This guide describes the major features that are new in V2, and provides guidance on how to migrate your code to V2 from V1. + +## What’s new in V2 SDK + +* V2 SDK client is truly async. Operations take callback functions/lambdas, that is called when the operation is registered with the server + Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved after the function call by calling `future.wait()` +* V2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. +* Public API terminology has changed. You `S``tart()` or `S``top()` the MQTT5 client rather than `Connect` or `Disconnect` like in V1. This removes the semantic confusion with the connect/disconnect as the client-level controls vs. internal recurrent networking events. +* Support for Fleet Provisioning AWS IoT Core service. + +Public API for almost all actions and operations has changed significantly. For more details about the new features and to see specific code examples, refer to the other sections of this guide. + + +## How To Get Started with V2 SDK + +There are differences between IoT C++ V1 SDK and IoT C++ V2 SDK. Below are changes you need to make to use IoT C++ V2 SDK features. For more information about MQTT5, visit [MQTT5 User Guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md). + + +### MQTT Protocol + +V1 SDK uses an MQTT version 3.1.1 client under the hood. + +V2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementations. This guide focuses on the MQTT5 since this version is significant improvement over MQTT3. See MQTT5 features section. + + +### Client Builder + +To access the AWS IoT service, you must initialize an MQTT client. + +In V1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html) class represents an MQTT client. You instantiate the client directly passing all the required parameters to the class constructor. It’s possible to change client settings after its creation using `set*` methods, e.g. `SetAutoReconnectEnabled` or `SetMaxReconnectBackoffTimeout`. + +In V2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) class represents an MQTT client, specifically MQTT5 protocol. V2 SDK provides an [Aws::Iot::Mqtt5ClientBuilder](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html) designed to easily create common configuration types such as direct MQTT or WebSocket connections. +Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot have its settings modified. + +_Example of creating a client in V1_ + +``` +#include "OpenSSLConnection.hpp" + + util::String clientEndpoint = "-ats.iot..amazonaws.com"; +uint16_t clientPort = + util::String clientId = ""; + util::String rootCaPath = ""; + util::String certificateFile = ""; // X.509 based certificate file + util::String privateKeyFile = ""; // PEM encoded private key file + + std::shared_ptr p_network_connection = + std::make_shared( + clientEndpoint, + clientPort, + rootCaPath, + certificateFile, + privateKeyFile); +ResponseCode rc = p_network_connection->Initialize(); +``` + +_Example of creating a client in V2_ + +V2 SDK supports different connection types. Given the same input parameters as in the V1 example above, the most suitable method to create an MQTT5 client will [beNewMqtt5ClientBuilderWithMtlsFromPath](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#ab595bbc50e08b9d2f78f62e9efeafd65). + +``` +util::String clientEndpoint = "-ats.iot..amazonaws.com"; +util::String certificateFile = ""; // X.509 based certificate file +util::String privateKeyFile = ""; // PEM encoded private key file +uint32_t clientPort = + +std::shared_ptrbuilder( + Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath( + clientEndpoint, + certificateFie, + privateKeyFile)); +std::shared_ptr connectOptions = + std::make_shared(); +util::String clientId = ""; +connectOptions->WithClientId(clientId); +builder->WithConnectOptions(connectOptions); +builder->WithPort(clientPort); +std::shared_ptr client = builder->Build(); +``` + +Refer to the [Connection Types and Features](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR0b9b69e08b72487dbe620342f) section for other connection types supported by V2 SDK. + +### Connection Types and Features + +V1 SDK supports two types of connections to connect to the AWS IoT service: MQTT with X.509 certificate and MQTT over Secure WebSocket with SigV4 authentication. + +V2 SDK adds a collection of connection types and cryptography formats (e.g. [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) and [Custom Authorizer](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html)), credential providers (e.g. [Amazon Cognito](https://aws.amazon.com/cognito/) and [Windows Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores)), and other connection-related features. +Refer to the “[Connecting To AWS IoT Core](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#connecting-to-aws-iot-core)” section of the MQTT5 user guide for detailed information and code snippets on each connection type and connection feature. + +|Connection Type/Feature |V1 SDK |V2 SDK |User guide section | | +|--- |--- |--- |--- |--- | +| | | | | | +|MQTT over Secure WebSocket with AWS SigV4 authentication |✔ |✔ | | | +|MQTT (over TLS 1.2) with X.509 certificate based mutual authentication |✘ |✔ | |X.509 | +|MQTT with PKCS12 Method |✔* |✔ | |Container for X.509 | +|MQTT with Custom Key Operation Method |✔* |✔ | |X.509 | +|MQTT with Custom Authorizer Method |✔* |✔ | | | +|MQTT with Windows Certificate Store Method |✔* |✔ | |X.509 | +|MQTT with PKCS11 Method |✘ |✔ | |X.509 plus other formats | +|Websocket Connection with Cognito Authentication Method |✘ |✔ | | | +|HTTP Proxy |✔** |✔ | | | + +✔* - In order to get this connection type work in V1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html). +✔** - Though V1 does not allow to specify HTTP proxy, it is possible to configure systemwide proxy. + +### Lifecycle Events + +Both V1 and V2 SDKs provide lifecycle events for the MQTT clients. + +V1 SDK provides 3 lifecycle events: “ClientCoreState::ApplicationResubscribeCallbackPt”, “ClientCoreState::ApplicationDisconnectCallbackPtr”, and “ClientCoreState::ApplicationReconnectCallbackPtr”. You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. + +V2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: “WithClientConnectionSuccessCallback”, “WithClientConnectionFailureCallback”, “WithClientDisconnectionCallback”, “WithClientStoppedCallback”, and “WithClientAttemptingConnectCallback”. +Refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management) for the details. + +_Example of setting lifecycle events in V1_ + +``` +std::shared_ptr p_iot_client_; +ResponseCode DisconnectCallback( + util::String client_id, + std::shared_ptr p_app_handler_data) { + ... + return ResponseCode::SUCCESS; +} +ResponseCode JobsSample::ReconnectCallback( + util::String client_id, + std::shared_ptr p_app_handler_data, + ResponseCode reconnect_result) { + ... + return ResponseCode::SUCCESS; +} +ResponseCode ResubscribeCallback(util::String client_id, + std::shared_ptr p_app_handler_data, + ResponseCode resubscribe_result) { + ... + return ResponseCode::SUCCESS; + } +ClientCoreState::ApplicationDisconnectCallbackPtr p_disconnect_handler = + std::bind(&DisconnectCallback, + this, + std::placeholders::_1, + std::placeholders::_2); + +ClientCoreState::ApplicationReconnectCallbackPtr p_reconnect_handler = + std::bind(&ReconnectCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + +ClientCoreState::ApplicationResubscribeCallbackPtr p_resubscribe_handler = + std::bind(&ResubscribeCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + +p_iot_client_ = std::shared_ptr( + MqttClient::Create(p_network_connection_, + ConfigCommon::mqtt_command_timeout_, + p_disconnect_handler, nullptr, + p_reconnect_handler, nullptr, + p_resubscribe_handler, nullptr)); + +rc = p_iot_client_->Connect(/*...*/); + +``` + +_Example of setting lifecycle events in V2_ + +``` +builder->WithClientConnectionSuccessCallback( + [&](const Mqtt5::OnConnectionSuccessEventData &eventData) { }); + +builder->WithClientConnectionFailureCallback([&]( + const Mqtt5::OnConnectionFailureEventData &eventData) { }); + +builder->WithClientStoppedCallback([&]( + const Mqtt5::OnStoppedEventData & eventData) { }); + +builder->WithClientAttemptingConnectCallback([&]( + OnAttemptingConnectEventData &eventData)) { }); + +builder->WithClientDisconnectionCallback([&]( + OnDisconnectionEventData &eventData) { }); + +std::shared_ptr client = builder->Build(); + +``` + +### Publish + +V1 SDK provides two API calls for publishing: blocking and non-blocking. For the non-blocking version, the result of the publish operation is reported via a set of callbacks. If you try to publish to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. + +V2 SDK provides only asynchronous non-blocking API. A [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) object containing a description of the PUBLISH packet. The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation takes a `PublishPacket` instance and a [Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) in its parameter that will contain different data depending on the `QoS` used in the publish. + +* For QoS 0 (AT_MOST_ONCE): Calling `getValue` will return `null` and the promise will be complete as soon as the packet has been written to the socket. +* For QoS 1 (AT_LEAST_ONCE): Calling `getValue` will return a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) and the promise will be complete as soon as the PUBACK is received from the broker. + +If the operation fails for any reason before these respective completion events, the promise is rejected with a descriptive error. You should always check the reason code of a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) completion to determine if a QoS 1 publish operation actually succeeded. + +_Example of publishing in V1_ + +``` +// Blocking API. +std::chrono::milliseconds action_response_timeout = 20; +bool is_retained = false; +bool is_duplicate = false; + +ResponseCode rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), + is_retained, + is_duplicate, + awsiotsdk::mqtt::QoS::QOS1, + "hello", + action_response_timeout); +``` + +``` +// Non-blocking API. +std::chrono::milliseconds action_response_timeout = 20; +bool is_retained = false; +bool is_duplicate = false; +uint16_t packet_id = 0; +void PublishActionTester::AsyncAckHandler(uint16_t action_id, ResponseCode rc) { + /* callback function */ +} +ActionData::AsyncAckNotificationHandlerPtr p_async_ack_handler = + std::bind(&PublishActionTester::AsyncAckHandler, + this, + std::placeholders::_1, + std::placeholders::_2); +uint16_t &packet_id_out; + +rc = p_iot_client_->PublishAsync(Utf8String::Create("my/topic"), + is_retained, + is_duplicate, + mqtt::QoS::QOS0, + "hello", + p_async_ack_handler, + packet_id); +``` + +_Example of publishing in V2_ + +``` +std::shared_ptr publish = + std::make_shared( + "my topic", + "hello", + Mqtt5::QOS::AWS_MQTT5_QOS_AT_LEAST_ONCE); + +auto onPublishComplete = + [](int, std::shared_ptr result) + { /* publish callback */ }; + +bool rc = client->Publish(publish, onPublishComplete); + +``` + +### Subscribe + +V1 provides blocking and non-blocking API for subscribing. To subscribe to topic in V1, you should provide an instance of [awsiotsdk::mqtt::Subscription](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1mqtt_1_1_subscription.html) to the [subscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a9702f18a7d663aae5b76bae70d3999c7) operation. awsiotsdk::mqtt::Subscription object (or, usually, an object of a children class) implements `ApplicationCallbackHandlerPtr` method which will be called on receiving a new message. If you try to subscribe to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. + +V2 SDK provides only asynchronous non-blocking API. First, you need to create a [SubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_subscribe_packet.html) object. If you specify multiple topics in the WithSubscription member function, V2 SDK will subscribe to all of these topics using one request. The [Subscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa6c3bfc3cbd99b17957148ac1e8c34c4) operation takes a description of the `SubscribePacket` you wish to send and sends back a callback that resolves with success or failure with the corresponding [SubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_sub_ack_packet.html) returned by the broker; You should always check the reason codes of a `SubAckPacket` completion to determine if the subscribe operation actually succeeded. + +In V2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, it is important to also setup the `builder.WithPublishReceivedCallback` callback. This callback is invoked whenever the client receives a message from the server on a topic the client is subscribed to. With this callback, you can process messages made to subscribed topics. + +_Example of subscribing in V1_ + +``` +ResponseCode PubSub::SubscribeCallback( + util::String topic_name, + util::String payload, + std::shared_ptr p_app_handler_data) +{ + /* subscribe callback */ + return ResponseCode::SUCCESS; +} + +std::unique_ptr p_topic_name = Utf8String::Create("my/own/topic"); +mqtt::Subscription::ApplicationCallbackHandlerPtr p_sub_handler = + std::bind(&PubSub::SubscribeCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + + +std::shared_ptr p_subscription = + mqtt::Subscription::Create(std::move(p_topic_name), + mqtt::QoS::QOS0, + p_sub_handler, + nullptr); // handler data + +util::Vector> topic_vector; +topic_vector.push_back(p_subscription); +std::chrono::milliseconds action_response_timeout = 10; + +// Subscribe to topic +ResponseCode rc = p_iot_client_->Subscribe(topic_vector, + action_response_timeout); + +``` + +_Example of subscribing in V2_ + +``` +builder->WithPublishReceivedCallback( + [&](const Mqtt5::PublishReceivedEventData &eventData) { + /*Called when a message is received by one of the active subscriptions.*/ + }); + +std::shared_ptr client = builder->Build(); + +Mqtt5::Subscription sub1("my/own/topic", + Mqtt5::QOS::AWS_MQTT5_QOS_AT_LEAST_ONCE); +std::shared_ptr subPacket = + std::make_shared(); +subPacket->WithSubscription(std::move(sub1)); + +auto onSubAck = [&](int error_code, + std::shared_ptr suback) +{ /* acknowledge callback */ }; + +// Subscribe to topic +bool rc = client->Subscribe(subPacket, onSubAck); + +``` + + + +### Unsubscribe + +V1 SDK provides blocking and non-blocking API for unsubscribing. To unsubscribe from topic in V1, you should provide a `std::vector` of `std::unique_ptr` of `Utf8String` to the [Unsubscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a8dc5fa8e8c1522219e6df33cbaa7e376) operation. +For asynchronous operations use [UnsubscribeAsync](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a4577dd3e720dea692755c640d4c638ed) success and failure results are sent through the callback [ActionData::AsyncAckNotificationHandlerPtr](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_action_data.html#a5d1d7452e081205b414e4df985d82f60) + +V2 SDK provides only asynchronous non-blocking API. First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) object with the help of [UnsubscribePacketBuilder](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/UnsubscribePacket.UnsubscribePacketBuilder.html). The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) operation takes a description of the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) you wish to send and returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) returned by the broker; the promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) is received. You should always check the reason codes of a [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) completion to determine if the unsubscribe operation actually succeeded. +Similar to subscribing, you can unsubscribe from multiple topics in one request: just call [WithTopicFilter](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html#a822c4f630d69ce3d1ba6ce8db021ab2a) for each topic you wish to unsubscribe from. + +_Example of unsubscribing in V1_ + +``` +// Blocking API. +std::chrono::milliseconds action_response_timeout = 20; +std::unique_ptr p_topic_name = Utf8String::Create("my/topic"); +util::Vector> topic_vector; +topic_vector.push_back(std::move(p_topic_name)); +ResponseCode rc = p_iot_client_->Unsubscribe(std::move(topic_vector), + action_response_timeout); + +``` + +``` +// Non-blocking API. +void unsubAck(uint16_t action_id, ResponseCode rc) +{ +} +uint16_t packet_id = 0; +util::Vector> topic_vector; +p_topic_name = "my/topic"; +topic_vector.push_back(std::move(p_topic_name)); +ActionData::AsyncAckNotificationHandlerPtr p_async_ack_handler +auto unsubAck = [&](uint16_t action_id, ResponseCode rc) { }; +ResponseCode rc = p_iot_client_->UnsubscribeAsync(std::move(topic_vector), + unsubAck, + packet_id); +``` + +_Example of unsubscribing in V2_ + +``` +std::shared_ptr unsub = + std::make_shared(); +unsub->WithTopicFilter("my/topic"); +auto unsubAck = [&](int, std::shared_ptr) { + /* callback */ + }; +bool rc = client->Unsubscribe(unsub, unsubAck); + +``` + + + +### Client Stop + +In V1 SDK, the `disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `connect`. + +In V2 SDK, an MQTT5 client can stop a session by calling the [stop](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#stop(software.amazon.awssdk.crt.mqtt5.packets.DisconnectPacket)) method. You can provide an optional [DisconnectPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/DisconnectPacket.html) parameter. A closed client can be started again by calling [start](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#start()). + +_Example of disconnecting a client in V1_ + +``` +std::chrono::milliseconds action_response_timeout = 20; +client.Disconnect(action_response_timeout); +``` + +_Example of disconnecting a client in V2_ + +``` +builder->WithClientStoppedCallback([](const Mqtt5::OnStoppedEventData &event) { + /* on stop callback */ +}); +Mqtt5Client client = builder->Build(); +client->Stop(); +``` + + + +### Reconnects + +V1 attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called + +V2 attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). + + +_Example of tweaking reconnection settings in V1_ + +``` +std::chrono::seconds min_reconnect_backoff_timeout = 20; +std::chrono::seconds max_reconnect_backoff_timeout = 30; +client.SetMinReconnectBackoffTimeout(min_reconnect_backoff_timeout); +client.SetMaxReconnectBackoffTimeout(max_reconnect_backoff_timeout); +``` + +_Example of tweaking reconnection settings in V2_ + +``` +Aws::Crt::Mqtt5::ReconnectOptions reconnectOptions = { + Mqtt5::JitterMode::AWS_EXPONENTIAL_BACKOFF_JITTER_FULL, // reconnect mode + 1000, // min reconnect delay ms + 1000, // max reconnect delay ms + 1000 // min connected time to reset reconnect delay ms +}; +builder.WithReconnectOptions(); +Mqtt5Client client = builder->Build(); + +``` + + + +### Offline Operations Queue + +V1 doesn’t set a limit on the number on in-flight publish + +V2 provides a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: + +_Example of configuring the offline queue in V2_ + +``` +AwsIotMqtt5ClientBuilder builder; +std::shared_ptrbuilder( + Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(/* ... */)); +builder.WithOfflineQueueBehavior( + Mqtt5::ClientOperationQueueBehaviorType:: + AWS_MQTT5_COQBT_FAIL_QOS0_PUBLISH_ON_DISCONNECT); +Mqtt5Client client = builder->Build(); + +``` + +Note that AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. + +``` +Mqtt5::Mqtt5ClientOperationStatistics statistics = + mqtt5Client->GetOperationStatistics(); +std::cout<<"Client operations queue statistics\n" + <<"\tgetUnackedOperationCoount: " < client_id = Utf8String::Create(client_id_tagged); + +rc = p_iot_client_->Connect(connectTimeout, + true + mqtt::Version::MQTT_3_1_1, + keepAliveTimeout, + std::move(client_id), + nullptr, + nullptr, + nullptr); + +std::chrono::seconds publishTimeout = 10; +rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), + false, + false, + awsiotsdk::mqtt::QoS::QOS1, + "hello", + publishTimeout); +``` + +_Example of timeouts in V2_ + +``` +builder.WithAckTimeoutSeconds(10); +Mqtt5Client client = builder->Build(); +``` + + + +### Logging + +V1 and V2 SDK uses a custom logger allowing to control the logging process simultaneously for all layers of the SDK. + +_Example of enabling logging in V1_ +To enable logging on V1 follow the next example: + +``` +#include "util/logging/Logging.hpp" +#include "util/logging/LogMacros.hpp" +#include "util/logging/ConsoleLogSystem.hpp" + +std::shared_ptr p_log_system = + std::make_shared( + awsiotsdk::util::Logging::LogLevel::Info); +awsiotsdk::util::Logging::InitializeAWSLogging(p_log_system); + +AWS_LOG_INFO(INTEG_TEST_RUNNER_LOG_TAG, + "Initialize Test Config Failed with rc : %d", + 32); +``` + +_Example of enabling logging in V2_ +You can enable logging by passing the folowing properties: + +``` +ApiHandle apiHandle; + +apiHandle.InitializeLogging(Aws::Crt::LogLevel::Info, + "logFile"); +/* or */ +apiHandle.InitializeLogging(logLevel, stderr); + +AWS_LOGF_ERROR("log location", "Invalid operation"); + +``` + +_Example of shutting down logging_ + +``` +awsiotsdk::util::Logging::ShutdownAWSLogging(); +``` + +In V2 logging is shutdown automatically with ApiHandle destruction when it goes out of scope + +### Client for Device Shadow Service + +V1 SDK is built with [AWS IoT device shadow support](http://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-shadows.html), providing access to thing shadows (sometimes referred to as device shadows). It also supports a simplified shadow access model, which allows developers to exchange data with their shadows by just using getter and setter methods without having to serialize or deserialize any JSON documents. + +V2 SDK supports device shadow service as well, but with completely different API. +First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. For example, `SubscribeToGetShadow``Accepted` subscribes to a topic to which AWS IoT Core will publish a shadow document; and via the `SubscribeToGetShadowRejected` the server will notify you if it cannot send you a requested document. +After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. For example, `PublishGetShadow` sends a request to AWS IoT Core to get a shadow document. The requested Shadow document will be received in a callback specified in the `SubscribeToGetShadowAccepted` call. + +AWS IoT Core [documentation for Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) service provides detailed descriptions for the topics used to interact with the service. + +_Example of creating a Device Shadow service client in V1_ + +``` +#include "shadow/Shadow.hpp" +// Blocking and non-blocking API. +String thingName = ""; +std::chrono::milliseconds mqtt_command_timeout = 200; +ResponseCode rc = p_iot_client_->Connect(/* ... */); +// 1st way +Shadow shadowClient( + p_iot_client_, + mqtt_command_timeout, + thingNmae, + clientTokenPrefix); + +// 2nd way + std::unique_ptr shadowClient = Shadow::Create( + p_iot_client_, + mqtt_command_timeout, + thingName, + clientTokenPrefix); + +``` + + + +``` +// Simplified shadow Access Model. +ResponseCode ShadowDelta::ActionResponseHandler( + util::String thing_name, + ShadowRequestType request_type, + ShadowResponseType response_type, + util::JsonDocument &payload) +{ +} +Shadow::RequestHandlerPtr p_action_handler = std::bind( + &ShadowDelta::ActionResponseHandler, + this, std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3, + std::placeholders::_4); +util::Map request_mapping; +request_mapping.insert(std::make_pair(ShadowRequestType::Get, p_action_handler)); +request_mapping.insert(std::make_pair(ShadowRequestType::Update, p_action_handler)); +request_mapping.insert(std::make_pair(ShadowRequestType::Delete, p_action_handler)); +request_mapping.insert(std::make_pair(ShadowRequestType::Delta, p_action_handler)); + +my_shadow.AddShadowSubscription(request_mapping); + +``` + + +_Example of creating a Device Shadow service client in V2_ +A thing name in V2 SDK shadow client is specified for the operations with shadow documents. + +``` +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +std::shared_ptr client = builder->Build(); +client->Start(); +Aws::Iotshadow::IotShadowClient shadowClient(client); + +``` + + +_Example of getting a shadow document in V1_ + +``` +// Blockig API. +std::condition_variable sync_action_response_wait_; +ResponseCode ShadowDelta::ActionResponseHandler( + util::String thing_name, + ShadowRequestType request_type, + ShadowResponseType response_type, + util::JsonDocument &payload) +{ + sync_action_response_wait_.notify_all(); + return 0; +} + +std::unique_lock block_handler_lock(sync_action_response_lock_); +{ + ResponseCode rc = my_shadow.performGetAsync(); + std::chrono::milliseconds shadow_action_timeout = 200; + if (ResponseCode::SUCCESS == rc) { + cv_status cv = sync_action_response_wait_.wait_for( + block_handler_lock, + shadow_action_timeout); + if (cv = cv_status::no_timeout) { + util::JsonDocumen doc = my_shadow.GetServerDocument(); + } + } +} +``` + +``` + // Non-blocking API. + ResponseCode rc = my_shadow.performGetAsync(); + util::JsonDocumen doc = my_shadow.GetServerDocument(); + +``` + + +_Example of getting a shadow document in V2_ + +``` +GetShadowSubscriptionRequest shadowSubscriptionRequest; +shadowSubscriptionRequest.ThingName = ""; + +auto onGetShadowAccepted = [&](GetShadowResponse *response, int ioErr) { + /* shadow document received. */ + /* The `response` object contains the shadow document. */ + }; +auto onGetShadowUpdatedAcceptedSubAck = [&](int ioErr) { }; +auto onGetShadowRejected = [&](ErrorResponse *error, int ioErr) { + /* called when getting the shadow document failed. */ + }; + +shadowClient.SubscribeToGetShadowAccepted( + shadowSubscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + onGetShadowAccepted, + onGetShadowUpdatedAcceptedSubAck); + +auto onGetShadowUpdatedRejectedSubAck = [&](int ioErr) { }; +shadowClient.SubscribeToGetShadowRejected( + shadowSubscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + onGetShadowRejected, + onGetShadowUpdatedRejectedSubAck); + +GetShadowRequest shadowGetRequest; +shadowGetRequest.ThingName = ""; +auto onGetShadowRequestSubAck = [&](int ioErr) { }; + +/* Send request for a shadow document. + On success, the document will be received on `onGetShadowAccepted` callback. + On failure, the `onGetShadowRejected` callback will be called. */ +shadowClient.PublishGetShadow( + shadowGetRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + onGetShadowRequestSubAck); + +``` + + +_Example of updating a shadow document in V1_ + +``` +// Non-blocking API. +util::JsonDocument doc; +util::JsonParser::InitializeFromJsonString( + doc, + "{\"state\":{\"reported\":{\"sensor\":3.0}}}"); +my_shadow.UpdateDeviceShadow(doc); +rc = my_shadow.PerformUpdateAsync(); + +/* for a blocking model look at the Example of getting a shadow document in V1 */ +``` + +_Example of updating a shadow document in V2_ + +``` +UpdateShadowRequest updateShadowRequest; +updateShadowRequest.ClientToken = uuid.ToString(); +updateShadowRequest.ThingName = "; + +ShadowState state; +JsonObject desired; +desired.WithString("sensor", "2.9"); +state.Desired = desired; +updateShadowRequest.State = state; + + +auto onUpdateShadowAccepted = [&](UpdateShadowResponse *response, int ioErr) { + // Called when an update request succeeded. + }; +auto onUpdatedAcceptedSubAck = [&](int ioErr) { }; + +UpdateShadowSubscriptionRequest updateShadowSubscriptionRequest; +updateShadowSubscriptionRequest.ThingName = ""; +shadowClient.SubscribeToUpdateShadowAccepted( + updateShadowSubscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + onUpdateShadowAccepted, + onUpdatedAcceptedSubAck); + +auto onUpdateShadowRejected = [&](ErrorResponse *error, int ioErr) { + // Called when an update request failed. + }; +auto onUpdatedRejectedSubAck = [&](int ioErr) { }; +shadowClient.SubscribeToUpdateShadowRejected( + updateShadowSubscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + onUpdateShadowRejected, + onUpdatedRejectedSubAck); + + +auto publishCompleted = [&](int ioErr) { }; +shadowClient.PublishUpdateShadow( + updateShadowRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + std::move(publishCompleted)); + +``` + +See API documentation for V2 SDK [Device Shadow](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotshadow.html) service client for more details. +Refer to the V2 SDK [Device Shadow](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/shadow) sample for code example. + + +### Client for Jobs Service + +V1 and V2 SDK offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. + +V1 IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) + +The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR759cb689cfb8488da0d1d539f). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. + +AWS IoT Core documentation for [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html) service provides detailed descriptions for the topics used to interact with the service. + +See API documentation for V2 SDK [Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html) service clients for more details. +Refer to the V2 SDK [Jobs](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/jobs) samples for code examples. + +_V1 example executing jobs_ + +``` +ResponseCode GetPendingCallback( + util::String topic_name, + util::String payload, + std::shared_ptr p_app_handler_data) +{} +ResponseCode NextJobCallback( + util::String topic_name, + util::String payload, + std::shared_ptr p_app_handler_data) +{} +ResponseCode UpdateAcceptedCallback( + util::String topic_name, + util::String payload, + std::shared_ptr p_app_handler_data) +{} +ResponseCode UpdateRejectedCallback( + util::String topic_name, + util::String payload, + std::shared_ptr p_app_handler_data) +{} +rc = p_iot_client_->Connect(/*...*/); + + +mqtt::Subscription::ApplicationCallbackHandlerPtr p_pending_handler = + std::bind( + &GetPendingCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + +mqtt::Subscription::ApplicationCallbackHandlerPtr p_next_handler = + std::bind( + &NextJobCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + +mqtt::Subscription::ApplicationCallbackHandlerPtr p_update_accepted_handler = + std::bind( + &UpdateAcceptedCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + +mqtt::Subscription::ApplicationCallbackHandlerPtr p_update_rejected_handler = + std::bind( + &UpdateRejectedCallback, + this, + std::placeholders::_1, + std::placeholders::_2, + std::placeholders::_3); + +util::Vector> topic_vector; +std::shared_ptr p_subscription; + +p_subscription = p_jobs_->CreateJobsSubscription( + p_pending_handler, + nullptr, + Jobs::JOB_GET_PENDING_TOPIC, + Jobs::JOB_ACCEPTED_REPLY_TYPE); +topic_vector.push_back(p_subscription); + +p_subscription = p_jobs_->CreateJobsSubscription( + p_next_handler, + nullptr, + Jobs::JOB_DESCRIBE_TOPIC, + Jobs::JOB_ACCEPTED_REPLY_TYPE, + "$next"); +topic_vector.push_back(p_subscription); + +p_subscription = p_jobs_->CreateJobsSubscription( + p_next_handler, + nullptr, + Jobs::JOB_NOTIFY_NEXT_TOPIC); +topic_vector.push_back(p_subscription); + +p_subscription = p_jobs_->CreateJobsSubscription( + p_update_accepted_handler, + nullptr, + Jobs::JOB_UPDATE_TOPIC, + Jobs::JOB_ACCEPTED_REPLY_TYPE, + "+"); +topic_vector.push_back(p_subscription); + +p_subscription = p_jobs_->CreateJobsSubscription( + p_update_rejected_handler, + nullptr, + Jobs::JOB_UPDATE_TOPIC, + Jobs::JOB_REJECTED_REPLY_TYPE, + "+"); +topic_vector.push_back(p_subscription); + +ResponseCode rc = p_iot_client_->Subscribe( + topic_vector, + ConfigCommon::mqtt_command_timeout_); + +util::String client_id_tagged = ConfigCommon::base_client_id_; +client_id_tagged.append("_jobs_sample_"); +client_id_tagged.append(std::to_string(rand())); + +p_jobs_ = Jobs::Create( + p_iot_client_, + mqtt::QoS::QOS1, + "", + client_id_tagged); +ResponseCode rc; +rc = p_jobs_->SendJobsQuery(Jobs::JOB_GET_PENDING_TOPIC); +rc = p_jobs_->SendJobsQuery(Jobs::JOB_DESCRIBE_TOPIC, "$next"); + +``` + +_V2 example executig a job_ + +``` +IotJobsClient jobsClient(client); + +auto subscriptionHandler = [&](DescribeJobExecutionResponse *response, int ioErr) +{ }; +auto subAckHandler = [&](int) + { }; + +// Get information about the job +DescribeJobExecutionSubscriptionRequest describeJobExecutionSubscriptionRequest; +describeJobExecutionSubscriptionRequest.ThingName = ""; +describeJobExecutionSubscriptionRequest.JobId = ""; + +jobsClient.SubscribeToDescribeJobExecutionAccepted( + describeJobExecutionSubscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + subscriptionHandler, + subAckHandler); + +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { }; + +jobsClient.SubscribeToDescribeJobExecutionRejected( + describeJobExecutionSubscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + failureHandler, + subAckHandler); + +DescribeJobExecutionRequest describeJobExecutionRequest; +describeJobExecutionRequest.ThingName = ""; +describeJobExecutionRequest.JobId = ""; +describeJobExecutionRequest.IncludeJobDocument = true; +Aws::Crt::UUID uuid; +describeJobExecutionRequest.ClientToken = uuid.ToString(); + +auto publishHandler = [&](int ioErr) { }; + +jobsClient.PublishDescribeJobExecution( + QTT_QOS_AT_LEAST_ONCE, + publishHandler); +auto OnSubscribeToStartNextPendingJobExecutionAcceptedResponse = + [&](StartNextJobExecutionResponse *response, int ioErr) { }; + +// Gets and starts the next pending job execution for a thing ( +StartNextPendingJobExecutionSubscriptionRequest subscriptionRequest; +subscriptionRequest.ThingName = ""; + +jobsClient.SubscribeToStartNextPendingJobExecutionAccepted( + subscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + OnSubscribeToStartNextPendingJobExecutionAcceptedResponse, + subAckHandler); +jobsClient.SubscribeToStartNextPendingJobExecutionRejected( + subscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + failureHandler, + subAckHandler); + +StartNextPendingJobExecutionRequest publishRequest; +publishRequest.ThingName = cmdData.input_thingName; +publishRequest.StepTimeoutInMinutes = 15L; + +jobsClient.PublishStartNextPendingJobExecution( + publishRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + publishHandler); + + +// Send an update about the status of the job +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { }; + +auto subscribeHandler = [&](UpdateJobExecutionResponse *response, int ioErr) { }; + +auto publishHandler = [&](int ioErr) { }; + +jobsClient.SubscribeToUpdateJobExecutionAccepted( +subscriptionRequest, AWS_MQTT_QOS_AT_LEAST_ONCE, subscribeHandler, subAckHandler); + +jobsClient.SubscribeToUpdateJobExecutionRejected( +subscriptionRequest, AWS_MQTT_QOS_AT_LEAST_ONCE, failureHandler, subAckHandler); + +UpdateJobExecutionRequest publishRequest; +publishRequest.ThingName = ""; +publishRequest.JobId = ""; +publishRequest.ExecutionNumber = 12; +publishRequest.Status = JobStatus::IN_PROGRESS; +publishRequest.ExpectedVersion = 0 + +jobsClient.PublishUpdateJobExecution( + publishRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + publishHandler); + +``` + + + +### Client for Fleet Provisioning Service + +Another IoT service that V2 SDK provides access to is [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) (also known as Identity Service). By using AWS IoT fleet provisioning, AWS IoT can generate and securely deliver device certificates and private keys to your devices when they connect to AWS IoT for the first time. + +The Fleet Provisioning service client provides API similar to API provided by [Client for Device Shadow Service](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR759cb689cfb8488da0d1d539f). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. + +AWS IoT Core documentation for [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/fleet-provision-api.html) service provides detailed descriptions for the topics used to interact with the service. + +See API documentation for V2 SDK [Fleet Provisioning](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotidentity.html) service client for more details. +Refer to the V2 SDK [Fleet Provisioning](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/fleet_provisioning/mqtt5_fleet_provisioning) samples for code examples. + + +### Example + +It’s always helpful to look at a working example to see how new functionality works, to be able to tweak different options, to compare with existing code. For that reasons, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) ([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp)) in V2 SDK similar to a sample provided by V1 SDK (see a corresponding [readme section](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/README.md) and [source code](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/PubSub/PubSub.cpp)). + + +## How to get help + +For any migration related questions or feedback, you can contact us at [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions) by submitting an issue with a label `label:migration`. + +## Appendix + +### MQTT5 Features + +**Clean Start and Session Expiry** +You can use Clean Start and Session Expiry to handle your persistent sessions with more flexibility. +Refer to [Mqtt5ClientOptions.ClientSessionBehavior](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client_options.html#a61d6bedd2502d209db912838f74462bb) enum and [NegotiatedSettings.getSessionExpiryInterval](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#aed6565927dcc2ecfb789f978f5a1aee4) method for details. + +**Reason Code on all ACKs** +You can debug or process error messages more easily using the reason codes. Reason codes are returned by the message broker based on the type of interaction with the broker (Subscribe, Publish, Acknowledge). +See [PubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a5901f1fc1e66ef0f859402b747630a02), [SubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a272e5b89320326afd9e0de269100ccd3), [UnsubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a0fece0c83f48d577ea7dfafe58f1261a), [ConnectReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a25d5cf0c9496d5002642c146bf0af9b2), [DisconnectReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ac305e4f9be3e3b06adfdb0abb4814163). + +**Topic Aliases** +You can substitute a topic name with a topic alias, which is a two-byte integer. +Use [withTopicAlias](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#a609e3b04a9c670e07f746da527d3bf17) method when creating a PUBLISH packet. + +**Message Expiry** +You can add message expiry values to published messages. Use [withMessageExpiryIntervalSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#aa9e7f2887ab39b0c82a990119df7b941) method in PublishPacketBuilder class. + +**Server disconnect** +When a disconnection happens, the server can proactively send the client a DISCONNECT to notify connection closure with a reason code for disconnection. +Refer to [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) class for details. + +**Request/Response** +Publishers can request a response be sent by the receiver to a publisher-specified topic upon reception. Use [withResponseTopic](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#acccc99a74512973210026a24f37c2db5) method in PublishPacketBuilder class. + +**Maximum Packet Size** +Client and Server can independently specify the maximum packet size that they support. See [connectPacketBuilder.withMaximumPacketSizeBytes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a88ec9f83510875c5cd92277ecc439bad), [NegotiatedSettings.getMaximumPacketSizeToServer](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a25670e9f1c004d93b3332cd432689b92), and [ConnAckPacket.getMaximumPacketSize](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#a83a5f4aaa007bdf6dddc41c718d0bfd6) methods. + +**Payload format and content type** +You can specify the payload format (binary, text) and content type when a message is published. These are forwarded to the receiver of the message. Use [withContentType](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#a0a5e4d33a3c82cdf4d6ef5d490bd509f) method in PublishPacketBuilder class. + +**Shared Subscriptions** +Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. +Refer to [shared subscription](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/samples/Mqtt5/SharedSubscription/README.md) in V2 SDK. +**NOTE** AWS IoT Core provides this functionality for MQTT3 as well. + From afea330bb52e6f9faad6058a16175e36cc394d6c Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 2 Feb 2024 18:35:47 -0800 Subject: [PATCH 02/33] Polish the migration guide document --- documents/MIGRATION_GUIDE.md | 208 +++++++++++++++++++++++------------ 1 file changed, 140 insertions(+), 68 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 496c68b71..c20ba2d0e 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -1,5 +1,32 @@ # Migrate from V1 to V2 of the AWS IoT SDK for C++ +> [!TIP] +> If you can't find necessary information in this guide, the [How to Get Help](#how-to-get-help) section will guide you. + +* [What’s New in V2 SDK](#whats-new-in-v2-sdk) +* [How to Get Started with V2 SDK](#how-to-get-started-with-v2-sdk) + * [MQTT Protocol](#mqtt-protocol) + * [Client Builder](#client-builder) + * [Connection Types and Features](#connection-types-and-features) + * [Lifecycle Events](#lifecycle-events) + * [Publish](#publish) + * [Subscribe](#subscribe) + * [Unsubscribe](#unsubscribe) + * [Client Stop](#client-stop) + * [Reconnects](#reconnects) + * [Offline Operations Queue](#offline-operations-queue) + * [Operation Timeouts](#operation-timeouts) + * [Logging](#logging) + * [Client for Device Shadow Service](#client-for-device-shadow-service) + * [Client for Jobs Service](#client-for-jobs-service) + * [Client for Fleet Provisioning Service](#client-for-fleet-provisioning-service) + * [Example](#example) +* [How to Get Help](#how-to-get-help) +* [Appendix](#appendix) + * [MQTT5 Features](#mqtt5-features) + + + The V2 AWS IoT SDK for C++ is a major rewrite of the V1 code base. It includes many updates, such as improved consistency, ease of use, more detailed information about client status, an offline operation queue control, etc. This guide describes the major features that are new in V2, and provides guidance on how to migrate your code to V2 from V1. ## What’s new in V2 SDK @@ -34,7 +61,8 @@ In V1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-web In V2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) class represents an MQTT client, specifically MQTT5 protocol. V2 SDK provides an [Aws::Iot::Mqtt5ClientBuilder](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html) designed to easily create common configuration types such as direct MQTT or WebSocket connections. Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot have its settings modified. -_Example of creating a client in V1_ +
+Example of creating a client in V1 ``` #include "OpenSSLConnection.hpp" @@ -55,8 +83,10 @@ uint16_t clientPort = privateKeyFile); ResponseCode rc = p_network_connection->Initialize(); ``` +
-_Example of creating a client in V2_ +
+Example of creating a client in V2 V2 SDK supports different connection types. Given the same input parameters as in the V1 example above, the most suitable method to create an MQTT5 client will [beNewMqtt5ClientBuilderWithMtlsFromPath](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#ab595bbc50e08b9d2f78f62e9efeafd65). @@ -79,6 +109,7 @@ builder->WithConnectOptions(connectOptions); builder->WithPort(clientPort); std::shared_ptr client = builder->Build(); ``` +
Refer to the [Connection Types and Features](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR0b9b69e08b72487dbe620342f) section for other connection types supported by V2 SDK. @@ -89,21 +120,20 @@ V1 SDK supports two types of connections to connect to the AWS IoT service: MQTT V2 SDK adds a collection of connection types and cryptography formats (e.g. [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) and [Custom Authorizer](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html)), credential providers (e.g. [Amazon Cognito](https://aws.amazon.com/cognito/) and [Windows Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores)), and other connection-related features. Refer to the “[Connecting To AWS IoT Core](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#connecting-to-aws-iot-core)” section of the MQTT5 user guide for detailed information and code snippets on each connection type and connection feature. -|Connection Type/Feature |V1 SDK |V2 SDK |User guide section | | -|--- |--- |--- |--- |--- | -| | | | | | -|MQTT over Secure WebSocket with AWS SigV4 authentication |✔ |✔ | | | -|MQTT (over TLS 1.2) with X.509 certificate based mutual authentication |✘ |✔ | |X.509 | -|MQTT with PKCS12 Method |✔* |✔ | |Container for X.509 | -|MQTT with Custom Key Operation Method |✔* |✔ | |X.509 | -|MQTT with Custom Authorizer Method |✔* |✔ | | | -|MQTT with Windows Certificate Store Method |✔* |✔ | |X.509 | -|MQTT with PKCS11 Method |✘ |✔ | |X.509 plus other formats | -|Websocket Connection with Cognito Authentication Method |✘ |✔ | | | -|HTTP Proxy |✔** |✔ | | | - -✔* - In order to get this connection type work in V1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html). -✔** - Though V1 does not allow to specify HTTP proxy, it is possible to configure systemwide proxy. +| Connection Type/Feature | V1 SDK | V2 SDK | User guide | +|----------------------------------------------------------|-----------------------------------------|----------------------------------|:----------:| +| MQTT over Secure WebSocket with AWS SigV4 authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-sigv4-authentication) | +| MQTT with X.509 certificate based mutual authentication | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-x509-based-mutual-tls) | +| MQTT with PKCS12 Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs12-method) | +| MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authorizer-method) | +| MQTT with Windows Certificate Store Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-windows-certificate-store-method) | +| MQTT with PKCS11 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs11-method) | +| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | +| HTTP Proxy | $${\Large\color{orange}✔\*\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#adding-an-http-proxy) | + +${\Large\color{orange}✔\*}$ - In order to get this connection type work in V1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ +${\Large\color{orange}✔\*\*}$ - Though V1 does not allow to specify HTTP proxy, it is possible to configure systemwide proxy. + ### Lifecycle Events @@ -114,8 +144,8 @@ V1 SDK provides 3 lifecycle events: “ClientCoreState::ApplicationResubscribeCa V2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: “WithClientConnectionSuccessCallback”, “WithClientConnectionFailureCallback”, “WithClientDisconnectionCallback”, “WithClientStoppedCallback”, and “WithClientAttemptingConnectCallback”. Refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management) for the details. -_Example of setting lifecycle events in V1_ - +
+Example of setting lifecycle events in V1 ``` std::shared_ptr p_iot_client_; ResponseCode DisconnectCallback( @@ -167,9 +197,10 @@ p_iot_client_ = std::shared_ptr( rc = p_iot_client_->Connect(/*...*/); ``` +
-_Example of setting lifecycle events in V2_ - +
+Example of setting lifecycle events in V2 ``` builder->WithClientConnectionSuccessCallback( [&](const Mqtt5::OnConnectionSuccessEventData &eventData) { }); @@ -189,6 +220,7 @@ builder->WithClientDisconnectionCallback([&]( std::shared_ptr client = builder->Build(); ``` +
### Publish @@ -201,8 +233,8 @@ V2 SDK provides only asynchronous non-blocking API. A [PublishPacket](https://a If the operation fails for any reason before these respective completion events, the promise is rejected with a descriptive error. You should always check the reason code of a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) completion to determine if a QoS 1 publish operation actually succeeded. -_Example of publishing in V1_ - +
+Example of publishing in V1 ``` // Blocking API. std::chrono::milliseconds action_response_timeout = 20; @@ -241,9 +273,10 @@ rc = p_iot_client_->PublishAsync(Utf8String::Create("my/topic"), p_async_ack_handler, packet_id); ``` +
-_Example of publishing in V2_ - +
+Example of publishing in V2 ``` std::shared_ptr publish = std::make_shared( @@ -258,6 +291,7 @@ auto onPublishComplete = bool rc = client->Publish(publish, onPublishComplete); ``` +
### Subscribe @@ -267,7 +301,8 @@ V2 SDK provides only asynchronous non-blocking API. First, you need to create a In V2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, it is important to also setup the `builder.WithPublishReceivedCallback` callback. This callback is invoked whenever the client receives a message from the server on a topic the client is subscribed to. With this callback, you can process messages made to subscribed topics. -_Example of subscribing in V1_ +
+Example of subscribing in V1 ``` ResponseCode PubSub::SubscribeCallback( @@ -303,9 +338,10 @@ ResponseCode rc = p_iot_client_->Subscribe(topic_vector, action_response_timeout); ``` +
-_Example of subscribing in V2_ - +
+Example of subscribing in V2 ``` builder->WithPublishReceivedCallback( [&](const Mqtt5::PublishReceivedEventData &eventData) { @@ -336,10 +372,11 @@ bool rc = client->Subscribe(subPacket, onSubAck); V1 SDK provides blocking and non-blocking API for unsubscribing. To unsubscribe from topic in V1, you should provide a `std::vector` of `std::unique_ptr` of `Utf8String` to the [Unsubscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a8dc5fa8e8c1522219e6df33cbaa7e376) operation. For asynchronous operations use [UnsubscribeAsync](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a4577dd3e720dea692755c640d4c638ed) success and failure results are sent through the callback [ActionData::AsyncAckNotificationHandlerPtr](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_action_data.html#a5d1d7452e081205b414e4df985d82f60) -V2 SDK provides only asynchronous non-blocking API. First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) object with the help of [UnsubscribePacketBuilder](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/UnsubscribePacket.UnsubscribePacketBuilder.html). The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) operation takes a description of the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) you wish to send and returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) returned by the broker; the promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) is received. You should always check the reason codes of a [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) completion to determine if the unsubscribe operation actually succeeded. +V2 SDK provides only asynchronous non-blocking API. First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) object. The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) operation takes a description of the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) you wish to send and returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) returned by the broker; the promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) is received. You should always check the reason codes of a [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) completion to determine if the unsubscribe operation actually succeeded. Similar to subscribing, you can unsubscribe from multiple topics in one request: just call [WithTopicFilter](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html#a822c4f630d69ce3d1ba6ce8db021ab2a) for each topic you wish to unsubscribe from. -_Example of unsubscribing in V1_ +
+Example of unsubscribing in V1 ``` // Blocking API. @@ -367,9 +404,10 @@ ResponseCode rc = p_iot_client_->UnsubscribeAsync(std::move(topic_vector), unsubAck, packet_id); ``` +
-_Example of unsubscribing in V2_ - +
+Example of unsubscribing in V2 ``` std::shared_ptr unsub = std::make_shared(); @@ -380,32 +418,36 @@ auto unsubAck = [&](int, std::shared_ptr) { bool rc = client->Unsubscribe(unsub, unsubAck); ``` - +
### Client Stop In V1 SDK, the `disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `connect`. -In V2 SDK, an MQTT5 client can stop a session by calling the [stop](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#stop(software.amazon.awssdk.crt.mqtt5.packets.DisconnectPacket)) method. You can provide an optional [DisconnectPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/DisconnectPacket.html) parameter. A closed client can be started again by calling [start](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#start()). +In V2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#abc503d1a67c4e1c232f8f722b3c59ca0) method. You can provide an optional [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) parameter. A closed client can be started again by calling [Start](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a9035534fc7cc8b48097518409e9c5a6b). -_Example of disconnecting a client in V1_ +
+Example of disconnecting a client in V1 ``` std::chrono::milliseconds action_response_timeout = 20; client.Disconnect(action_response_timeout); -``` -_Example of disconnecting a client in V2_ +``` +
+
+Example of disconnecting a client in V2 ``` builder->WithClientStoppedCallback([](const Mqtt5::OnStoppedEventData &event) { /* on stop callback */ }); Mqtt5Client client = builder->Build(); client->Stop(); -``` +``` +
### Reconnects @@ -415,16 +457,19 @@ V1 attempts to reconnect automatically until connection succeeds or `client.Disc V2 attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). -_Example of tweaking reconnection settings in V1_ - +
+Example of tweaking reconnection settings in V1 ``` std::chrono::seconds min_reconnect_backoff_timeout = 20; std::chrono::seconds max_reconnect_backoff_timeout = 30; client.SetMinReconnectBackoffTimeout(min_reconnect_backoff_timeout); client.SetMaxReconnectBackoffTimeout(max_reconnect_backoff_timeout); + ``` +
-_Example of tweaking reconnection settings in V2_ +
+Example of tweaking reconnection settings in V2 ``` Aws::Crt::Mqtt5::ReconnectOptions reconnectOptions = { @@ -437,7 +482,7 @@ builder.WithReconnectOptions(); Mqtt5Client client = builder->Build(); ``` - +
### Offline Operations Queue @@ -446,7 +491,8 @@ V1 doesn’t set a limit on the number on in-flight publish V2 provides a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: -_Example of configuring the offline queue in V2_ +
+Example of configuring the offline queue in V2 ``` AwsIotMqtt5ClientBuilder builder; @@ -459,8 +505,10 @@ Mqtt5Client client = builder->Build(); ``` -Note that AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. +Note that AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). +The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. +Example of getting operation statistics ``` Mqtt5::Mqtt5ClientOperationStatistics statistics = mqtt5Client->GetOperationStatistics(); @@ -471,6 +519,7 @@ std::cout<<"Client operations queue statistics\n" <<"\tgetIncompleteOperationSize: "< See [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) for more details. See [ClientOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) to find the list of the supported offline queue behaviors and their description. @@ -483,7 +532,8 @@ In V1 SDK, all operations (*publish*, *subscribe*, *unsubscribe*) will not timeo In V2 SDK, operations timeout is set for the MQTT5 client with the builder method [withAckTimeoutSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#a2769eb658b3809c5bd3d28724b936a67). The default value is no timeout. As in V1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won’t block the client. The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking operations. -_Example of timeouts in V1_ +
+Example of timeouts in V1 ``` std::chrono::milliseconds connectTimeout = 200; @@ -508,22 +558,27 @@ rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), awsiotsdk::mqtt::QoS::QOS1, "hello", publishTimeout); + ``` +
-_Example of timeouts in V2_ +
+Example of timeouts in V2 ``` builder.WithAckTimeoutSeconds(10); Mqtt5Client client = builder->Build(); -``` +``` +
### Logging V1 and V2 SDK uses a custom logger allowing to control the logging process simultaneously for all layers of the SDK. -_Example of enabling logging in V1_ +
+Example of enabling logging in V1 To enable logging on V1 follow the next example: ``` @@ -540,8 +595,10 @@ AWS_LOG_INFO(INTEG_TEST_RUNNER_LOG_TAG, "Initialize Test Config Failed with rc : %d", 32); ``` +
-_Example of enabling logging in V2_ +
+Example of enabling logging in V2 You can enable logging by passing the folowing properties: ``` @@ -555,12 +612,16 @@ apiHandle.InitializeLogging(logLevel, stderr); AWS_LOGF_ERROR("log location", "Invalid operation"); ``` +
-_Example of shutting down logging_ +
+Example of shutting down logging ``` awsiotsdk::util::Logging::ShutdownAWSLogging(); + ``` +
In V2 logging is shutdown automatically with ApiHandle destruction when it goes out of scope @@ -574,8 +635,8 @@ After subscribing to all the required topics, the service client can start inter AWS IoT Core [documentation for Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) service provides detailed descriptions for the topics used to interact with the service. -_Example of creating a Device Shadow service client in V1_ - +
+Example of creating a Device Shadow service client in V1 ``` #include "shadow/Shadow.hpp" // Blocking and non-blocking API. @@ -598,8 +659,6 @@ Shadow shadowClient( ``` - - ``` // Simplified shadow Access Model. ResponseCode ShadowDelta::ActionResponseHandler( @@ -624,9 +683,11 @@ request_mapping.insert(std::make_pair(ShadowRequestType::Delta, p_action_handler my_shadow.AddShadowSubscription(request_mapping); ``` +
-_Example of creating a Device Shadow service client in V2_ +
+Example of creating a Device Shadow service client in V2 A thing name in V2 SDK shadow client is specified for the operations with shadow documents. ``` @@ -646,9 +707,11 @@ client->Start(); Aws::Iotshadow::IotShadowClient shadowClient(client); ``` +
-_Example of getting a shadow document in V1_ +
+Example of getting a shadow document in V1 ``` // Blockig API. @@ -676,6 +739,7 @@ std::unique_lock block_handler_lock(sync_action_response_lock_); } } } + ``` ``` @@ -684,10 +748,11 @@ std::unique_lock block_handler_lock(sync_action_response_lock_); util::JsonDocumen doc = my_shadow.GetServerDocument(); ``` +
-_Example of getting a shadow document in V2_ - +
+Example of getting a shadow document in V2 ``` GetShadowSubscriptionRequest shadowSubscriptionRequest; shadowSubscriptionRequest.ThingName = ""; @@ -727,10 +792,11 @@ shadowClient.PublishGetShadow( onGetShadowRequestSubAck); ``` +
-_Example of updating a shadow document in V1_ - +
+Example of updating a shadow document in V1 ``` // Non-blocking API. util::JsonDocument doc; @@ -741,9 +807,12 @@ my_shadow.UpdateDeviceShadow(doc); rc = my_shadow.PerformUpdateAsync(); /* for a blocking model look at the Example of getting a shadow document in V1 */ + ``` +
-_Example of updating a shadow document in V2_ +
+Example of updating a shadow document in V2 ``` UpdateShadowRequest updateShadowRequest; @@ -788,6 +857,7 @@ shadowClient.PublishUpdateShadow( std::move(publishCompleted)); ``` +
See API documentation for V2 SDK [Device Shadow](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotshadow.html) service client for more details. Refer to the V2 SDK [Device Shadow](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/shadow) sample for code example. @@ -806,8 +876,8 @@ AWS IoT Core documentation for [Jobs](https://docs.aws.amazon.com/iot/latest/dev See API documentation for V2 SDK [Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html) service clients for more details. Refer to the V2 SDK [Jobs](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/jobs) samples for code examples. -_V1 example executing jobs_ - +
+V1 example executing jobs ``` ResponseCode GetPendingCallback( util::String topic_name, @@ -922,16 +992,17 @@ rc = p_jobs_->SendJobsQuery(Jobs::JOB_GET_PENDING_TOPIC); rc = p_jobs_->SendJobsQuery(Jobs::JOB_DESCRIBE_TOPIC, "$next"); ``` +
-_V2 example executig a job_ - +
+V2 example executig a job ``` IotJobsClient jobsClient(client); auto subscriptionHandler = [&](DescribeJobExecutionResponse *response, int ioErr) { }; auto subAckHandler = [&](int) - { }; +{ }; // Get information about the job DescribeJobExecutionSubscriptionRequest describeJobExecutionSubscriptionRequest; @@ -1018,6 +1089,7 @@ jobsClient.PublishUpdateJobExecution( publishHandler); ``` +
@@ -1038,7 +1110,7 @@ Refer to the V2 SDK [Fleet Provisioning](https://github.com/aws/aws-iot-device-s It’s always helpful to look at a working example to see how new functionality works, to be able to tweak different options, to compare with existing code. For that reasons, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) ([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp)) in V2 SDK similar to a sample provided by V1 SDK (see a corresponding [readme section](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/README.md) and [source code](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/PubSub/PubSub.cpp)). -## How to get help +## How to Get Help For any migration related questions or feedback, you can contact us at [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions) by submitting an issue with a label `label:migration`. @@ -1076,6 +1148,6 @@ You can specify the payload format (binary, text) and content type when a messag **Shared Subscriptions** Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. -Refer to [shared subscription](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/samples/Mqtt5/SharedSubscription/README.md) in V2 SDK. +Refer to [shared subscription](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in V2 SDK. **NOTE** AWS IoT Core provides this functionality for MQTT3 as well. From c7cfba7a26b5f71a05350c50616bf968773fc874 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 2 Feb 2024 18:49:51 -0800 Subject: [PATCH 03/33] Fix md extra characters --- documents/MIGRATION_GUIDE.md | 72 ++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index c20ba2d0e..a22bb01cb 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -34,7 +34,7 @@ The V2 AWS IoT SDK for C++ is a major rewrite of the V1 code base. It includes m * V2 SDK client is truly async. Operations take callback functions/lambdas, that is called when the operation is registered with the server Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved after the function call by calling `future.wait()` * V2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. -* Public API terminology has changed. You `S``tart()` or `S``top()` the MQTT5 client rather than `Connect` or `Disconnect` like in V1. This removes the semantic confusion with the connect/disconnect as the client-level controls vs. internal recurrent networking events. +* Public API terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` like in V1. This removes the semantic confusion with the connect/disconnect as the client-level controls vs. internal recurrent networking events. * Support for Fleet Provisioning AWS IoT Core service. Public API for almost all actions and operations has changed significantly. For more details about the new features and to see specific code examples, refer to the other sections of this guide. @@ -64,7 +64,7 @@ Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot h
Example of creating a client in V1 -``` +```cpp #include "OpenSSLConnection.hpp" util::String clientEndpoint = "-ats.iot..amazonaws.com"; @@ -90,7 +90,7 @@ ResponseCode rc = p_network_connection->Initialize(); V2 SDK supports different connection types. Given the same input parameters as in the V1 example above, the most suitable method to create an MQTT5 client will [beNewMqtt5ClientBuilderWithMtlsFromPath](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#ab595bbc50e08b9d2f78f62e9efeafd65). -``` +```cpp util::String clientEndpoint = "-ats.iot..amazonaws.com"; util::String certificateFile = ""; // X.509 based certificate file util::String privateKeyFile = ""; // PEM encoded private key file @@ -146,7 +146,7 @@ Refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2
Example of setting lifecycle events in V1 -``` +```cpp std::shared_ptr p_iot_client_; ResponseCode DisconnectCallback( util::String client_id, @@ -201,7 +201,7 @@ rc = p_iot_client_->Connect(/*...*/);
Example of setting lifecycle events in V2 -``` +```cpp builder->WithClientConnectionSuccessCallback( [&](const Mqtt5::OnConnectionSuccessEventData &eventData) { }); @@ -209,7 +209,7 @@ builder->WithClientConnectionFailureCallback([&]( const Mqtt5::OnConnectionFailureEventData &eventData) { }); builder->WithClientStoppedCallback([&]( - const Mqtt5::OnStoppedEventData & eventData) { }); + const Mqtt5::OnStoppedEventData &eventData) { }); builder->WithClientAttemptingConnectCallback([&]( OnAttemptingConnectEventData &eventData)) { }); @@ -235,7 +235,7 @@ If the operation fails for any reason before these respective completion events,
Example of publishing in V1 -``` +```cpp // Blocking API. std::chrono::milliseconds action_response_timeout = 20; bool is_retained = false; @@ -249,7 +249,7 @@ ResponseCode rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), action_response_timeout); ``` -``` +```cpp // Non-blocking API. std::chrono::milliseconds action_response_timeout = 20; bool is_retained = false; @@ -277,7 +277,7 @@ rc = p_iot_client_->PublishAsync(Utf8String::Create("my/topic"),
Example of publishing in V2 -``` +```cpp std::shared_ptr publish = std::make_shared( "my topic", @@ -304,7 +304,7 @@ In V2 SDK, if the MQTT5 client is going to subscribe and receive packets from th
Example of subscribing in V1 -``` +```cpp ResponseCode PubSub::SubscribeCallback( util::String topic_name, util::String payload, @@ -342,7 +342,7 @@ ResponseCode rc = p_iot_client_->Subscribe(topic_vector,
Example of subscribing in V2 -``` +```cpp builder->WithPublishReceivedCallback( [&](const Mqtt5::PublishReceivedEventData &eventData) { /*Called when a message is received by one of the active subscriptions.*/ @@ -378,7 +378,7 @@ Similar to subscribing, you can unsubscribe from multiple topics in one request:
Example of unsubscribing in V1 -``` +```cpp // Blocking API. std::chrono::milliseconds action_response_timeout = 20; std::unique_ptr p_topic_name = Utf8String::Create("my/topic"); @@ -389,7 +389,7 @@ ResponseCode rc = p_iot_client_->Unsubscribe(std::move(topic_vector), ``` -``` +```cpp // Non-blocking API. void unsubAck(uint16_t action_id, ResponseCode rc) { @@ -408,7 +408,7 @@ ResponseCode rc = p_iot_client_->UnsubscribeAsync(std::move(topic_vector),
Example of unsubscribing in V2 -``` +```cpp std::shared_ptr unsub = std::make_shared(); unsub->WithTopicFilter("my/topic"); @@ -430,7 +430,7 @@ In V2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.
Example of disconnecting a client in V1 -``` +```cpp std::chrono::milliseconds action_response_timeout = 20; client.Disconnect(action_response_timeout); @@ -439,7 +439,7 @@ client.Disconnect(action_response_timeout);
Example of disconnecting a client in V2 -``` +```cpp builder->WithClientStoppedCallback([](const Mqtt5::OnStoppedEventData &event) { /* on stop callback */ }); @@ -459,7 +459,7 @@ V2 attempts to reconnect automatically until connection succeeds or `client.stop
Example of tweaking reconnection settings in V1 -``` +```cpp std::chrono::seconds min_reconnect_backoff_timeout = 20; std::chrono::seconds max_reconnect_backoff_timeout = 30; client.SetMinReconnectBackoffTimeout(min_reconnect_backoff_timeout); @@ -471,7 +471,7 @@ client.SetMaxReconnectBackoffTimeout(max_reconnect_backoff_timeout);
Example of tweaking reconnection settings in V2 -``` +```cpp Aws::Crt::Mqtt5::ReconnectOptions reconnectOptions = { Mqtt5::JitterMode::AWS_EXPONENTIAL_BACKOFF_JITTER_FULL, // reconnect mode 1000, // min reconnect delay ms @@ -494,7 +494,7 @@ V2 provides a way to configure which kind of packets will be placed into the off
Example of configuring the offline queue in V2 -``` +```cpp AwsIotMqtt5ClientBuilder builder; std::shared_ptrbuilder( Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(/* ... */)); @@ -509,7 +509,7 @@ Note that AWS IoT Core [limits the number of allowed operations per second](http The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. Example of getting operation statistics -``` +```cpp Mqtt5::Mqtt5ClientOperationStatistics statistics = mqtt5Client->GetOperationStatistics(); std::cout<<"Client operations queue statistics\n" @@ -535,7 +535,7 @@ The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/c
Example of timeouts in V1 -``` +```cpp std::chrono::milliseconds connectTimeout = 200; std::chrono::seconds keepAliveTimeout = 200; @@ -565,7 +565,7 @@ rc = p_iot_client_->Publish(Utf8String::Create("my/topic"),
Example of timeouts in V2 -``` +```cpp builder.WithAckTimeoutSeconds(10); Mqtt5Client client = builder->Build(); @@ -581,7 +581,7 @@ V1 and V2 SDK uses a custom logger allowing to control the logging process simul Example of enabling logging in V1 To enable logging on V1 follow the next example: -``` +```cpp #include "util/logging/Logging.hpp" #include "util/logging/LogMacros.hpp" #include "util/logging/ConsoleLogSystem.hpp" @@ -601,7 +601,7 @@ AWS_LOG_INFO(INTEG_TEST_RUNNER_LOG_TAG, Example of enabling logging in V2 You can enable logging by passing the folowing properties: -``` +```cpp ApiHandle apiHandle; apiHandle.InitializeLogging(Aws::Crt::LogLevel::Info, @@ -617,7 +617,7 @@ AWS_LOGF_ERROR("log location", "Invalid operation");
Example of shutting down logging -``` +```cpp awsiotsdk::util::Logging::ShutdownAWSLogging(); ``` @@ -630,14 +630,14 @@ In V2 logging is shutdown automatically with ApiHandle destruction when it goes V1 SDK is built with [AWS IoT device shadow support](http://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-shadows.html), providing access to thing shadows (sometimes referred to as device shadows). It also supports a simplified shadow access model, which allows developers to exchange data with their shadows by just using getter and setter methods without having to serialize or deserialize any JSON documents. V2 SDK supports device shadow service as well, but with completely different API. -First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. For example, `SubscribeToGetShadow``Accepted` subscribes to a topic to which AWS IoT Core will publish a shadow document; and via the `SubscribeToGetShadowRejected` the server will notify you if it cannot send you a requested document. +First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. For example, `SubscribeToGetShadowAccepted` subscribes to a topic to which AWS IoT Core will publish a shadow document; and via the `SubscribeToGetShadowRejected` the server will notify you if it cannot send you a requested document. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. For example, `PublishGetShadow` sends a request to AWS IoT Core to get a shadow document. The requested Shadow document will be received in a callback specified in the `SubscribeToGetShadowAccepted` call. AWS IoT Core [documentation for Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) service provides detailed descriptions for the topics used to interact with the service.
Example of creating a Device Shadow service client in V1 -``` +```cpp #include "shadow/Shadow.hpp" // Blocking and non-blocking API. String thingName = ""; @@ -659,7 +659,7 @@ Shadow shadowClient( ``` -``` +```cpp // Simplified shadow Access Model. ResponseCode ShadowDelta::ActionResponseHandler( util::String thing_name, @@ -690,7 +690,7 @@ my_shadow.AddShadowSubscription(request_mapping); Example of creating a Device Shadow service client in V2 A thing name in V2 SDK shadow client is specified for the operations with shadow documents. -``` +```cpp #include #include #include @@ -713,7 +713,7 @@ Aws::Iotshadow::IotShadowClient shadowClient(client);
Example of getting a shadow document in V1 -``` +```cpp // Blockig API. std::condition_variable sync_action_response_wait_; ResponseCode ShadowDelta::ActionResponseHandler( @@ -742,7 +742,7 @@ std::unique_lock block_handler_lock(sync_action_response_lock_); ``` -``` +```cpp // Non-blocking API. ResponseCode rc = my_shadow.performGetAsync(); util::JsonDocumen doc = my_shadow.GetServerDocument(); @@ -753,7 +753,7 @@ std::unique_lock block_handler_lock(sync_action_response_lock_);
Example of getting a shadow document in V2 -``` +```cpp GetShadowSubscriptionRequest shadowSubscriptionRequest; shadowSubscriptionRequest.ThingName = ""; @@ -797,7 +797,7 @@ shadowClient.PublishGetShadow(
Example of updating a shadow document in V1 -``` +```cpp // Non-blocking API. util::JsonDocument doc; util::JsonParser::InitializeFromJsonString( @@ -814,7 +814,7 @@ rc = my_shadow.PerformUpdateAsync();
Example of updating a shadow document in V2 -``` +```cpp UpdateShadowRequest updateShadowRequest; updateShadowRequest.ClientToken = uuid.ToString(); updateShadowRequest.ThingName = "; @@ -878,7 +878,7 @@ Refer to the V2 SDK [Jobs](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree
V1 example executing jobs -``` +```cpp ResponseCode GetPendingCallback( util::String topic_name, util::String payload, @@ -996,7 +996,7 @@ rc = p_jobs_->SendJobsQuery(Jobs::JOB_DESCRIBE_TOPIC, "$next");
V2 example executig a job -``` +```cpp IotJobsClient jobsClient(client); auto subscriptionHandler = [&](DescribeJobExecutionResponse *response, int ioErr) From 75488c9c94f0acf27c6a4b33f9d77f611a168052 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 2 Feb 2024 19:03:33 -0800 Subject: [PATCH 04/33] Fix formatting --- documents/MIGRATION_GUIDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index a22bb01cb..58e130bb6 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -109,7 +109,7 @@ builder->WithConnectOptions(connectOptions); builder->WithPort(clientPort); std::shared_ptr client = builder->Build(); ``` -
+
Refer to the [Connection Types and Features](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR0b9b69e08b72487dbe620342f) section for other connection types supported by V2 SDK. @@ -364,6 +364,7 @@ auto onSubAck = [&](int error_code, bool rc = client->Subscribe(subPacket, onSubAck); ``` +
@@ -577,7 +578,7 @@ Mqtt5Client client = builder->Build(); V1 and V2 SDK uses a custom logger allowing to control the logging process simultaneously for all layers of the SDK. -
+
Example of enabling logging in V1 To enable logging on V1 follow the next example: @@ -635,7 +636,7 @@ After subscribing to all the required topics, the service client can start inter AWS IoT Core [documentation for Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) service provides detailed descriptions for the topics used to interact with the service. -
+
Example of creating a Device Shadow service client in V1 ```cpp #include "shadow/Shadow.hpp" From 3687c12afafad4764b421577d514ecc32d375a06 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:10:34 -0800 Subject: [PATCH 05/33] fix local references --- documents/MIGRATION_GUIDE.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 58e130bb6..bf0c3b455 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -111,7 +111,7 @@ std::shared_ptr client = builder->Build(); ```
-Refer to the [Connection Types and Features](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR0b9b69e08b72487dbe620342f) section for other connection types supported by V2 SDK. +Refer to the [Connection Types and Features](#connection-types-and-features) section for other connection types supported by V2 SDK. ### Connection Types and Features @@ -139,14 +139,17 @@ ${\Large\color{orange}✔\*\*}$ - Though V1 does not allow to specify HTTP p Both V1 and V2 SDKs provide lifecycle events for the MQTT clients. -V1 SDK provides 3 lifecycle events: “ClientCoreState::ApplicationResubscribeCallbackPt”, “ClientCoreState::ApplicationDisconnectCallbackPtr”, and “ClientCoreState::ApplicationReconnectCallbackPtr”. You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. +V1 SDK provides 3 lifecycle events: “ClientCoreState::ApplicationResubscribeCallbackPt”, “ClientCoreState::ApplicationDisconnectCallbackPtr”, and “ClientCoreState::ApplicationReconnectCallbackPtr”. +You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. V2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: “WithClientConnectionSuccessCallback”, “WithClientConnectionFailureCallback”, “WithClientDisconnectionCallback”, “WithClientStoppedCallback”, and “WithClientAttemptingConnectCallback”. Refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management) for the details.
Example of setting lifecycle events in V1 + ```cpp + std::shared_ptr p_iot_client_; ResponseCode DisconnectCallback( util::String client_id, @@ -870,7 +873,7 @@ V1 and V2 SDK offer support of AWS IoT Core services implementing a service clie V1 IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) -The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR759cb689cfb8488da0d1d539f). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. +The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. AWS IoT Core documentation for [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html) service provides detailed descriptions for the topics used to interact with the service. @@ -1098,7 +1101,7 @@ jobsClient.PublishUpdateJobExecution( Another IoT service that V2 SDK provides access to is [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) (also known as Identity Service). By using AWS IoT fleet provisioning, AWS IoT can generate and securely deliver device certificates and private keys to your devices when they connect to AWS IoT for the first time. -The Fleet Provisioning service client provides API similar to API provided by [Client for Device Shadow Service](https://quip-amazon.com/bbcuA13anxJa#temp:C:YWR759cb689cfb8488da0d1d539f). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. +The Fleet Provisioning service client provides API similar to API provided by [Client for Device Shadow Service](#client for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. AWS IoT Core documentation for [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/fleet-provision-api.html) service provides detailed descriptions for the topics used to interact with the service. From 499d2a69e87af13bbcf1facf845ab021df33ca92 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:22:25 -0800 Subject: [PATCH 06/33] Fix code snippet --- documents/MIGRATION_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index bf0c3b455..5e9304737 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -96,7 +96,7 @@ util::String certificateFile = ""; // X.509 based certificate util::String privateKeyFile = ""; // PEM encoded private key file uint32_t clientPort = -std::shared_ptrbuilder( +std::shared_ptr builder( Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath( clientEndpoint, certificateFie, @@ -500,7 +500,7 @@ V2 provides a way to configure which kind of packets will be placed into the off ```cpp AwsIotMqtt5ClientBuilder builder; -std::shared_ptrbuilder( +std::shared_ptr builder( Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(/* ... */)); builder.WithOfflineQueueBehavior( Mqtt5::ClientOperationQueueBehaviorType:: From a2c2314c8d81d486d0c54c4e50771ed717e86740 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:24:22 -0800 Subject: [PATCH 07/33] remove unique from code --- documents/MIGRATION_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 5e9304737..4a64ac092 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -69,7 +69,7 @@ Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot h util::String clientEndpoint = "-ats.iot..amazonaws.com"; uint16_t clientPort = - util::String clientId = ""; + util::String clientId = ""; util::String rootCaPath = ""; util::String certificateFile = ""; // X.509 based certificate file util::String privateKeyFile = ""; // PEM encoded private key file @@ -103,7 +103,7 @@ std::shared_ptr builder( privateKeyFile)); std::shared_ptr connectOptions = std::make_shared(); -util::String clientId = ""; +util::String clientId = ""; connectOptions->WithClientId(clientId); builder->WithConnectOptions(connectOptions); builder->WithPort(clientPort); From 1f6cd444aa4320404dec5df899228c05078f1f68 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:26:21 -0800 Subject: [PATCH 08/33] client id as parameter --- documents/MIGRATION_GUIDE.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 4a64ac092..401b3e5f5 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -67,9 +67,11 @@ Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot h ```cpp #include "OpenSSLConnection.hpp" - util::String clientEndpoint = "-ats.iot..amazonaws.com"; +String client_id = "unique client id"; + +util::String clientEndpoint = "-ats.iot..amazonaws.com"; uint16_t clientPort = - util::String clientId = ""; + util::String clientId = client_id; util::String rootCaPath = ""; util::String certificateFile = ""; // X.509 based certificate file util::String privateKeyFile = ""; // PEM encoded private key file @@ -95,6 +97,7 @@ util::String clientEndpoint = "-ats.iot..amazonaws.com"; util::String certificateFile = ""; // X.509 based certificate file util::String privateKeyFile = ""; // PEM encoded private key file uint32_t clientPort = +String client_id = "unique client id"; std::shared_ptr builder( Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath( @@ -103,7 +106,7 @@ std::shared_ptr builder( privateKeyFile)); std::shared_ptr connectOptions = std::make_shared(); -util::String clientId = ""; +util::String clientId = client_id; connectOptions->WithClientId(clientId); builder->WithConnectOptions(connectOptions); builder->WithPort(clientPort); From b9add39b34a8034cc5b8fe820cd4fdbc4fe81e8b Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:47:31 -0800 Subject: [PATCH 09/33] fix variables --- documents/MIGRATION_GUIDE.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 401b3e5f5..98dd8904f 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -67,14 +67,11 @@ Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot h ```cpp #include "OpenSSLConnection.hpp" -String client_id = "unique client id"; - util::String clientEndpoint = "-ats.iot..amazonaws.com"; uint16_t clientPort = - util::String clientId = client_id; - util::String rootCaPath = ""; - util::String certificateFile = ""; // X.509 based certificate file - util::String privateKeyFile = ""; // PEM encoded private key file +util::String rootCaPath = ""; +util::String certificateFile = ""; // X.509 based certificate file +util::String privateKeyFile = ""; // PEM encoded private key file std::shared_ptr p_network_connection = std::make_shared( @@ -84,6 +81,7 @@ uint16_t clientPort = certificateFile, privateKeyFile); ResponseCode rc = p_network_connection->Initialize(); + ```
@@ -106,11 +104,12 @@ std::shared_ptr builder( privateKeyFile)); std::shared_ptr connectOptions = std::make_shared(); -util::String clientId = client_id; +util::String clientId = "client_id"; connectOptions->WithClientId(clientId); builder->WithConnectOptions(connectOptions); builder->WithPort(clientPort); std::shared_ptr client = builder->Build(); + ```
From a20ea2d88fa781846fefaa690f90121b6ec5c13b Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:50:21 -0800 Subject: [PATCH 10/33] Fix --- documents/MIGRATION_GUIDE.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 98dd8904f..8916ed167 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -98,10 +98,7 @@ uint32_t clientPort = String client_id = "unique client id"; std::shared_ptr builder( - Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath( - clientEndpoint, - certificateFie, - privateKeyFile)); + Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(clientEndpoint, certificateFie, privateKeyFile)); std::shared_ptr connectOptions = std::make_shared(); util::String clientId = "client_id"; From 369c701952f5fd7630e7ed69105e8f8c601599b7 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 10:53:13 -0800 Subject: [PATCH 11/33] Fix --- documents/MIGRATION_GUIDE.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 8916ed167..2f55485dc 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -97,10 +97,8 @@ util::String privateKeyFile = ""; // PEM encoded private key uint32_t clientPort = String client_id = "unique client id"; -std::shared_ptr builder( - Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(clientEndpoint, certificateFie, privateKeyFile)); -std::shared_ptr connectOptions = - std::make_shared(); +std::shared_ptr builder(Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(clientEndpoint, certificateFile, privateKeyFile)); +std::shared_ptr connectOptions = std::make_shared(); util::String clientId = "client_id"; connectOptions->WithClientId(clientId); builder->WithConnectOptions(connectOptions); From 7f2b78764a6b0775f808ff68d47bea0b9739e92b Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Sat, 3 Feb 2024 11:00:27 -0800 Subject: [PATCH 12/33] remove new lines from code snippet --- documents/MIGRATION_GUIDE.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 2f55485dc..7fd03f554 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -73,13 +73,7 @@ util::String rootCaPath = ""; util::String certificateFile = ""; // X.509 based certificate file util::String privateKeyFile = ""; // PEM encoded private key file - std::shared_ptr p_network_connection = - std::make_shared( - clientEndpoint, - clientPort, - rootCaPath, - certificateFile, - privateKeyFile); +std::shared_ptr p_network_connection = std::make_shared( clientEndpoint, clientPort, rootCaPath, certificateFile, privateKeyFile); ResponseCode rc = p_network_connection->Initialize(); ``` From fd5cd1d4cdf292ed4f7c0b082e5aaa85cfede4ba Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Wed, 7 Feb 2024 20:58:56 -0800 Subject: [PATCH 13/33] Apply reviews --- documents/MIGRATION_GUIDE.md | 532 ++++++++++++++++++++--------------- 1 file changed, 303 insertions(+), 229 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 7fd03f554..cb387fc0b 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -1,68 +1,80 @@ -# Migrate from V1 to V2 of the AWS IoT SDK for C++ - -> [!TIP] -> If you can't find necessary information in this guide, the [How to Get Help](#how-to-get-help) section will guide you. - -* [What’s New in V2 SDK](#whats-new-in-v2-sdk) -* [How to Get Started with V2 SDK](#how-to-get-started-with-v2-sdk) - * [MQTT Protocol](#mqtt-protocol) - * [Client Builder](#client-builder) - * [Connection Types and Features](#connection-types-and-features) - * [Lifecycle Events](#lifecycle-events) +# Migrate from v1 to v2 of the AWS IoT SDK for C++ + +The AWS IoT Devide SDK for C++ v2 is a major rewrite of the v1 SDK code base. +It includes many updates, such as improved consistency, ease of use, more detailed information about client status, +an offline operation queue control. This guide describes the major features that are new in the v2 SDK, +and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot SDK for C++. + +> [!NOTE] +> If you can't find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for +> more help and guidance + +* [What's new in AWS IoT Device SDK for C++ v2](#what's-new-in-aws-iot-device-sdk-for-c++-v2) +* [How to get started with the v2 sdk for C++](#how-to-get-started-with-the-v2-sdk-for-c++) + * [Mqtt protocol](#mqtt-protocol) + * [client builder](#client-builder) + * [Connection types and features](#connection-types-and-features) + * [Lifecycle events](#lifecycle-events) * [Publish](#publish) * [Subscribe](#subscribe) * [Unsubscribe](#unsubscribe) - * [Client Stop](#client-stop) + * [Client stop](#client-stop) * [Reconnects](#reconnects) - * [Offline Operations Queue](#offline-operations-queue) - * [Operation Timeouts](#operation-timeouts) + * [Offline operations queue](#offline-operations-queue) + * [Operation timeouts](#operation-timeouts) * [Logging](#logging) - * [Client for Device Shadow Service](#client-for-device-shadow-service) - * [Client for Jobs Service](#client-for-jobs-service) - * [Client for Fleet Provisioning Service](#client-for-fleet-provisioning-service) + * [Client for AWS IOT Device Shadow](#client-for-aws-iot-device-shadow) + * [Client for AWS_IOT Jobs](#client-for-aws-iot-jobs) + * [Client for AWS IOT fleet provisioning](#client-for-aws-iot-fleet-provisioning) * [Example](#example) -* [How to Get Help](#how-to-get-help) +* [How to get help](#how-to-get-help) * [Appendix](#appendix) - * [MQTT5 Features](#mqtt5-features) - + * [Mqtt5 features](#mqtt5-features) -The V2 AWS IoT SDK for C++ is a major rewrite of the V1 code base. It includes many updates, such as improved consistency, ease of use, more detailed information about client status, an offline operation queue control, etc. This guide describes the major features that are new in V2, and provides guidance on how to migrate your code to V2 from V1. +## What's new in AWS IoT Device SDK for C++ v2 -## What’s new in V2 SDK +* The v2 SDK client is truly async. Operations take callback functions/lambdas, that is called-back when the operation is registered with the server. + Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` +* The v2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. +* Public APIs terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` as in the V1 SDK. +This removes the semantic confusion with the client-level controls and internal recurrent networking events related to +connection and disconnection. +* The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. -* V2 SDK client is truly async. Operations take callback functions/lambdas, that is called when the operation is registered with the server - Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved after the function call by calling `future.wait()` -* V2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. -* Public API terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` like in V1. This removes the semantic confusion with the connect/disconnect as the client-level controls vs. internal recurrent networking events. -* Support for Fleet Provisioning AWS IoT Core service. +Public APIs for almost all actions and operations has changed significantly. +For more information about the new features and specific code examples, refer to the [how to get started with the v2 sdk for c++](#how-to-get-started-with-the-v2-sdk-for-c++) sections of this guide. -Public API for almost all actions and operations has changed significantly. For more details about the new features and to see specific code examples, refer to the other sections of this guide. +## How To Get Started with the the v2 SDK for C++ -## How To Get Started with V2 SDK - -There are differences between IoT C++ V1 SDK and IoT C++ V2 SDK. Below are changes you need to make to use IoT C++ V2 SDK features. For more information about MQTT5, visit [MQTT5 User Guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md). +There are differences between the v1 SDK and the v2 SDK. This section describes the changes you need to apply to your +project with the v1 SDK to start using the v1 SDK. +For more information about MQTT5, visit [MQTT5 User Guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md). ### MQTT Protocol -V1 SDK uses an MQTT version 3.1.1 client under the hood. +The v1 SDK uses an MQTT version 3.1.1 client under the hood. -V2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementations. This guide focuses on the MQTT5 since this version is significant improvement over MQTT3. See MQTT5 features section. +The v2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementations. This guide focuses on the MQTT5 because this version is significant improvement over MQTT3. +For more information see the [MQTT5 features]($mqtt5-features) section. ### Client Builder To access the AWS IoT service, you must initialize an MQTT client. -In V1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html) class represents an MQTT client. You instantiate the client directly passing all the required parameters to the class constructor. It’s possible to change client settings after its creation using `set*` methods, e.g. `SetAutoReconnectEnabled` or `SetMaxReconnectBackoffTimeout`. +In the v1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html) class represents an MQTT client. +You instantiate the client directly passing all the required parameters to the class constructor. +It’s possible to change client settings after its creation using `set*` methods, e.g. `SetAutoReconnectEnabled` or `SetMaxReconnectBackoffTimeout`. -In V2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) class represents an MQTT client, specifically MQTT5 protocol. V2 SDK provides an [Aws::Iot::Mqtt5ClientBuilder](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html) designed to easily create common configuration types such as direct MQTT or WebSocket connections. -Once an MQTT5 client is built and finalized, the resulting MQTT5 client cannot have its settings modified. +In the v2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) class represents an MQTT client, specifically MQTT5 protocol. +The v2 SDK provides an [Aws::Iot::Mqtt5ClientBuilder](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html) +designed to easily create common configuration types such as direct MQTT or WebSocket connections. +After an MQTT5 client is built and finalized, the setting of the resulting MQTT5 client cannot be modified. -
-Example of creating a client in V1 +#### Example of creating a client in the v1 SDK ```cpp #include "OpenSSLConnection.hpp" @@ -77,12 +89,11 @@ std::shared_ptr p_network_connection = std::make_sha ResponseCode rc = p_network_connection->Initialize(); ``` -
-
-Example of creating a client in V2 +#### Example of creating a client in the v2 SDK -V2 SDK supports different connection types. Given the same input parameters as in the V1 example above, the most suitable method to create an MQTT5 client will [beNewMqtt5ClientBuilderWithMtlsFromPath](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#ab595bbc50e08b9d2f78f62e9efeafd65). +The v2 SDK supports different connection types. Given the same input parameters as in the v1 example above, +the most recommended method to create an MQTT5 client will be [NewMqtt5ClientBuilderWithMtlsFromPath](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#ab595bbc50e08b9d2f78f62e9efeafd65). ```cpp util::String clientEndpoint = "-ats.iot..amazonaws.com"; @@ -100,47 +111,52 @@ builder->WithPort(clientPort); std::shared_ptr client = builder->Build(); ``` -
-Refer to the [Connection Types and Features](#connection-types-and-features) section for other connection types supported by V2 SDK. +For more information, refer to the [Connection Types and Features](#connection-types-and-features) section for other connection types supported by the v2 SDK. ### Connection Types and Features -V1 SDK supports two types of connections to connect to the AWS IoT service: MQTT with X.509 certificate and MQTT over Secure WebSocket with SigV4 authentication. +The v1 SDK supports two types of connections to connect to the AWS IoT service: MQTT with X.509 certificate and MQTT over Secure WebSocket with SigV4 authentication. + +The v2 SDK adds a collection of connection types and cryptography formats (e.g. [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) and +[Custom Authorizer](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html)), +credential providers (e.g. [Amazon Cognito](https://aws.amazon.com/cognito/) and +[Windows Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores)), and other connection-related features. -V2 SDK adds a collection of connection types and cryptography formats (e.g. [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) and [Custom Authorizer](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html)), credential providers (e.g. [Amazon Cognito](https://aws.amazon.com/cognito/) and [Windows Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores)), and other connection-related features. -Refer to the “[Connecting To AWS IoT Core](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#connecting-to-aws-iot-core)” section of the MQTT5 user guide for detailed information and code snippets on each connection type and connection feature. +For more information, refer to the [Connecting To AWS IoT Core](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#connecting-to-aws-iot-core) +section of the MQTT5 user guide for detailed information and code snippets on each connection type and connection feature. -| Connection Type/Feature | V1 SDK | V2 SDK | User guide | +| Connection type/feature | v1 SDK | v2 SDK | User guide | |----------------------------------------------------------|-----------------------------------------|----------------------------------|:----------:| | MQTT over Secure WebSocket with AWS SigV4 authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-sigv4-authentication) | +| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | | MQTT with X.509 certificate based mutual authentication | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-x509-based-mutual-tls) | | MQTT with PKCS12 Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs12-method) | | MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authorizer-method) | | MQTT with Windows Certificate Store Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-windows-certificate-store-method) | | MQTT with PKCS11 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs11-method) | -| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | | HTTP Proxy | $${\Large\color{orange}✔\*\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#adding-an-http-proxy) | -${\Large\color{orange}✔\*}$ - In order to get this connection type work in V1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ -${\Large\color{orange}✔\*\*}$ - Though V1 does not allow to specify HTTP proxy, it is possible to configure systemwide proxy. +${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ +${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP proxy, but sustemwide proxy ### Lifecycle Events -Both V1 and V2 SDKs provide lifecycle events for the MQTT clients. +Both v1 and v2 SDKs provide lifecycle events for the MQTT clients. -V1 SDK provides 3 lifecycle events: “ClientCoreState::ApplicationResubscribeCallbackPt”, “ClientCoreState::ApplicationDisconnectCallbackPtr”, and “ClientCoreState::ApplicationReconnectCallbackPtr”. -You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. +The v1 SDK provides 3 lifecycle events: *ClientCoreState::ApplicationResubscribeCallbackPt*, *ClientCoreState::ApplicationDisconnectCallbackPtr*, and *ClientCoreState::ApplicationReconnectCallbackPtr*. +You can supply a custom callback function via the function `Create`. +It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. -V2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: “WithClientConnectionSuccessCallback”, “WithClientConnectionFailureCallback”, “WithClientDisconnectionCallback”, “WithClientStoppedCallback”, and “WithClientAttemptingConnectCallback”. -Refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management) for the details. +The v2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: *WithClientConnectionSuccessCallback*, +*WithClientConnectionFailureCallback*, *WithClientDisconnectionCallback*, *WithClientStoppedCallback*, and *WithClientAttemptingConnectCallback*. -
-Example of setting lifecycle events in V1 +For more information, refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management). -```cpp +#### Example of setting lifecycle events in the v1 SDK +```cpp std::shared_ptr p_iot_client_; ResponseCode DisconnectCallback( util::String client_id, @@ -191,44 +207,60 @@ p_iot_client_ = std::shared_ptr( rc = p_iot_client_->Connect(/*...*/); ``` -
-
-Example of setting lifecycle events in V2 +#### Example of setting lifecycle events in the v2 SDK + ```cpp builder->WithClientConnectionSuccessCallback( - [&](const Mqtt5::OnConnectionSuccessEventData &eventData) { }); + [&](const Mqtt5::OnConnectionSuccessEventData &eventData) { + /* Connection success event received */ + }); builder->WithClientConnectionFailureCallback([&]( - const Mqtt5::OnConnectionFailureEventData &eventData) { }); + const Mqtt5::OnConnectionFailureEventData &eventData) { + /* Connection failure event received */ + }); builder->WithClientStoppedCallback([&]( - const Mqtt5::OnStoppedEventData &eventData) { }); + const Mqtt5::OnStoppedEventData &eventData) { + /* On stopped event received */ + }); builder->WithClientAttemptingConnectCallback([&]( - OnAttemptingConnectEventData &eventData)) { }); + OnAttemptingConnectEventData &eventData)) { + /* Connection attempt event received */ + }); builder->WithClientDisconnectionCallback([&]( - OnDisconnectionEventData &eventData) { }); + OnDisconnectionEventData &eventData) { + /* Disconnection event received */ + }); std::shared_ptr client = builder->Build(); ``` -
### Publish -V1 SDK provides two API calls for publishing: blocking and non-blocking. For the non-blocking version, the result of the publish operation is reported via a set of callbacks. If you try to publish to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. +The v1 SDK provides two API calls for publishing: blocking and non-blocking. For the non-blocking version, the result of the publish operation is reported via a set of callbacks. +If you try to publish to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. + +The v2 SDK provides only asynchronous non-blocking API. A [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) +object containing a description of the PUBLISH packet. +The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation +takes a `PublishPacket` instance and a [Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) +that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) in its parameter that will +contain different data depending on the `QoS` used in the publish. -V2 SDK provides only asynchronous non-blocking API. A [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) object containing a description of the PUBLISH packet. The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation takes a `PublishPacket` instance and a [Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) in its parameter that will contain different data depending on the `QoS` used in the publish. +* For QoS 0 (AT\_MOST\_ONCE): Calling `getValue` will return `null` and the promise will be complete as soon as the packet has been written to the socket. +* For QoS 1 (AT\_LEAST\_ONCE): Calling `getValue` will return a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) and the promise will be complete as soon as the PUBACK is received from the broker. -* For QoS 0 (AT_MOST_ONCE): Calling `getValue` will return `null` and the promise will be complete as soon as the packet has been written to the socket. -* For QoS 1 (AT_LEAST_ONCE): Calling `getValue` will return a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) and the promise will be complete as soon as the PUBACK is received from the broker. +If the operation fails for any reason before these respective completion events, the promise is rejected with a descriptive error. +You should always check the reason code of a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) +completion to determine if a QoS 1 publish operation actually succeeded. -If the operation fails for any reason before these respective completion events, the promise is rejected with a descriptive error. You should always check the reason code of a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) completion to determine if a QoS 1 publish operation actually succeeded. +#### Example of publishing in the v1 SDK -
-Example of publishing in V1 ```cpp // Blocking API. std::chrono::milliseconds action_response_timeout = 20; @@ -267,10 +299,9 @@ rc = p_iot_client_->PublishAsync(Utf8String::Create("my/topic"), p_async_ack_handler, packet_id); ``` -
-
-Example of publishing in V2 +#### Example of publishing in the v2 SDK + ```cpp std::shared_ptr publish = std::make_shared( @@ -285,18 +316,27 @@ auto onPublishComplete = bool rc = client->Publish(publish, onPublishComplete); ``` -
### Subscribe -V1 provides blocking and non-blocking API for subscribing. To subscribe to topic in V1, you should provide an instance of [awsiotsdk::mqtt::Subscription](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1mqtt_1_1_subscription.html) to the [subscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a9702f18a7d663aae5b76bae70d3999c7) operation. awsiotsdk::mqtt::Subscription object (or, usually, an object of a children class) implements `ApplicationCallbackHandlerPtr` method which will be called on receiving a new message. If you try to subscribe to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. +The v1 SDK provides blocking and non-blocking API for subscribing. +To subscribe to a topic in the v1 SDK, you should provide an instance of [awsiotsdk::mqtt::Subscription](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1mqtt_1_1_subscription.html) +to the [subscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a9702f18a7d663aae5b76bae70d3999c7) operation. +awsiotsdk::mqtt::Subscription object (or, usually, an object of a children class) implements `ApplicationCallbackHandlerPtr` method which will be called on receiving a new message. +If you try to subscribe to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. -V2 SDK provides only asynchronous non-blocking API. First, you need to create a [SubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_subscribe_packet.html) object. If you specify multiple topics in the WithSubscription member function, V2 SDK will subscribe to all of these topics using one request. The [Subscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa6c3bfc3cbd99b17957148ac1e8c34c4) operation takes a description of the `SubscribePacket` you wish to send and sends back a callback that resolves with success or failure with the corresponding [SubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_sub_ack_packet.html) returned by the broker; You should always check the reason codes of a `SubAckPacket` completion to determine if the subscribe operation actually succeeded. +The v2 SDK provides only asynchronous non-blocking API. First, you need to create a [SubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_subscribe_packet.html) object. +If you specify multiple topics in the WithSubscription member function, the v2 SDK will subscribe to all of these topics using one request. +The [Subscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa6c3bfc3cbd99b17957148ac1e8c34c4) operation takes +a description of the `SubscribePacket` you wish to send and sends back a callback that resolves with success or failure with the corresponding [SubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_sub_ack_packet.html) returned by the broker; +You should always check the reason codes of a `SubAckPacket` completion to determine if the subscribe operation actually succeeded. -In V2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, it is important to also setup the `builder.WithPublishReceivedCallback` callback. This callback is invoked whenever the client receives a message from the server on a topic the client is subscribed to. With this callback, you can process messages made to subscribed topics. +In V2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, +it is important to also setup the `builder.WithPublishReceivedCallback` callback. +This callback is invoked whenever the client receives a message from the server on a topic the client is subscribed to. +With this callback, you can process messages made to subscribed topics. -
-Example of subscribing in V1 +#### Example of subscribing in the v1 SDK ```cpp ResponseCode PubSub::SubscribeCallback( @@ -332,10 +372,9 @@ ResponseCode rc = p_iot_client_->Subscribe(topic_vector, action_response_timeout); ``` -
-
-Example of subscribing in V2 +#### Example of subscribing in the v2 SDK + ```cpp builder->WithPublishReceivedCallback( [&](const Mqtt5::PublishReceivedEventData &eventData) { @@ -358,20 +397,27 @@ auto onSubAck = [&](int error_code, bool rc = client->Subscribe(subPacket, onSubAck); ``` -
- - ### Unsubscribe -V1 SDK provides blocking and non-blocking API for unsubscribing. To unsubscribe from topic in V1, you should provide a `std::vector` of `std::unique_ptr` of `Utf8String` to the [Unsubscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a8dc5fa8e8c1522219e6df33cbaa7e376) operation. +the v1 SDK provides blocking and non-blocking API for unsubscribing. To unsubscribe from a topic in the v1 SDK, +you should provide a `std::vector` of `std::unique_ptr` of `Utf8String` to the [Unsubscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a8dc5fa8e8c1522219e6df33cbaa7e376) operation. For asynchronous operations use [UnsubscribeAsync](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a4577dd3e720dea692755c640d4c638ed) success and failure results are sent through the callback [ActionData::AsyncAckNotificationHandlerPtr](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_action_data.html#a5d1d7452e081205b414e4df985d82f60) +`unsubscribeAsync` takes a callback argument or type `ActionData::AsyncAckNotificationHandlerPtr`, that will be called when the operation fails or succeeds. -V2 SDK provides only asynchronous non-blocking API. First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) object. The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) operation takes a description of the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) you wish to send and returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) returned by the broker; the promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) is received. You should always check the reason codes of a [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) completion to determine if the unsubscribe operation actually succeeded. -Similar to subscribing, you can unsubscribe from multiple topics in one request: just call [WithTopicFilter](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html#a822c4f630d69ce3d1ba6ce8db021ab2a) for each topic you wish to unsubscribe from. -
-Example of unsubscribing in V1 +the v2 SDK provides only asynchronous non-blocking API. First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) object. +The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) operation takes a description of +the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) you wish to send and +returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) +returned by the broker; the promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) +is received. You should always check the reason codes of a [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) +completion to determine if the unsubscribe operation actually succeeded. + +Similar to subscribing, you can unsubscribe from multiple topics in one request by just calling [WithTopicFilter](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html#a822c4f630d69ce3d1ba6ce8db021ab2a) +for each topic you wish to unsubscribe from. + +#### Example of unsubscribing in the v1 SDK ```cpp // Blocking API. @@ -399,10 +445,9 @@ ResponseCode rc = p_iot_client_->UnsubscribeAsync(std::move(topic_vector), unsubAck, packet_id); ``` -
-
-Example of unsubscribing in V2 +#### Example of unsubscribing in the v2 SDK + ```cpp std::shared_ptr unsub = std::make_shared(); @@ -413,27 +458,25 @@ auto unsubAck = [&](int, std::shared_ptr) { bool rc = client->Unsubscribe(unsub, unsubAck); ``` -
- ### Client Stop -In V1 SDK, the `disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `connect`. +In the v1 SDK, the `disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `connect`. -In V2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#abc503d1a67c4e1c232f8f722b3c59ca0) method. You can provide an optional [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) parameter. A closed client can be started again by calling [Start](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a9035534fc7cc8b48097518409e9c5a6b). +In V2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#abc503d1a67c4e1c232f8f722b3c59ca0) +method. You can provide an optional [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) +parameter. A closed client can be started again by calling [Start](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a9035534fc7cc8b48097518409e9c5a6b). -
-Example of disconnecting a client in V1 +#### Example of disconnecting a client in the v1 SDK ```cpp std::chrono::milliseconds action_response_timeout = 20; client.Disconnect(action_response_timeout); ``` -
-
-Example of disconnecting a client in V2 +#### Example of disconnecting a client in the v2 SDK + ```cpp builder->WithClientStoppedCallback([](const Mqtt5::OnStoppedEventData &event) { /* on stop callback */ @@ -442,18 +485,17 @@ Mqtt5Client client = builder->Build(); client->Stop(); ``` -
- ### Reconnects -V1 attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called +the v1 SDK attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called -V2 attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). +V2 attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. +The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), +are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). +#### Example of tweaking reconnection settings in the v1 SDK -
-Example of tweaking reconnection settings in V1 ```cpp std::chrono::seconds min_reconnect_backoff_timeout = 20; std::chrono::seconds max_reconnect_backoff_timeout = 30; @@ -461,10 +503,8 @@ client.SetMinReconnectBackoffTimeout(min_reconnect_backoff_timeout); client.SetMaxReconnectBackoffTimeout(max_reconnect_backoff_timeout); ``` -
-
-Example of tweaking reconnection settings in V2 +#### Example of tweaking reconnection settings in the v2 SDK ```cpp Aws::Crt::Mqtt5::ReconnectOptions reconnectOptions = { @@ -477,17 +517,16 @@ builder.WithReconnectOptions(); Mqtt5Client client = builder->Build(); ``` -
- ### Offline Operations Queue -V1 doesn’t set a limit on the number on in-flight publish +The v1 SDK doesn’t set a limit on the number on in-flight messages. -V2 provides a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: +The v2 SDK similarly doesn't set a limit on the number of in-flight messages. Additionally, the v2 SDK provides +a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. +The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: -
-Example of configuring the offline queue in V2 +#### Example of configuring the offline queue in the v2 SDK ```cpp AwsIotMqtt5ClientBuilder builder; @@ -500,13 +539,17 @@ Mqtt5Client client = builder->Build(); ``` -Note that AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). -The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. +[!Note] +AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). +The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) +method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. + +#### Example of getting operation statistics in the v2 SDK -Example of getting operation statistics ```cpp Mqtt5::Mqtt5ClientOperationStatistics statistics = mqtt5Client->GetOperationStatistics(); + std::cout<<"Client operations queue statistics\n" <<"\tgetUnackedOperationCoount: " < -See [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) for more details. -See [ClientOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) to find the list of the supported offline queue behaviors and their description. +For more information, see [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) for more details. +For the list of the supported offline queue behaviors and their desriptions, see [ClientOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) to find the list of the supported offline queue behaviors and their description. ### Operation Timeouts -In V1 SDK, all operations (*publish*, *subscribe*, *unsubscribe*) will not timeout unless you define a timeout for them. If no timeout is defined, there is a possibility that an operation will wait forever for the server to respond and block the calling thread indefinitely. +In the v1 SDK, all operations (*publish*, *subscribe*, *unsubscribe*) will not timeout unless you define a timeout for them. +If no timeout is defined, there is a possibility that an operation will wait forever for the server to respond and block the calling thread indefinitely. -In V2 SDK, operations timeout is set for the MQTT5 client with the builder method [withAckTimeoutSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#a2769eb658b3809c5bd3d28724b936a67). The default value is no timeout. As in V1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won’t block the client. -The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking operations. +In the v2 SDK, operations timeout is set for the MQTT5 client with the builder method [withAckTimeoutSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#a2769eb658b3809c5bd3d28724b936a67). +The default value is no timeout. As in the v1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won’t block the client. -
-Example of timeouts in V1 +The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) +method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking operations. + +#### Example of timeouts in the v1 SDK ```cpp std::chrono::milliseconds connectTimeout = 200; @@ -555,25 +600,21 @@ rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), publishTimeout); ``` -
-
-Example of timeouts in V2 +#### Example of timeouts in the v2 SDK ```cpp builder.WithAckTimeoutSeconds(10); Mqtt5Client client = builder->Build(); ``` -
- ### Logging -V1 and V2 SDK uses a custom logger allowing to control the logging process simultaneously for all layers of the SDK. +The v1 and the v2 SDK uses a custom logger, allowing to control the logging process simultaneously for all layers of the SDK. + +#### Example of enabling logging in the v1 SDK -
-Example of enabling logging in V1 To enable logging on V1 follow the next example: ```cpp @@ -590,10 +631,9 @@ AWS_LOG_INFO(INTEG_TEST_RUNNER_LOG_TAG, "Initialize Test Config Failed with rc : %d", 32); ``` -
-
-Example of enabling logging in V2 +#### Example of enabling logging in the v2 SDK + You can enable logging by passing the folowing properties: ```cpp @@ -607,31 +647,35 @@ apiHandle.InitializeLogging(logLevel, stderr); AWS_LOGF_ERROR("log location", "Invalid operation"); ``` -
-
-Example of shutting down logging +#### Example of shutting down logging in the v1 SDK ```cpp awsiotsdk::util::Logging::ShutdownAWSLogging(); ``` -
-In V2 logging is shutdown automatically with ApiHandle destruction when it goes out of scope +In the v2 SDK, logging is shutdown automatically with ApiHandle destruction when it goes out of scope + +### Client for AWS IOT Device Shadow -### Client for Device Shadow Service +The v1 SDK is built with [AWS IoT device shadow support](http://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-shadows.html), +which provides access to thing shadows (sometimes referred to as device shadows). -V1 SDK is built with [AWS IoT device shadow support](http://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-shadows.html), providing access to thing shadows (sometimes referred to as device shadows). It also supports a simplified shadow access model, which allows developers to exchange data with their shadows by just using getter and setter methods without having to serialize or deserialize any JSON documents. +the v2 SDK supports device shadow service as well, but with completely different API. +First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. +For example, `SubscribeToGetShadowAccepted` subscribes to a topic to which AWS IoT Core will publish a shadow document. +The server will notify you if it cannot send you a requested document and via the `SubscribeToGetShadowRejected`.\ +After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. +These actions are also performed via client API calls. +For example, `PublishGetShadow` sends a request to AWS IoT Core to get a shadow document. +The requested Shadow document will be received in a callback specified in the `SubscribeToGetShadowAccepted` call. -V2 SDK supports device shadow service as well, but with completely different API. -First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. For example, `SubscribeToGetShadowAccepted` subscribes to a topic to which AWS IoT Core will publish a shadow document; and via the `SubscribeToGetShadowRejected` the server will notify you if it cannot send you a requested document. -After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. For example, `PublishGetShadow` sends a request to AWS IoT Core to get a shadow document. The requested Shadow document will be received in a callback specified in the `SubscribeToGetShadowAccepted` call. +AWS IoT Core [documentation for Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) +service provides detailed descriptions for the topics used to interact with the service. -AWS IoT Core [documentation for Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) service provides detailed descriptions for the topics used to interact with the service. +#### Example of creating a Device Shadow service client in the v1 SDK -
-Example of creating a Device Shadow service client in V1 ```cpp #include "shadow/Shadow.hpp" // Blocking and non-blocking API. @@ -655,34 +699,35 @@ Shadow shadowClient( ``` ```cpp -// Simplified shadow Access Model. +// Adding shadow callbacks ResponseCode ShadowDelta::ActionResponseHandler( util::String thing_name, ShadowRequestType request_type, ShadowResponseType response_type, util::JsonDocument &payload) { + /* shadow callback received */ } + Shadow::RequestHandlerPtr p_action_handler = std::bind( &ShadowDelta::ActionResponseHandler, this, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4); + util::Map request_mapping; request_mapping.insert(std::make_pair(ShadowRequestType::Get, p_action_handler)); request_mapping.insert(std::make_pair(ShadowRequestType::Update, p_action_handler)); -request_mapping.insert(std::make_pair(ShadowRequestType::Delete, p_action_handler)); +request_mapping.insert(std::make_pair(ShadowRequestType::Delete, p_action_handler)); request_mapping.insert(std::make_pair(ShadowRequestType::Delta, p_action_handler)); -my_shadow.AddShadowSubscription(request_mapping); +shadowClient.AddShadowSubscription(request_mapping); ``` -
+#### Example of creating a Device Shadow service client in the v2 SDK -
-Example of creating a Device Shadow service client in V2 A thing name in V2 SDK shadow client is specified for the operations with shadow documents. ```cpp @@ -702,11 +747,8 @@ client->Start(); Aws::Iotshadow::IotShadowClient shadowClient(client); ``` -
- -
-Example of getting a shadow document in V1 +#### Example of getting a shadow document in the v1 SDK ```cpp // Blockig API. @@ -743,11 +785,9 @@ std::unique_lock block_handler_lock(sync_action_response_lock_); util::JsonDocumen doc = my_shadow.GetServerDocument(); ``` -
+#### Example of getting a shadow document in the v2 SDK -
-Example of getting a shadow document in V2 ```cpp GetShadowSubscriptionRequest shadowSubscriptionRequest; shadowSubscriptionRequest.ThingName = ""; @@ -787,11 +827,9 @@ shadowClient.PublishGetShadow( onGetShadowRequestSubAck); ``` -
+#### Example of updating a shadow document in the V1 SDK -
-Example of updating a shadow document in V1 ```cpp // Non-blocking API. util::JsonDocument doc; @@ -804,10 +842,8 @@ rc = my_shadow.PerformUpdateAsync(); /* for a blocking model look at the Example of getting a shadow document in V1 */ ``` -
-
-Example of updating a shadow document in V2 +#### Example of updating a shadow document in the v2 SDK ```cpp UpdateShadowRequest updateShadowRequest; @@ -852,27 +888,26 @@ shadowClient.PublishUpdateShadow( std::move(publishCompleted)); ``` -
- -See API documentation for V2 SDK [Device Shadow](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotshadow.html) service client for more details. -Refer to the V2 SDK [Device Shadow](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/shadow) sample for code example. +For more information, see API documentation for the v2 SDK [Device Shadow](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotshadow.html).\ +For code examples, see the v2 SDK [Device Shadow](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/shadow). -### Client for Jobs Service -V1 and V2 SDK offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. +### Client for AWS IoT Jobs -V1 IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) +The v1 and v2 SDKs offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) +service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. -The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. +The v1 SDK's IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) -AWS IoT Core documentation for [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html) service provides detailed descriptions for the topics used to interact with the service. +The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). +First, you subscribe to special topics to get data and feedback from a service. +The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, +for example update the status or request for data. These actions are also performed via client API calls. -See API documentation for V2 SDK [Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html) service clients for more details. -Refer to the V2 SDK [Jobs](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/jobs) samples for code examples. +AWS IoT Core documentation for [AWS IOT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html) service provides detailed descriptions for the topics used to interact with the service. -
-V1 example executing jobs +#### Executing jobs in the v1 SDK ```cpp ResponseCode GetPendingCallback( util::String topic_name, @@ -987,10 +1022,9 @@ rc = p_jobs_->SendJobsQuery(Jobs::JOB_GET_PENDING_TOPIC); rc = p_jobs_->SendJobsQuery(Jobs::JOB_DESCRIBE_TOPIC, "$next"); ``` -
-
-V2 example executig a job +#### Executing jobs in the v2 SDK + ```cpp IotJobsClient jobsClient(client); @@ -1059,9 +1093,13 @@ jobsClient.PublishStartNextPendingJobExecution( // Send an update about the status of the job -auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { }; +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { + /* failure callback */ +}; -auto subscribeHandler = [&](UpdateJobExecutionResponse *response, int ioErr) { }; +auto subscribeHandler = [&](UpdateJobExecutionResponse *response, int ioErr) { + +}; auto publishHandler = [&](int ioErr) { }; @@ -1084,65 +1122,101 @@ jobsClient.PublishUpdateJobExecution( publishHandler); ``` -
+ +For more information, see API documentation for the V2 SDK [AWS IOT Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html).\ +For code examples, see the v2 SDK [Jobs Samples](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/jobs). +### Client for AWS IoT fleet provisioning -### Client for Fleet Provisioning Service +[Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) +(also known as Identity Service) is another AWS Iot service that the v2 SDK provides access to. +By using AWS IoT fleet provisioning, AWS IoT can generate and securely deliver device certificates and private keys to your devices when they connect to AWS IoT for the first time. -Another IoT service that V2 SDK provides access to is [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) (also known as Identity Service). By using AWS IoT fleet provisioning, AWS IoT can generate and securely deliver device certificates and private keys to your devices when they connect to AWS IoT for the first time. +The Fleet Provisioning service client provides an API similar to API provided by [Client for Device Shadow Service](#client for-device-shadow-service). +First, you subscribe to special topics to get data and feedback from a service. +The service client provides API for that. +After subscribing to all the required topics, the service client can start interacting with the server, +for example, update the status or request for data. These actions are also performed via client API calls. -The Fleet Provisioning service client provides API similar to API provided by [Client for Device Shadow Service](#client for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. These actions are also performed via client API calls. -AWS IoT Core documentation for [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/fleet-provision-api.html) service provides detailed descriptions for the topics used to interact with the service. +For detailed descriptions for the topics used to interact with the Fleet Provisioning service, see AWS IoT Core +documentation for [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/fleet-provision-api.html). -See API documentation for V2 SDK [Fleet Provisioning](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotidentity.html) service client for more details. -Refer to the V2 SDK [Fleet Provisioning](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/fleet_provisioning/mqtt5_fleet_provisioning) samples for code examples. +For more information about the Fleet Provisioning service client, see API documentation for the v2 SDK [Fleet Provisioning](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotidentity.html). + +For code examples, see the v2 SDK [Fleet Provisioning](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/fleet_provisioning/mqtt5_fleet_provisioning) samples. ### Example -It’s always helpful to look at a working example to see how new functionality works, to be able to tweak different options, to compare with existing code. For that reasons, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) ([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp)) in V2 SDK similar to a sample provided by V1 SDK (see a corresponding [readme section](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/README.md) and [source code](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/PubSub/PubSub.cpp)). +It’s always helpful to look at a working example to see how new functionality works, to be able to tweak different options, +to compare with existing code. For that reason, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) +([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp)) +in the v2 SDK similar to a sample provided by the v1 SDK (see a corresponding +[readme section](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/README.md) and +[source code](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/PubSub/PubSub.cpp)). ## How to Get Help -For any migration related questions or feedback, you can contact us at [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions) by submitting an issue with a label `label:migration`. +Questions? you can look for an answer in the [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions) +page. Or, you can always open a [new +discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions/new?category=q-a&labels=migration), and we will be happy to help you. + ## Appendix ### MQTT5 Features -**Clean Start and Session Expiry** +**Clean Start and Session Expiry**\ You can use Clean Start and Session Expiry to handle your persistent sessions with more flexibility. -Refer to [Mqtt5ClientOptions.ClientSessionBehavior](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client_options.html#a61d6bedd2502d209db912838f74462bb) enum and [NegotiatedSettings.getSessionExpiryInterval](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#aed6565927dcc2ecfb789f978f5a1aee4) method for details. - -**Reason Code on all ACKs** -You can debug or process error messages more easily using the reason codes. Reason codes are returned by the message broker based on the type of interaction with the broker (Subscribe, Publish, Acknowledge). -See [PubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a5901f1fc1e66ef0f859402b747630a02), [SubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a272e5b89320326afd9e0de269100ccd3), [UnsubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a0fece0c83f48d577ea7dfafe58f1261a), [ConnectReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a25d5cf0c9496d5002642c146bf0af9b2), [DisconnectReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ac305e4f9be3e3b06adfdb0abb4814163). - -**Topic Aliases** +For more information, see the [Mqtt5ClientOptions.ClientSessionBehavior](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client_options.html#a61d6bedd2502d209db912838f74462bb) enum and [NegotiatedSettings.getSessionExpiryInterval](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#aed6565927dcc2ecfb789f978f5a1aee4) method. + +**Reason Code on all ACKs**\ +You can debug or process error messages more easily using the reason codes. +Reason codes are returned by the message broker based on the type of interaction with the broker (Subscribe, Publish, Acknowledge). +For more information, see [PubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a5901f1fc1e66ef0f859402b747630a02), +[SubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a272e5b89320326afd9e0de269100ccd3), +[UnsubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a0fece0c83f48d577ea7dfafe58f1261a), +[ConnectReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a25d5cf0c9496d5002642c146bf0af9b2), +[DisconnectReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ac305e4f9be3e3b06adfdb0abb4814163). + +**Topic Aliases**\ You can substitute a topic name with a topic alias, which is a two-byte integer. -Use [withTopicAlias](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#a609e3b04a9c670e07f746da527d3bf17) method when creating a PUBLISH packet. +Use [withTopicAlias](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#a609e3b04a9c670e07f746da527d3bf17) +method when creating a PUBLISH packet. -**Message Expiry** -You can add message expiry values to published messages. Use [withMessageExpiryIntervalSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#aa9e7f2887ab39b0c82a990119df7b941) method in PublishPacketBuilder class. +**Message Expiry**\ +You can add message expiry values to published messages. +Use [withMessageExpiryIntervalSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#aa9e7f2887ab39b0c82a990119df7b941) +method in PublishPacketBuilder class. -**Server disconnect** +**Server disconnect**\ When a disconnection happens, the server can proactively send the client a DISCONNECT to notify connection closure with a reason code for disconnection. -Refer to [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) class for details. - -**Request/Response** -Publishers can request a response be sent by the receiver to a publisher-specified topic upon reception. Use [withResponseTopic](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#acccc99a74512973210026a24f37c2db5) method in PublishPacketBuilder class. - -**Maximum Packet Size** -Client and Server can independently specify the maximum packet size that they support. See [connectPacketBuilder.withMaximumPacketSizeBytes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a88ec9f83510875c5cd92277ecc439bad), [NegotiatedSettings.getMaximumPacketSizeToServer](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a25670e9f1c004d93b3332cd432689b92), and [ConnAckPacket.getMaximumPacketSize](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#a83a5f4aaa007bdf6dddc41c718d0bfd6) methods. - -**Payload format and content type** -You can specify the payload format (binary, text) and content type when a message is published. These are forwarded to the receiver of the message. Use [withContentType](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#a0a5e4d33a3c82cdf4d6ef5d490bd509f) method in PublishPacketBuilder class. - -**Shared Subscriptions** +For more information, see the [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) class. + +**Request/Response**\ +Publishers can request a response be sent by the receiver to a publisher-specified topic upon reception. +Use [withResponseTopic](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#acccc99a74512973210026a24f37c2db5) +method in PublishPacketBuilder class. + +**Maximum Packet Size**\ +Client and Server can independently specify the maximum packet size that they support. +For more information, see the [connectPacketBuilder.withMaximumPacketSizeBytes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a88ec9f83510875c5cd92277ecc439bad), +[NegotiatedSettings.getMaximumPacketSizeToServer](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a25670e9f1c004d93b3332cd432689b92), +and [ConnAckPacket.getMaximumPacketSize](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#a83a5f4aaa007bdf6dddc41c718d0bfd6) methods. + +**Payload format and content type**\ +You can specify the payload format (binary, text) and content type when a message is published. +These are forwarded to the receiver of the message. +Use the [withContentType](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html#a0a5e4d33a3c82cdf4d6ef5d490bd509f) +method in PublishPacketBuilder class. + +**Shared Subscriptions**\ Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. -Refer to [shared subscription](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in V2 SDK. -**NOTE** AWS IoT Core provides this functionality for MQTT3 as well. +For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in the V2 SDK. +[!NOTE] +AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see +[Shared Subscriptions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription) from the AWS IoT Core developer guide From ed6ff2ecc31daa210b9a0d28dcc88c96334ece0b Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Wed, 7 Feb 2024 21:03:07 -0800 Subject: [PATCH 14/33] excape apostrophes --- documents/MIGRATION_GUIDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index cb387fc0b..917471975 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -6,10 +6,10 @@ an offline operation queue control. This guide describes the major features that and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot SDK for C++. > [!NOTE] -> If you can't find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for +> If you can\'t find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for > more help and guidance -* [What's new in AWS IoT Device SDK for C++ v2](#what's-new-in-aws-iot-device-sdk-for-c++-v2) +* [What\'s new in AWS IoT Device SDK for C++ v2](#what\'s-new-in-aws-iot-device-sdk-for-c++-v2) * [How to get started with the v2 sdk for C++](#how-to-get-started-with-the-v2-sdk-for-c++) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) @@ -32,7 +32,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S * [Mqtt5 features](#mqtt5-features) -## What's new in AWS IoT Device SDK for C++ v2 +## What\'s new in AWS IoT Device SDK for C++ v2 * The v2 SDK client is truly async. Operations take callback functions/lambdas, that is called-back when the operation is registered with the server. Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` @@ -522,7 +522,7 @@ Mqtt5Client client = builder->Build(); The v1 SDK doesn’t set a limit on the number on in-flight messages. -The v2 SDK similarly doesn't set a limit on the number of in-flight messages. Additionally, the v2 SDK provides +The v2 SDK similarly doesn\'t set a limit on the number of in-flight messages. Additionally, the v2 SDK provides a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: @@ -898,7 +898,7 @@ For code examples, see the v2 SDK [Device Shadow](https://github.com/aws/aws-iot The v1 and v2 SDKs offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. -The v1 SDK's IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) +The v1 SDK\'s IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. From 9bec7d1fde4909c8d9b9e885b2d8b8cab4ab3045 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Wed, 7 Feb 2024 21:04:23 -0800 Subject: [PATCH 15/33] Remove apostrophe escapes --- documents/MIGRATION_GUIDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 917471975..cb387fc0b 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -6,10 +6,10 @@ an offline operation queue control. This guide describes the major features that and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot SDK for C++. > [!NOTE] -> If you can\'t find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for +> If you can't find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for > more help and guidance -* [What\'s new in AWS IoT Device SDK for C++ v2](#what\'s-new-in-aws-iot-device-sdk-for-c++-v2) +* [What's new in AWS IoT Device SDK for C++ v2](#what's-new-in-aws-iot-device-sdk-for-c++-v2) * [How to get started with the v2 sdk for C++](#how-to-get-started-with-the-v2-sdk-for-c++) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) @@ -32,7 +32,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S * [Mqtt5 features](#mqtt5-features) -## What\'s new in AWS IoT Device SDK for C++ v2 +## What's new in AWS IoT Device SDK for C++ v2 * The v2 SDK client is truly async. Operations take callback functions/lambdas, that is called-back when the operation is registered with the server. Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` @@ -522,7 +522,7 @@ Mqtt5Client client = builder->Build(); The v1 SDK doesn’t set a limit on the number on in-flight messages. -The v2 SDK similarly doesn\'t set a limit on the number of in-flight messages. Additionally, the v2 SDK provides +The v2 SDK similarly doesn't set a limit on the number of in-flight messages. Additionally, the v2 SDK provides a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: @@ -898,7 +898,7 @@ For code examples, see the v2 SDK [Device Shadow](https://github.com/aws/aws-iot The v1 and v2 SDKs offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. -The v1 SDK\'s IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) +The v1 SDK's IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. From cee27ec286fcbe641c7e0da0cf2f56987908d7d0 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Wed, 7 Feb 2024 21:07:28 -0800 Subject: [PATCH 16/33] fix some typos --- documents/MIGRATION_GUIDE.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index cb387fc0b..cb4c0d467 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -37,7 +37,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S * The v2 SDK client is truly async. Operations take callback functions/lambdas, that is called-back when the operation is registered with the server. Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` * The v2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. -* Public APIs terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` as in the V1 SDK. +* Public APIs terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` as in the v1 SDK. This removes the semantic confusion with the client-level controls and internal recurrent networking events related to connection and disconnection. * The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. @@ -331,7 +331,7 @@ The [Subscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_cr a description of the `SubscribePacket` you wish to send and sends back a callback that resolves with success or failure with the corresponding [SubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_sub_ack_packet.html) returned by the broker; You should always check the reason codes of a `SubAckPacket` completion to determine if the subscribe operation actually succeeded. -In V2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, +In the v2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, it is important to also setup the `builder.WithPublishReceivedCallback` callback. This callback is invoked whenever the client receives a message from the server on a topic the client is subscribed to. With this callback, you can process messages made to subscribed topics. @@ -463,7 +463,7 @@ bool rc = client->Unsubscribe(unsub, unsubAck); In the v1 SDK, the `disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `connect`. -In V2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#abc503d1a67c4e1c232f8f722b3c59ca0) +In the v2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#abc503d1a67c4e1c232f8f722b3c59ca0) method. You can provide an optional [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) parameter. A closed client can be started again by calling [Start](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a9035534fc7cc8b48097518409e9c5a6b). @@ -488,9 +488,9 @@ client->Stop(); ### Reconnects -the v1 SDK attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called +The v1 SDK attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called -V2 attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. +The v2 SDK attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). @@ -615,8 +615,6 @@ The v1 and the v2 SDK uses a custom logger, allowing to control the logging proc #### Example of enabling logging in the v1 SDK -To enable logging on V1 follow the next example: - ```cpp #include "util/logging/Logging.hpp" #include "util/logging/LogMacros.hpp" @@ -728,7 +726,7 @@ shadowClient.AddShadowSubscription(request_mapping); #### Example of creating a Device Shadow service client in the v2 SDK -A thing name in V2 SDK shadow client is specified for the operations with shadow documents. +A thing name in the v2 SDK shadow client is specified for the operations with shadow documents. ```cpp #include @@ -828,7 +826,7 @@ shadowClient.PublishGetShadow( ``` -#### Example of updating a shadow document in the V1 SDK +#### Example of updating a shadow document in the v1 SDK ```cpp // Non-blocking API. @@ -839,7 +837,7 @@ util::JsonParser::InitializeFromJsonString( my_shadow.UpdateDeviceShadow(doc); rc = my_shadow.PerformUpdateAsync(); -/* for a blocking model look at the Example of getting a shadow document in V1 */ +/* for a blocking model look at the Example of getting a shadow document in the v1 SDK */ ``` @@ -1123,7 +1121,7 @@ jobsClient.PublishUpdateJobExecution( ``` -For more information, see API documentation for the V2 SDK [AWS IOT Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html).\ +For more information, see API documentation for the v2 SDK [AWS IOT Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html).\ For code examples, see the v2 SDK [Jobs Samples](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/jobs). @@ -1215,7 +1213,7 @@ method in PublishPacketBuilder class. **Shared Subscriptions**\ Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. -For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in the V2 SDK. +For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in the v2 SDK. [!NOTE] AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see [Shared Subscriptions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription) from the AWS IoT Core developer guide From 8a1d3d574e0640e9f39c76c459446a1927473e87 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 08:04:14 -0800 Subject: [PATCH 17/33] shorten code lines --- documents/MIGRATION_GUIDE.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index cb4c0d467..d22a86603 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -85,7 +85,13 @@ util::String rootCaPath = ""; util::String certificateFile = ""; // X.509 based certificate file util::String privateKeyFile = ""; // PEM encoded private key file -std::shared_ptr p_network_connection = std::make_shared( clientEndpoint, clientPort, rootCaPath, certificateFile, privateKeyFile); +std::shared_ptr p_network_connection = + std::make_shared( + clientEndpoint, + clientPort, + rootCaPath, + certificateFile, + privateKeyFile); ResponseCode rc = p_network_connection->Initialize(); ``` @@ -102,7 +108,11 @@ util::String privateKeyFile = ""; // PEM encoded private key uint32_t clientPort = String client_id = "unique client id"; -std::shared_ptr builder(Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(clientEndpoint, certificateFile, privateKeyFile)); +std::shared_ptr builder( + Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath( + clientEndpoint, + certificateFile, + privateKeyFile)); std::shared_ptr connectOptions = std::make_shared(); util::String clientId = "client_id"; connectOptions->WithClientId(clientId); @@ -729,17 +739,6 @@ shadowClient.AddShadowSubscription(request_mapping); A thing name in the v2 SDK shadow client is specified for the operations with shadow documents. ```cpp -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - std::shared_ptr client = builder->Build(); client->Start(); Aws::Iotshadow::IotShadowClient shadowClient(client); From b59edb705a9706bf7acda7043dbc0d1f20d94b2e Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 09:54:30 -0800 Subject: [PATCH 18/33] Remove apostrophe --- documents/MIGRATION_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index d22a86603..a9cf26e54 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -9,7 +9,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S > If you can't find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for > more help and guidance -* [What's new in AWS IoT Device SDK for C++ v2](#what's-new-in-aws-iot-device-sdk-for-c++-v2) +* [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c++-v2) * [How to get started with the v2 sdk for C++](#how-to-get-started-with-the-v2-sdk-for-c++) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) @@ -568,7 +568,7 @@ std::cout<<"Client operations queue statistics\n" ``` -For more information, see [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) for more details. +For more information, see [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) for more details.\ For the list of the supported offline queue behaviors and their desriptions, see [ClientOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) to find the list of the supported offline queue behaviors and their description. From 2b9e1aa390a3ebed2997a491005c2c7914be7241 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 10:00:04 -0800 Subject: [PATCH 19/33] Fix typo --- documents/MIGRATION_GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index a9cf26e54..a3ef59033 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -10,7 +10,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S > more help and guidance * [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c++-v2) -* [How to get started with the v2 sdk for C++](#how-to-get-started-with-the-v2-sdk-for-c++) +* [How to get started with the v2 SDK for C++](#how-to-get-started-with-the-v2-sdk-for-c++) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) * [Connection types and features](#connection-types-and-features) @@ -43,10 +43,10 @@ connection and disconnection. * The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. Public APIs for almost all actions and operations has changed significantly. -For more information about the new features and specific code examples, refer to the [how to get started with the v2 sdk for c++](#how-to-get-started-with-the-v2-sdk-for-c++) sections of this guide. +For more information about the new features and specific code examples, refer to the [How to get started with the v2 SDK for C++](#how-to-get-started-with-the-v2-sdk-for-c++) sections of this guide. -## How To Get Started with the the v2 SDK for C++ +## How To get started with the v2 SDK for C++ There are differences between the v1 SDK and the v2 SDK. This section describes the changes you need to apply to your project with the v1 SDK to start using the v1 SDK. From a3cce5146e79c724418f63b069a06e3e2cf2a7f5 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 10:03:11 -0800 Subject: [PATCH 20/33] Fix wording --- documents/MIGRATION_GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index a3ef59033..cb8fbf014 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -10,7 +10,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S > more help and guidance * [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c++-v2) -* [How to get started with the v2 SDK for C++](#how-to-get-started-with-the-v2-sdk-for-c++) +* [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c++-v2) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) * [Connection types and features](#connection-types-and-features) @@ -43,10 +43,10 @@ connection and disconnection. * The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. Public APIs for almost all actions and operations has changed significantly. -For more information about the new features and specific code examples, refer to the [How to get started with the v2 SDK for C++](#how-to-get-started-with-the-v2-sdk-for-c++) sections of this guide. +For more information about the new features and specific code examples, refer to the [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c++-v2) sections of this guide. -## How To get started with the v2 SDK for C++ +## How To get started with the SDK for C++ v2 There are differences between the v1 SDK and the v2 SDK. This section describes the changes you need to apply to your project with the v1 SDK to start using the v1 SDK. From 868f02c3dfd229ce90515e79995e3c455dd3b04c Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 10:04:41 -0800 Subject: [PATCH 21/33] Try different local link format --- documents/MIGRATION_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index cb8fbf014..628a8f478 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -9,7 +9,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S > If you can't find the information you need in this guide, visit the [How to Get Help](#how-to-get-help) section for > more help and guidance -* [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c++-v2) +* [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c-v2) * [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c++-v2) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) From 49838fb1791539fa87767dab384adb373df45878 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 10:06:45 -0800 Subject: [PATCH 22/33] Fix remaining local link - remove ++ --- documents/MIGRATION_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 628a8f478..d950b0f0d 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -10,7 +10,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S > more help and guidance * [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c-v2) -* [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c++-v2) +* [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c-v2) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) * [Connection types and features](#connection-types-and-features) @@ -43,7 +43,7 @@ connection and disconnection. * The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. Public APIs for almost all actions and operations has changed significantly. -For more information about the new features and specific code examples, refer to the [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c++-v2) sections of this guide. +For more information about the new features and specific code examples, refer to the [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c-v2) sections of this guide. ## How To get started with the SDK for C++ v2 From 79a9aa3db28aeb45e3602b260172587b5c287c8e Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 11:20:53 -0800 Subject: [PATCH 23/33] Fix NOTE tags --- documents/MIGRATION_GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index d950b0f0d..24cf2017e 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -1213,7 +1213,7 @@ method in PublishPacketBuilder class. **Shared Subscriptions**\ Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in the v2 SDK. -[!NOTE] -AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see -[Shared Subscriptions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription) from the AWS IoT Core developer guide +>[!NOTE] +>AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see +>[Shared Subscriptions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription) from the AWS IoT Core developer guide From f3f883b45cf43844faccee0f87b9a913c74aa0ea Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 8 Feb 2024 21:04:51 -0800 Subject: [PATCH 24/33] apply various fixes --- documents/MIGRATION_GUIDE.md | 89 ++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 34 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 24cf2017e..c94fbb054 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -34,12 +34,14 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S ## What's new in AWS IoT Device SDK for C++ v2 -* The v2 SDK client is truly async. Operations take callback functions/lambdas, that is called-back when the operation is registered with the server. - Blocking calls can be emulated by setting an `std::promise<>` in the callback by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` +* The v2 SDK client is truly async. Operations take callback functions/lambdas, that is called-back when the operation + is registered with the server. Blocking calls can be emulated by setting an `std::promise<>` in the callback + by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling + `promise.get_future().wait()` * The v2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. * Public APIs terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` as in the v1 SDK. -This removes the semantic confusion with the client-level controls and internal recurrent networking events related to -connection and disconnection. + This removes the semantic confusion with the client-level controls and internal recurrent networking events related to + connection and disconnection. * The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. Public APIs for almost all actions and operations has changed significantly. @@ -57,7 +59,8 @@ For more information about MQTT5, visit [MQTT5 User Guide](https://github.com/aw The v1 SDK uses an MQTT version 3.1.1 client under the hood. -The v2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementations. This guide focuses on the MQTT5 because this version is significant improvement over MQTT3. +The v2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementations. +This guide focuses on the MQTT5 because this version is significant improvement over MQTT3. For more information see the [MQTT5 features]($mqtt5-features) section. @@ -67,9 +70,11 @@ To access the AWS IoT service, you must initialize an MQTT client. In the v1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html) class represents an MQTT client. You instantiate the client directly passing all the required parameters to the class constructor. -It’s possible to change client settings after its creation using `set*` methods, e.g. `SetAutoReconnectEnabled` or `SetMaxReconnectBackoffTimeout`. +It's possible to change client settings after its creation using `set*` methods, +like `SetAutoReconnectEnabled` or `SetMaxReconnectBackoffTimeout`. -In the v2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) class represents an MQTT client, specifically MQTT5 protocol. +In the v2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) +class represents an MQTT client, specifically for MQTT5 protocol. The v2 SDK provides an [Aws::Iot::Mqtt5ClientBuilder](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html) designed to easily create common configuration types such as direct MQTT or WebSocket connections. After an MQTT5 client is built and finalized, the setting of the resulting MQTT5 client cannot be modified. @@ -122,16 +127,20 @@ std::shared_ptr client = builder->Build(); ``` -For more information, refer to the [Connection Types and Features](#connection-types-and-features) section for other connection types supported by the v2 SDK. +For more information, refer to the [Connection Types and Features](#connection-types-and-features) +section for other connection types supported by the v2 SDK. ### Connection Types and Features -The v1 SDK supports two types of connections to connect to the AWS IoT service: MQTT with X.509 certificate and MQTT over Secure WebSocket with SigV4 authentication. +The v1 SDK supports two types of connections to connect to the AWS IoT service: MQTT with X.509 certificate and MQTT +over Secure WebSocket with SigV4 authentication. -The v2 SDK adds a collection of connection types and cryptography formats (e.g. [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) and +The v2 SDK adds a collection of connection types and cryptography formats +(e.g. [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) and [Custom Authorizer](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html)), credential providers (e.g. [Amazon Cognito](https://aws.amazon.com/cognito/) and -[Windows Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores)), and other connection-related features. +[Windows Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores)), +and other connection-related features. For more information, refer to the [Connecting To AWS IoT Core](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#connecting-to-aws-iot-core) section of the MQTT5 user guide for detailed information and code snippets on each connection type and connection feature. @@ -148,21 +157,25 @@ section of the MQTT5 user guide for detailed information and code snippets on ea | HTTP Proxy | $${\Large\color{orange}✔\*\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#adding-an-http-proxy) | ${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ -${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP proxy, but sustemwide proxy +${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP proxy, but systemwide proxy ### Lifecycle Events Both v1 and v2 SDKs provide lifecycle events for the MQTT clients. -The v1 SDK provides 3 lifecycle events: *ClientCoreState::ApplicationResubscribeCallbackPt*, *ClientCoreState::ApplicationDisconnectCallbackPtr*, and *ClientCoreState::ApplicationReconnectCallbackPtr*. +The v1 SDK provides 3 lifecycle events: *ClientCoreState::ApplicationResubscribeCallbackPt*, +*ClientCoreState::ApplicationDisconnectCallbackPtr*, and *ClientCoreState::ApplicationReconnectCallbackPtr*. You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. -The v2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: *WithClientConnectionSuccessCallback*, -*WithClientConnectionFailureCallback*, *WithClientDisconnectionCallback*, *WithClientStoppedCallback*, and *WithClientAttemptingConnectCallback*. +The v2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), +providing 5 lifecycle events in total: *WithClientConnectionSuccessCallback*, +*WithClientConnectionFailureCallback*, *WithClientDisconnectionCallback*, *WithClientStoppedCallback*, +and *WithClientAttemptingConnectCallback*. -For more information, refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management). +For more information, +refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management). #### Example of setting lifecycle events in the v1 SDK @@ -252,21 +265,28 @@ std::shared_ptr client = builder->Build(); ### Publish -The v1 SDK provides two API calls for publishing: blocking and non-blocking. For the non-blocking version, the result of the publish operation is reported via a set of callbacks. +The v1 SDK provides two API calls for publishing: blocking and non-blocking. For the non-blocking version, +the result of the publish operation is reported via a set of callbacks. If you try to publish to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. -The v2 SDK provides only asynchronous non-blocking API. A [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) +The v2 SDK provides only asynchronous non-blocking API. +A [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) object containing a description of the PUBLISH packet. -The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation -takes a `PublishPacket` instance and a [Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) -that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) in its parameter that will -contain different data depending on the `QoS` used in the publish. - -* For QoS 0 (AT\_MOST\_ONCE): Calling `getValue` will return `null` and the promise will be complete as soon as the packet has been written to the socket. -* For QoS 1 (AT\_LEAST\_ONCE): Calling `getValue` will return a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) and the promise will be complete as soon as the PUBACK is received from the broker. - -If the operation fails for any reason before these respective completion events, the promise is rejected with a descriptive error. -You should always check the reason code of a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) +The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) +operation takes a `PublishPacket` instance and a +[Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) +that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) +in its parameter that will contain different data depending on the `QoS` used in the publish. + +* For QoS 0 (AT\_MOST\_ONCE): Calling `getValue` will return `null` + and the promise will be complete as soon as the packet has been written to the socket. +* For QoS 1 (AT\_LEAST\_ONCE): Calling `getValue` will return a + [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) + and the promise will be complete as soon as the PUBACK is received from the broker. + +If the operation fails for any reason before these respective completion events, +the promise is rejected with a descriptive error. You should always check the reason code of a +[PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) completion to determine if a QoS 1 publish operation actually succeeded. #### Example of publishing in the v1 SDK @@ -530,7 +550,7 @@ Mqtt5Client client = builder->Build(); ### Offline Operations Queue -The v1 SDK doesn’t set a limit on the number on in-flight messages. +The v1 SDK doesn't set a limit on the number on in-flight messages. The v2 SDK similarly doesn't set a limit on the number of in-flight messages. Additionally, the v2 SDK provides a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. @@ -552,7 +572,7 @@ Mqtt5Client client = builder->Build(); [!Note] AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) -method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking the number of in-flight messages. +method returns the current state of an `Mqtt5Client` object's queue of operations, which may help with tracking the number of in-flight messages. #### Example of getting operation statistics in the v2 SDK @@ -578,10 +598,10 @@ In the v1 SDK, all operations (*publish*, *subscribe*, *unsubscribe*) will not t If no timeout is defined, there is a possibility that an operation will wait forever for the server to respond and block the calling thread indefinitely. In the v2 SDK, operations timeout is set for the MQTT5 client with the builder method [withAckTimeoutSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#a2769eb658b3809c5bd3d28724b936a67). -The default value is no timeout. As in the v1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won’t block the client. +The default value is no timeout. As in the v1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won't block the client. The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) -method returns the current state of an `Mqtt5Client` object’s queue of operations, which may help with tracking operations. +method returns the current state of an `Mqtt5Client` object's queue of operations, which may help with tracking operations. #### Example of timeouts in the v1 SDK @@ -895,7 +915,8 @@ For code examples, see the v2 SDK [Device Shadow](https://github.com/aws/aws-iot The v1 and v2 SDKs offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. -The v1 SDK's IotJobs APIs are defined [here](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), with its corresponding code [samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) +For more information, see [Iot Jobs APIs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), +For code examples, see [Jobs samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. @@ -1147,7 +1168,7 @@ For code examples, see the v2 SDK [Fleet Provisioning](https://github.com/aws/aw ### Example -It’s always helpful to look at a working example to see how new functionality works, to be able to tweak different options, +It's always helpful to look at a working example to see how new functionality works, to be able to tweak different options, to compare with existing code. For that reason, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) ([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp)) in the v2 SDK similar to a sample provided by the v1 SDK (see a corresponding From 87ef8fa0baaded70ccbfb9b57353dd667de3e482 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 15 Feb 2024 20:02:12 -0800 Subject: [PATCH 25/33] Sync with the Java migration guide --- README.md | 1 + documents/MIGRATION_GUIDE.md | 542 ++++++++++++++++++++++++----------- 2 files changed, 374 insertions(+), 169 deletions(-) diff --git a/README.md b/README.md index eb1d753fb..ccc1aa391 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ __Jump To:__ * [FAQ](./documents/FAQ.md) * [API Docs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/) * [MQTT5 User Guide](./documents/MQTT5_Userguide.md) +* [Migration Guide from the AWS IoT SDK for C++ v1](./documents/MIGRATION_GUIDE.md) ## Installation diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index c94fbb054..ca3b92909 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -13,12 +13,13 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S * [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c-v2) * [Mqtt protocol](#mqtt-protocol) * [client builder](#client-builder) + * [Client Start](#client-start) * [Connection types and features](#connection-types-and-features) * [Lifecycle events](#lifecycle-events) * [Publish](#publish) * [Subscribe](#subscribe) * [Unsubscribe](#unsubscribe) - * [Client stop](#client-stop) + * [Client Stop](#client-stop) * [Reconnects](#reconnects) * [Offline operations queue](#offline-operations-queue) * [Operation timeouts](#operation-timeouts) @@ -39,22 +40,15 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` * The v2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. -* Public APIs terminology has changed. You `Start()` or `Stop()` the MQTT5 client rather than `Connect` or `Disconnect` as in the v1 SDK. - This removes the semantic confusion with the client-level controls and internal recurrent networking events related to - connection and disconnection. * The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. -Public APIs for almost all actions and operations has changed significantly. -For more information about the new features and specific code examples, refer to the [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c-v2) sections of this guide. - - ## How To get started with the SDK for C++ v2 +Public APIs for almost all actions and operations has changed significantly. There are differences between the v1 SDK and the v2 SDK. This section describes the changes you need to apply to your -project with the v1 SDK to start using the v1 SDK. +project with the v1 SDK to start using the v2 SDK.\ For more information about MQTT5, visit [MQTT5 User Guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md). - ### MQTT Protocol The v1 SDK uses an MQTT version 3.1.1 client under the hood. @@ -68,16 +62,17 @@ For more information see the [MQTT5 features]($mqtt5-features) section. To access the AWS IoT service, you must initialize an MQTT client. -In the v1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html) class represents an MQTT client. +In the v1 SDK, the [awsiotsdk::MqttClient](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html) +class represents an MQTT client. You instantiate the client directly passing all the required parameters to the class constructor. It's possible to change client settings after its creation using `set*` methods, like `SetAutoReconnectEnabled` or `SetMaxReconnectBackoffTimeout`. -In the v2 SDK, the [Aws::Iot::MqttClient](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt_client.html) +In the v2 SDK, the [Aws::Iot::Mqtt5Client](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html) class represents an MQTT client, specifically for MQTT5 protocol. The v2 SDK provides an [Aws::Iot::Mqtt5ClientBuilder](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html) designed to easily create common configuration types such as direct MQTT or WebSocket connections. -After an MQTT5 client is built and finalized, the setting of the resulting MQTT5 client cannot be modified. +After an MQTT5 client is built and finalized, the settings of the resulting MQTT5 client cannot be modified. #### Example of creating a client in the v1 SDK @@ -99,6 +94,14 @@ std::shared_ptr p_network_connection = privateKeyFile); ResponseCode rc = p_network_connection->Initialize(); +std::chrono::milliseconds mqtt_timeout = 1000; +std::shared_ptrclient = std::shared_ptr( + MqttClient::Create( + p_network_connection, + mqtt_timeout, + /* disconnect handler */, nullptr, + /* reconnect handler */, nullptr, + /* resubscribe handler */, nullptr); ``` #### Example of creating a client in the v2 SDK @@ -123,6 +126,7 @@ util::String clientId = "client_id"; connectOptions->WithClientId(clientId); builder->WithConnectOptions(connectOptions); builder->WithPort(clientPort); + std::shared_ptr client = builder->Build(); ``` @@ -130,9 +134,27 @@ std::shared_ptr client = builder->Build(); For more information, refer to the [Connection Types and Features](#connection-types-and-features) section for other connection types supported by the v2 SDK. +### Client Start +To connect to the server in the v1 SDK, you call the `connect` method on an `MQTTClient` instance. + +The v2 SDK changed API terminology. You `Start` the MQTT5 client rather than `Connect` as in the v1 SDK. This removes +the semantinc confusion between client-level controls and internal recurrent networking events related to connection. + +#### Example of connecting to a server in the v1 SDK +```cpp +std::shared_ptrclient = std::shared_ptr(MqttClient::Create(p_network_connection, ...); +client.Connect(); +``` + +#### Example of connecting to a server in the v2 SDK +```cpp +std::shared_ptr client = builder->Build(); +client.Start(); +``` + ### Connection Types and Features -The v1 SDK supports two types of connections to connect to the AWS IoT service: MQTT with X.509 certificate and MQTT +The v1 SDK supports two types of connections to the AWS IoT service: MQTT with X.509 certificate and MQTT over Secure WebSocket with SigV4 authentication. The v2 SDK adds a collection of connection types and cryptography formats @@ -151,12 +173,13 @@ section of the MQTT5 user guide for detailed information and code snippets on ea | Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | | MQTT with X.509 certificate based mutual authentication | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-x509-based-mutual-tls) | | MQTT with PKCS12 Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs12-method) | -| MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authorizer-method) | +| MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authentication) | | MQTT with Windows Certificate Store Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-windows-certificate-store-method) | | MQTT with PKCS11 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs11-method) | | HTTP Proxy | $${\Large\color{orange}✔\*\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#adding-an-http-proxy) | -${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ +${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 SDK, you need to implement the +[Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ ${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP proxy, but systemwide proxy @@ -164,7 +187,7 @@ ${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP Both v1 and v2 SDKs provide lifecycle events for the MQTT clients. -The v1 SDK provides 3 lifecycle events: *ClientCoreState::ApplicationResubscribeCallbackPt*, +The v1 SDK provides three lifecycle events: *ClientCoreState::ApplicationResubscribeCallbackPt*, *ClientCoreState::ApplicationDisconnectCallbackPtr*, and *ClientCoreState::ApplicationReconnectCallbackPtr*. You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. @@ -173,6 +196,7 @@ The v2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), providing 5 lifecycle events in total: *WithClientConnectionSuccessCallback*, *WithClientConnectionFailureCallback*, *WithClientDisconnectionCallback*, *WithClientStoppedCallback*, and *WithClientAttemptingConnectCallback*. +It is also recommended to use lifecycle events callbacks on the v2 SDK. For more information, refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#client-lifecycle-management). @@ -180,7 +204,6 @@ refer to the [MQTT5 user guide](https://github.com/aws/aws-iot-device-sdk-cpp-v2 #### Example of setting lifecycle events in the v1 SDK ```cpp -std::shared_ptr p_iot_client_; ResponseCode DisconnectCallback( util::String client_id, std::shared_ptr p_app_handler_data) { @@ -220,20 +243,24 @@ ClientCoreState::ApplicationResubscribeCallbackPtr p_resubscribe_handler = std::placeholders::_2, std::placeholders::_3); -p_iot_client_ = std::shared_ptr( +std::shared_ptr client; + +client = std::shared_ptr( MqttClient::Create(p_network_connection_, ConfigCommon::mqtt_command_timeout_, p_disconnect_handler, nullptr, p_reconnect_handler, nullptr, p_resubscribe_handler, nullptr)); -rc = p_iot_client_->Connect(/*...*/); +rc = client->Connect(/*...*/); ``` #### Example of setting lifecycle events in the v2 SDK ```cpp +std::shared_ptr builder( ... ); + builder->WithClientConnectionSuccessCallback( [&](const Mqtt5::OnConnectionSuccessEventData &eventData) { /* Connection success event received */ @@ -270,7 +297,7 @@ the result of the publish operation is reported via a set of callbacks. If you try to publish to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. The v2 SDK provides only asynchronous non-blocking API. -A [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) +Begin by creeating a [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) object containing a description of the PUBLISH packet. The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation takes a `PublishPacket` instance and a @@ -278,6 +305,11 @@ operation takes a `PublishPacket` instance and a that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) in its parameter that will contain different data depending on the `QoS` used in the publish. +> [!NOTE] +> If you try to publish with the v2 MQTT5 client to a topic that is not allowed by a policy, you do not get the +> connection +> closed but instead receive a PUBACK with a reason code. + * For QoS 0 (AT\_MOST\_ONCE): Calling `getValue` will return `null` and the promise will be complete as soon as the packet has been written to the socket. * For QoS 1 (AT\_LEAST\_ONCE): Calling `getValue` will return a @@ -297,7 +329,7 @@ std::chrono::milliseconds action_response_timeout = 20; bool is_retained = false; bool is_duplicate = false; -ResponseCode rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), +ResponseCode rc = client->Publish(Utf8String::Create("my/topic"), is_retained, is_duplicate, awsiotsdk::mqtt::QoS::QOS1, @@ -321,7 +353,7 @@ ActionData::AsyncAckNotificationHandlerPtr p_async_ack_handler = std::placeholders::_2); uint16_t &packet_id_out; -rc = p_iot_client_->PublishAsync(Utf8String::Create("my/topic"), +rc = client->PublishAsync(Utf8String::Create("my/topic"), is_retained, is_duplicate, mqtt::QoS::QOS0, @@ -349,17 +381,27 @@ bool rc = client->Publish(publish, onPublishComplete); ### Subscribe -The v1 SDK provides blocking and non-blocking API for subscribing. +The v1 SDK provides blocking and non-blocking APIs for subscribing. To subscribe to a topic in the v1 SDK, you should provide an instance of [awsiotsdk::mqtt::Subscription](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1mqtt_1_1_subscription.html) -to the [subscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a9702f18a7d663aae5b76bae70d3999c7) operation. -awsiotsdk::mqtt::Subscription object (or, usually, an object of a children class) implements `ApplicationCallbackHandlerPtr` method which will be called on receiving a new message. +to the [subscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a9702f18a7d663aae5b76bae70d3999c7) +operation. `awsiotsdk::mqtt::Subscription` object (or, usually, an object of a children class) +implements `ApplicationCallbackHandlerPtr` method which will be called on receiving a new message. If you try to subscribe to a topic that is not allowed by a policy, AWS IoT Core service will close the connection. -The v2 SDK provides only asynchronous non-blocking API. First, you need to create a [SubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_subscribe_packet.html) object. -If you specify multiple topics in the WithSubscription member function, the v2 SDK will subscribe to all of these topics using one request. -The [Subscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa6c3bfc3cbd99b17957148ac1e8c34c4) operation takes -a description of the `SubscribePacket` you wish to send and sends back a callback that resolves with success or failure with the corresponding [SubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_sub_ack_packet.html) returned by the broker; -You should always check the reason codes of a `SubAckPacket` completion to determine if the subscribe operation actually succeeded. +The v2 SDK provides only asynchronous non-blocking API. +First, you need to create a [SubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_subscribe_packet.html) +object. If you specify multiple topics in the `WithSubscription` member function, +the v2 SDK will subscribe to all of these topics using one request. +The [Subscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa6c3bfc3cbd99b17957148ac1e8c34c4) +operation takes a description of the `SubscribePacket` you wish to send and sends back a callback that +resolves with success or failure with the corresponding [SubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_sub_ack_packet.html) +returned by the broker. You should always check the reason codes of a `SubAckPacket` completion +to determine if the subscribe operation actually succeeded. + +> [!NOTE] +> If you try to subscribe with the v2 MQTT5 client to a topic that is not allowed by a policy, you do not get the +> connection +> closed but instead receive a SUBACK with a reason code. In the v2 SDK, if the MQTT5 client is going to subscribe and receive packets from the MQTT broker, it is important to also setup the `builder.WithPublishReceivedCallback` callback. @@ -398,7 +440,7 @@ topic_vector.push_back(p_subscription); std::chrono::milliseconds action_response_timeout = 10; // Subscribe to topic -ResponseCode rc = p_iot_client_->Subscribe(topic_vector, +ResponseCode rc = client->Subscribe(topic_vector, action_response_timeout); ``` @@ -408,7 +450,7 @@ ResponseCode rc = p_iot_client_->Subscribe(topic_vector, ```cpp builder->WithPublishReceivedCallback( [&](const Mqtt5::PublishReceivedEventData &eventData) { - /*Called when a message is received by one of the active subscriptions.*/ + /* Called when a message is received by one of the active subscriptions. */ }); std::shared_ptr client = builder->Build(); @@ -430,17 +472,23 @@ bool rc = client->Subscribe(subPacket, onSubAck); ### Unsubscribe -the v1 SDK provides blocking and non-blocking API for unsubscribing. To unsubscribe from a topic in the v1 SDK, -you should provide a `std::vector` of `std::unique_ptr` of `Utf8String` to the [Unsubscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a8dc5fa8e8c1522219e6df33cbaa7e376) operation. -For asynchronous operations use [UnsubscribeAsync](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a4577dd3e720dea692755c640d4c638ed) success and failure results are sent through the callback [ActionData::AsyncAckNotificationHandlerPtr](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_action_data.html#a5d1d7452e081205b414e4df985d82f60) -`unsubscribeAsync` takes a callback argument or type `ActionData::AsyncAckNotificationHandlerPtr`, that will be called when the operation fails or succeeds. +The v1 SDK provides blocking and non-blocking APIs for unsubscribing. To unsubscribe from a topic in the v1 SDK, +you should provide a `std::vector` of `std::unique_ptr` of `Utf8String` to the +[Unsubscribe](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a8dc5fa8e8c1522219e6df33cbaa7e376) +operation. +For asynchronous operations use [UnsubscribeAsync](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_mqtt_client.html#a4577dd3e720dea692755c640d4c638ed) +success and failure results are sent through the callback [ActionData::AsyncAckNotificationHandlerPtr](http://aws-iot-device-sdk-cpp-docs.s3-website-us-east-1.amazonaws.com/latest/classawsiotsdk_1_1_action_data.html#a5d1d7452e081205b414e4df985d82f60) +`unsubscribeAsync` takes a callback argument or type `ActionData::AsyncAckNotificationHandlerPtr`, +that will be called when the operation succeeds or fails. -the v2 SDK provides only asynchronous non-blocking API. First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) object. -The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) operation takes a description of -the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) you wish to send and -returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) -returned by the broker; the promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) +The v2 SDK provides only asynchronous non-blocking API. +First, you need to create an [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) +object. +The [Unsubscribe](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a96a931b49893d54712062722c5ab7d1a) +operation takes a description of the [UnsubscribePacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_unsubscribe_packet.html) +you wish to send and returns a promise that resolves successfully with the corresponding [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) +returned by the broker. The promise is rejected with an error if anything goes wrong before the [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) is received. You should always check the reason codes of a [UnsubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_un_sub_ack_packet.html) completion to determine if the unsubscribe operation actually succeeded. @@ -455,8 +503,10 @@ std::chrono::milliseconds action_response_timeout = 20; std::unique_ptr p_topic_name = Utf8String::Create("my/topic"); util::Vector> topic_vector; topic_vector.push_back(std::move(p_topic_name)); -ResponseCode rc = p_iot_client_->Unsubscribe(std::move(topic_vector), - action_response_timeout); + +ResponseCode rc = client->Unsubscribe( + std::move(topic_vector), + action_response_timeout); ``` @@ -471,9 +521,12 @@ p_topic_name = "my/topic"; topic_vector.push_back(std::move(p_topic_name)); ActionData::AsyncAckNotificationHandlerPtr p_async_ack_handler auto unsubAck = [&](uint16_t action_id, ResponseCode rc) { }; -ResponseCode rc = p_iot_client_->UnsubscribeAsync(std::move(topic_vector), - unsubAck, - packet_id); + +ResponseCode rc = client->UnsubscribeAsync( + std::move(topic_vector), + unsubAck, + packet_id); + ``` #### Example of unsubscribing in the v2 SDK @@ -485,13 +538,15 @@ unsub->WithTopicFilter("my/topic"); auto unsubAck = [&](int, std::shared_ptr) { /* callback */ }; + bool rc = client->Unsubscribe(unsub, unsubAck); ``` ### Client Stop -In the v1 SDK, the `disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `connect`. +In the v1 SDK, the `Disconnect` method in the `AWSIotMqttClient` class disconnects the client. +Once disconnected, the client can connect again by calling `Connect`. In the v2 SDK, an MQTT5 client can stop a session by calling the [Stop](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#abc503d1a67c4e1c232f8f722b3c59ca0) method. You can provide an optional [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) @@ -520,7 +575,8 @@ client->Stop(); The v1 SDK attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called -The v2 SDK attempts to reconnect automatically until connection succeeds or `client.stop()` is called, either the initial `client→Start()` succeeds or fails. +The v2 SDK attempts to reconnect automatically until connection succeeds or `client.Stop()` is called, +either the initial `client.Start()` succeeds or fails. The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). @@ -529,6 +585,7 @@ are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github. ```cpp std::chrono::seconds min_reconnect_backoff_timeout = 20; std::chrono::seconds max_reconnect_backoff_timeout = 30; + client.SetMinReconnectBackoffTimeout(min_reconnect_backoff_timeout); client.SetMaxReconnectBackoffTimeout(max_reconnect_backoff_timeout); @@ -543,6 +600,7 @@ Aws::Crt::Mqtt5::ReconnectOptions reconnectOptions = { 1000, // max reconnect delay ms 1000 // min connected time to reset reconnect delay ms }; + builder.WithReconnectOptions(); Mqtt5Client client = builder->Build(); @@ -552,27 +610,30 @@ Mqtt5Client client = builder->Build(); The v1 SDK doesn't set a limit on the number on in-flight messages. -The v2 SDK similarly doesn't set a limit on the number of in-flight messages. Additionally, the v2 SDK provides -a way to configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. -The following code snippet demonstrates how to enable storing all packets except QOS0 publish packets in the offline queue on disconnect: +The v2 SDK similarly doesn't set a limit on the number of in-flight messages. Additionally, the v2 SDK provides a way to +configure which kind of packets will be placed into the offline queue when the client is in the disconnected state. +The following code snippet demonstrates how to enable storing all packets +except QOS0 publish packets in the offline queue on disconnect: #### Example of configuring the offline queue in the v2 SDK ```cpp -AwsIotMqtt5ClientBuilder builder; std::shared_ptr builder( Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(/* ... */)); + builder.WithOfflineQueueBehavior( Mqtt5::ClientOperationQueueBehaviorType:: AWS_MQTT5_COQBT_FAIL_QOS0_PUBLISH_ON_DISCONNECT); + Mqtt5Client client = builder->Build(); ``` -[!Note] -AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). +> [!Note] +> AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) -method returns the current state of an `Mqtt5Client` object's queue of operations, which may help with tracking the number of in-flight messages. +method returns the current state of an `Mqtt5Client` object's queue of operations, +which may help with tracking the number of in-flight messages. #### Example of getting operation statistics in the v2 SDK @@ -588,20 +649,24 @@ std::cout<<"Client operations queue statistics\n" ``` -For more information, see [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) for more details.\ -For the list of the supported offline queue behaviors and their desriptions, see [ClientOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816) to find the list of the supported offline queue behaviors and their description. +For more information, see [withOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816)\ +For the list of the supported offline queue behaviors and their desriptions, see [ClientOfflineQueueBehavior documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a1eb626870603eab906714e2b86d79816). ### Operation Timeouts -In the v1 SDK, all operations (*publish*, *subscribe*, *unsubscribe*) will not timeout unless you define a timeout for them. -If no timeout is defined, there is a possibility that an operation will wait forever for the server to respond and block the calling thread indefinitely. +In the v1 SDK, all operations (*publish*, *subscribe*, *unsubscribe*) will not timeout unless +you define a timeout for them. +If no timeout is defined, there is a possibility that an operation will wait forever for the server to respond and +block the calling thread indefinitely. In the v2 SDK, operations timeout is set for the MQTT5 client with the builder method [withAckTimeoutSeconds](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#a2769eb658b3809c5bd3d28724b936a67). -The default value is no timeout. As in the v1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won't block the client. +The default value is no timeout. As in the v1 SDK, failing to set a timeout can cause an operation to stuck forever, +but it won't block the client. The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) -method returns the current state of an `Mqtt5Client` object's queue of operations, which may help with tracking operations. +method returns the current state of an `Mqtt5Client` object's queue of operations, +which may help with tracking operations. #### Example of timeouts in the v1 SDK @@ -612,22 +677,24 @@ std::chrono::seconds keepAliveTimeout = 200; util::String client_id_tagged = "clID" std::unique_ptr client_id = Utf8String::Create(client_id_tagged); -rc = p_iot_client_->Connect(connectTimeout, - true - mqtt::Version::MQTT_3_1_1, - keepAliveTimeout, - std::move(client_id), - nullptr, - nullptr, - nullptr); +rc = client->Connect( + connectTimeout, + true + mqtt::Version::MQTT_3_1_1, + keepAliveTimeout, + std::move(client_id), + nullptr, + nullptr, + nullptr); std::chrono::seconds publishTimeout = 10; -rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), - false, - false, - awsiotsdk::mqtt::QoS::QOS1, - "hello", - publishTimeout); +rc = client->Publish( + Utf8String::Create("my/topic"), + false, + false, + awsiotsdk::mqtt::QoS::QOS1, + "hello", + publishTimeout); ``` @@ -635,13 +702,15 @@ rc = p_iot_client_->Publish(Utf8String::Create("my/topic"), ```cpp builder.WithAckTimeoutSeconds(10); + Mqtt5Client client = builder->Build(); ``` ### Logging -The v1 and the v2 SDK uses a custom logger, allowing to control the logging process simultaneously for all layers of the SDK. +The v1 and the v2 SDK use a custom logger, allowing to control the logging process simultaneously +for all layers of the SDK. #### Example of enabling logging in the v1 SDK @@ -682,7 +751,6 @@ AWS_LOGF_ERROR("log location", "Invalid operation"); awsiotsdk::util::Logging::ShutdownAWSLogging(); ``` - In the v2 SDK, logging is shutdown automatically with ApiHandle destruction when it goes out of scope ### Client for AWS IOT Device Shadow @@ -690,12 +758,12 @@ In the v2 SDK, logging is shutdown automatically with ApiHandle destruction when The v1 SDK is built with [AWS IoT device shadow support](http://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-shadows.html), which provides access to thing shadows (sometimes referred to as device shadows). -the v2 SDK supports device shadow service as well, but with completely different API. +The v2 SDK also supports device shadow service, but with completely different API. First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. For example, `SubscribeToGetShadowAccepted` subscribes to a topic to which AWS IoT Core will publish a shadow document. The server will notify you if it cannot send you a requested document and via the `SubscribeToGetShadowRejected`.\ -After subscribing to all the required topics, the service client can start interacting with the server, for example update the status or request for data. -These actions are also performed via client API calls. +After subscribing to all the required topics, the service client can start interacting with the server, +for example update the status or request for data. These actions are also performed via client API calls. For example, `PublishGetShadow` sends a request to AWS IoT Core to get a shadow document. The requested Shadow document will be received in a callback specified in the `SubscribeToGetShadowAccepted` call. @@ -709,17 +777,17 @@ service provides detailed descriptions for the topics used to interact with the // Blocking and non-blocking API. String thingName = ""; std::chrono::milliseconds mqtt_command_timeout = 200; -ResponseCode rc = p_iot_client_->Connect(/* ... */); +ResponseCode rc = client->Connect(/* ... */); // 1st way Shadow shadowClient( - p_iot_client_, + client, mqtt_command_timeout, thingNmae, clientTokenPrefix); -// 2nd way +// 2nd way through a static method std::unique_ptr shadowClient = Shadow::Create( - p_iot_client_, + client, mqtt_command_timeout, thingName, clientTokenPrefix); @@ -727,7 +795,7 @@ Shadow shadowClient( ``` ```cpp -// Adding shadow callbacks +// shadow callbacks registration ResponseCode ShadowDelta::ActionResponseHandler( util::String thing_name, ShadowRequestType request_type, @@ -909,23 +977,46 @@ shadowClient.PublishUpdateShadow( For more information, see API documentation for the v2 SDK [Device Shadow](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotshadow.html).\ For code examples, see the v2 SDK [Device Shadow](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/shadow). - ### Client for AWS IoT Jobs -The v1 and v2 SDKs offer support of AWS IoT Core services implementing a service client for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) -service which helps with defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. +The v1 and v2 SDKs both offer support for AWS IoT Core services implementing a service client +for the [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service which helps with +defining a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. -For more information, see [Iot Jobs APIs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html), -For code examples, see [Jobs samples](https://github.com/aws/aws-iot-device-sdk-cpp/tree/master/samples/Jobs) - -The Jobs service client provides API similar to API provided by [Client for Device Shadow Service](#client-for-device-shadow-service). +The Jobs service client provides APIs similar to the APIs provided by [Client for Device Shadow Service](#client-for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. -The service client provides API for that. After subscribing to all the required topics, the service client can start interacting with the server, -for example update the status or request for data. These actions are also performed via client API calls. +The service client provides API for that. After subscribing to all the required topics, +the service client can start interacting with the server, +for example, update the status or request for data. These actions are also performed via client API calls. -AWS IoT Core documentation for [AWS IOT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html) service provides detailed descriptions for the topics used to interact with the service. -#### Executing jobs in the v1 SDK +#### Example creating a jobs client in the v1 SDK + +```cpp +util::String client_id_tagged = ConfigCommon::base_client_id_; +client_id_tagged.append("_jobs_sample_"); +client_id_tagged.append(std::to_string(rand())); + +jobsClient = Jobs::Create( + client, + mqtt::QoS::QOS1, + "", + client_id_tagged); + +``` + +#### Example creating a jobs client in the v2 SDK + +```cpp +std::shared_ptr client = builder->Build(); +client->Start(); + +IotJobsClient jobsClient(client); + +``` + +#### Example subscribing to jobs topics in the v1 SDK + ```cpp ResponseCode GetPendingCallback( util::String topic_name, @@ -947,8 +1038,7 @@ ResponseCode UpdateRejectedCallback( util::String payload, std::shared_ptr p_app_handler_data) {} -rc = p_iot_client_->Connect(/*...*/); - +rc = client->Connect(/*...*/); mqtt::Subscription::ApplicationCallbackHandlerPtr p_pending_handler = std::bind( @@ -985,14 +1075,14 @@ mqtt::Subscription::ApplicationCallbackHandlerPtr p_update_rejected_handler = util::Vector> topic_vector; std::shared_ptr p_subscription; -p_subscription = p_jobs_->CreateJobsSubscription( +p_subscription = jobsClient->CreateJobsSubscription( p_pending_handler, nullptr, Jobs::JOB_GET_PENDING_TOPIC, Jobs::JOB_ACCEPTED_REPLY_TYPE); topic_vector.push_back(p_subscription); -p_subscription = p_jobs_->CreateJobsSubscription( +p_subscription = jobsClient->CreateJobsSubscription( p_next_handler, nullptr, Jobs::JOB_DESCRIBE_TOPIC, @@ -1000,13 +1090,13 @@ p_subscription = p_jobs_->CreateJobsSubscription( "$next"); topic_vector.push_back(p_subscription); -p_subscription = p_jobs_->CreateJobsSubscription( +p_subscription = jobsClient->CreateJobsSubscription( p_next_handler, nullptr, Jobs::JOB_NOTIFY_NEXT_TOPIC); topic_vector.push_back(p_subscription); -p_subscription = p_jobs_->CreateJobsSubscription( +p_subscription = jobsClient->CreateJobsSubscription( p_update_accepted_handler, nullptr, Jobs::JOB_UPDATE_TOPIC, @@ -1014,7 +1104,7 @@ p_subscription = p_jobs_->CreateJobsSubscription( "+"); topic_vector.push_back(p_subscription); -p_subscription = p_jobs_->CreateJobsSubscription( +p_subscription = jobsClient->CreateJobsSubscription( p_update_rejected_handler, nullptr, Jobs::JOB_UPDATE_TOPIC, @@ -1022,29 +1112,125 @@ p_subscription = p_jobs_->CreateJobsSubscription( "+"); topic_vector.push_back(p_subscription); -ResponseCode rc = p_iot_client_->Subscribe( +std::chrono::milliseconds response_timeout = 10; +ResponseCode rc = client->Subscribe( topic_vector, - ConfigCommon::mqtt_command_timeout_); + response_timeout); -util::String client_id_tagged = ConfigCommon::base_client_id_; -client_id_tagged.append("_jobs_sample_"); -client_id_tagged.append(std::to_string(rand())); +ResponseCode rc; +rc = jobsClient->SendJobsQuery(Jobs::JOB_GET_PENDING_TOPIC); +rc = jobsClient->SendJobsQuery(Jobs::JOB_DESCRIBE_TOPIC, "$next"); + +``` + +#### Example subscribing to jobs topics in the v2 SDK +Subscribing to events in the v2 SDK is done for each API + +```cpp +auto err_handler = [&](Aws::Iotjobs::RejectedError *rejectedError, int ioErr) + { + /* callback received on error */ + } + +auto publishHandler = [&](int ioErr) + { + /* callback received when the server accepts the request */ + } + +auto success_handler = [&](Aws::Iotjobs::GetPendingJobExecutionsResponse *response, int ioErr) + { + /* callback received on successfull reception of data or ioErr is set */ + } + +GetPendingJobExecutionsSubscriptionRequest subscriptionRequest; +subscriptionRequest.ThingName = thingName; + +jobsClient.SubscribeToGetPendingJobExecutionsAccepted( + subscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + success_handler, + publishHandler); + +jobsClient.SubscribeToGetPendingJobExecutionsRejected( + subscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + err_handler, + publishHandler); + +GetPendingJobExecutionsRequest publishRequest; +publishRequest.ThingName = thingName; + +jobsClient.PublishGetPendingJobExecutions( + publishRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + publishHandler); + +``` + +#### Example of execution of the next pending job in the v1 SDK + +```cpp + const util::Map< util::String, util::String > statusDetailsMap; + jobsClient.SendJobsStartNext(statusDetailsMap); + +``` + +#### Example of execution of the next pending job in the v2 SDK +```cpp +// Gets and starts the next pending job execution for a thing + +auto OnSubscribeToStartNextPendingJobExecutionAcceptedResponse = + [&](StartNextJobExecutionResponse *response, int ioErr) { }; + +auto subAckHandler = [&](int) { }; + +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { }; + +auto publishHandler = [&](int ioErr) { }; + +StartNextPendingJobExecutionSubscriptionRequest subscriptionRequest; +subscriptionRequest.ThingName = ""; + +jobsClient.SubscribeToStartNextPendingJobExecutionAccepted( + subscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + OnSubscribeToStartNextPendingJobExecutionAcceptedResponse, + subAckHandler); + +jobsClient.SubscribeToStartNextPendingJobExecutionRejected( + subscriptionRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + failureHandler, + subAckHandler); + +StartNextPendingJobExecutionRequest publishRequest; +publishRequest.ThingName = cmdData.input_thingName; +publishRequest.StepTimeoutInMinutes = 15L; + +jobsClient.PublishStartNextPendingJobExecution( + publishRequest, + AWS_MQTT_QOS_AT_LEAST_ONCE, + publishHandler); + +``` + +#### Example of getting detailed information about a job execution in the v1 SDK + +```cpp +util::String job_id = "job id"; +int64_t execution_number; -p_jobs_ = Jobs::Create( - p_iot_client_, - mqtt::QoS::QOS1, - "", - client_id_tagged); ResponseCode rc; -rc = p_jobs_->SendJobsQuery(Jobs::JOB_GET_PENDING_TOPIC); -rc = p_jobs_->SendJobsQuery(Jobs::JOB_DESCRIBE_TOPIC, "$next"); +rc = jobsClient.SendJobsDescribe( + job_id, + execution_number, + true); ``` -#### Executing jobs in the v2 SDK +#### Example of getting detailed information about a job execution in the v2 SDK ```cpp -IotJobsClient jobsClient(client); auto subscriptionHandler = [&](DescribeJobExecutionResponse *response, int ioErr) { }; @@ -1080,46 +1266,49 @@ describeJobExecutionRequest.ClientToken = uuid.ToString(); auto publishHandler = [&](int ioErr) { }; jobsClient.PublishDescribeJobExecution( + describeJobExecutionRequest, QTT_QOS_AT_LEAST_ONCE, publishHandler); -auto OnSubscribeToStartNextPendingJobExecutionAcceptedResponse = - [&](StartNextJobExecutionResponse *response, int ioErr) { }; -// Gets and starts the next pending job execution for a thing ( -StartNextPendingJobExecutionSubscriptionRequest subscriptionRequest; -subscriptionRequest.ThingName = ""; +``` -jobsClient.SubscribeToStartNextPendingJobExecutionAccepted( - subscriptionRequest, - AWS_MQTT_QOS_AT_LEAST_ONCE, - OnSubscribeToStartNextPendingJobExecutionAcceptedResponse, - subAckHandler); -jobsClient.SubscribeToStartNextPendingJobExecutionRejected( - subscriptionRequest, - AWS_MQTT_QOS_AT_LEAST_ONCE, - failureHandler, - subAckHandler); +#### Example updating status of a job on the v1 SDK -StartNextPendingJobExecutionRequest publishRequest; -publishRequest.ThingName = cmdData.input_thingName; -publishRequest.StepTimeoutInMinutes = 15L; +```cpp +util::String jobId = "job id"; -jobsClient.PublishStartNextPendingJobExecution( - publishRequest, - AWS_MQTT_QOS_AT_LEAST_ONCE, - publishHandler); +util::Map statusDetailsMap; + +statusDetailsMap.insert(std::make_pair("exampleDetail", "a value appropriate for your successful job")); +rc = jobsClient->SendJobsUpdate(jobId, Jobs::JOB_EXECUTION_SUCCEEDED, statusDetailsMap); +statusDetailsMap.clear(); +statusDetailsMap.insert(std::make_pair("failureDetail", "Unable to process job document")); +rc = jobsClient->SendJobsUpdate(jobId, Jobs::JOB_EXECUTION_FAILED, statusDetailsMap); +``` + +#### Example updating status of a job on the v2 SDK + +```cpp // Send an update about the status of the job -auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { - /* failure callback */ -}; +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) + { + /* failure callback */ + }; -auto subscribeHandler = [&](UpdateJobExecutionResponse *response, int ioErr) { +auto subscribeHandler = [&](UpdateJobExecutionResponse *response, int ioErr) + { -}; + }; -auto publishHandler = [&](int ioErr) { }; +auto subAckHandler = [&](int) + { + }; + +auto publishHandler = [&](int ioErr) + { + }; jobsClient.SubscribeToUpdateJobExecutionAccepted( subscriptionRequest, AWS_MQTT_QOS_AT_LEAST_ONCE, subscribeHandler, subAckHandler); @@ -1141,19 +1330,23 @@ jobsClient.PublishUpdateJobExecution( ``` -For more information, see API documentation for the v2 SDK [AWS IOT Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html).\ -For code examples, see the v2 SDK [Jobs Samples](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/b065b818f955aef6181b2c89815425ea6c5b4194/samples/jobs). +For detailed descriptions for the topics used to interact with the Jobs service, see AWS IoT Core documentation for the +[Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html) service. +For more information about the service clients, see API documentation for the v2 SDK +[Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html). +For code examples, see [Jobs](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/jobs/mqtt5_job_execution) samples. ### Client for AWS IoT fleet provisioning [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) (also known as Identity Service) is another AWS Iot service that the v2 SDK provides access to. -By using AWS IoT fleet provisioning, AWS IoT can generate and securely deliver device certificates and private keys to your devices when they connect to AWS IoT for the first time. +By using AWS IoT fleet provisioning, AWS IoT can generate and securely deliver device certificates and private keys +to your devices when they connect to AWS IoT for the first time. -The Fleet Provisioning service client provides an API similar to API provided by [Client for Device Shadow Service](#client for-device-shadow-service). +The Fleet Provisioning service client provides an API similar to APIs provided by [Client for Device Shadow Service](#client for-device-shadow-service). First, you subscribe to special topics to get data and feedback from a service. -The service client provides API for that. +The service client provides APIs for that. After subscribing to all the required topics, the service client can start interacting with the server, for example, update the status or request for data. These actions are also performed via client API calls. @@ -1161,15 +1354,17 @@ for example, update the status or request for data. These actions are also perfo For detailed descriptions for the topics used to interact with the Fleet Provisioning service, see AWS IoT Core documentation for [Fleet Provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/fleet-provision-api.html). -For more information about the Fleet Provisioning service client, see API documentation for the v2 SDK [Fleet Provisioning](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotidentity.html). - -For code examples, see the v2 SDK [Fleet Provisioning](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/fleet_provisioning/mqtt5_fleet_provisioning) samples. +For more information about the Fleet Provisioning service client, +see API documentation for the v2 SDK [Fleet Provisioning](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotidentity.html). +For code examples, see the v2 SDK [Fleet Provisioning](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/fleet_provisioning/mqtt5_fleet_provisioning) +samples. ### Example -It's always helpful to look at a working example to see how new functionality works, to be able to tweak different options, -to compare with existing code. For that reason, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) +It's always helpful to look at a working example to see how new functionality works, +to be able to tweak different options, to compare with existing code. +For that reason, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub) ([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp)) in the v2 SDK similar to a sample provided by the v1 SDK (see a corresponding [readme section](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/README.md) and @@ -1179,8 +1374,8 @@ in the v2 SDK similar to a sample provided by the v1 SDK (see a corresponding ## How to Get Help Questions? you can look for an answer in the [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions) -page. Or, you can always open a [new -discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions/new?category=q-a&labels=migration), and we will be happy to help you. +page. Or, you can always open a [new discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions/new?category=q-a&labels=migration), +and we will be happy to help you. ## Appendix @@ -1189,11 +1384,13 @@ discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions/new?cat **Clean Start and Session Expiry**\ You can use Clean Start and Session Expiry to handle your persistent sessions with more flexibility. -For more information, see the [Mqtt5ClientOptions.ClientSessionBehavior](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client_options.html#a61d6bedd2502d209db912838f74462bb) enum and [NegotiatedSettings.getSessionExpiryInterval](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#aed6565927dcc2ecfb789f978f5a1aee4) method. +For more information, see the [Mqtt5ClientOptions.ClientSessionBehavior](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client_options.html#a61d6bedd2502d209db912838f74462bb) enum and [NegotiatedSettings.getSessionExpiryInterval](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#aed6565927dcc2ecfb789f978f5a1aee4) +method. **Reason Code on all ACKs**\ You can debug or process error messages more easily using the reason codes. -Reason codes are returned by the message broker based on the type of interaction with the broker (Subscribe, Publish, Acknowledge). +Reason codes are returned by the message broker based on the type of interaction with +the broker (Subscribe, Publish, Acknowledge). For more information, see [PubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a5901f1fc1e66ef0f859402b747630a02), [SubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a272e5b89320326afd9e0de269100ccd3), [UnsubAckReasonCode](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a0fece0c83f48d577ea7dfafe58f1261a), @@ -1211,8 +1408,10 @@ Use [withMessageExpiryIntervalSeconds](https://aws.github.io/aws-iot-device-sdk- method in PublishPacketBuilder class. **Server disconnect**\ -When a disconnection happens, the server can proactively send the client a DISCONNECT to notify connection closure with a reason code for disconnection. -For more information, see the [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) class. +When a disconnection happens, the server can proactively send the client a DISCONNECT to notify connection closure +with a reason code for disconnection.\ +For more information, see the [DisconnectPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_disconnect_packet.html) +class. **Request/Response**\ Publishers can request a response be sent by the receiver to a publisher-specified topic upon reception. @@ -1220,10 +1419,11 @@ Use [withResponseTopic](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aw method in PublishPacketBuilder class. **Maximum Packet Size**\ -Client and Server can independently specify the maximum packet size that they support. +Client and Server can independently specify the maximum packet size that they support.\ For more information, see the [connectPacketBuilder.withMaximumPacketSizeBytes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a88ec9f83510875c5cd92277ecc439bad), [NegotiatedSettings.getMaximumPacketSizeToServer](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_connect_packet.html#a25670e9f1c004d93b3332cd432689b92), -and [ConnAckPacket.getMaximumPacketSize](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#a83a5f4aaa007bdf6dddc41c718d0bfd6) methods. +and [ConnAckPacket.getMaximumPacketSize](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_conn_ack_packet.html#a83a5f4aaa007bdf6dddc41c718d0bfd6) +methods. **Payload format and content type**\ You can specify the payload format (binary, text) and content type when a message is published. @@ -1232,9 +1432,13 @@ Use the [withContentType](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_ method in PublishPacketBuilder class. **Shared Subscriptions**\ -Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. -For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) in the v2 SDK. ->[!NOTE] ->AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see ->[Shared Subscriptions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription) from the AWS IoT Core developer guide +Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client +will receive messages published to that topic using a random distribution.\ +For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md) +in the v2 SDK. + +> [!NOTE] +> AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see +> [Shared Subscriptions](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription) +> from the AWS IoT Core developer guide From 1041f4eed78cfea44cbe7ffce9ee21af1484812d Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 15 Feb 2024 20:19:13 -0800 Subject: [PATCH 26/33] add comments to job lambdas --- documents/MIGRATION_GUIDE.md | 52 ++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index ca3b92909..f937fdf1c 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -1180,13 +1180,20 @@ jobsClient.PublishGetPendingJobExecutions( // Gets and starts the next pending job execution for a thing auto OnSubscribeToStartNextPendingJobExecutionAcceptedResponse = - [&](StartNextJobExecutionResponse *response, int ioErr) { }; - -auto subAckHandler = [&](int) { }; + [&](StartNextJobExecutionResponse *response, int ioErr) + { + /* callback received on successfull reception of data or ioErr is set */ + }; -auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { }; +auto subAckHandler = [&](int ioErr) + { + /* callback received when the server accepts the request */ + }; -auto publishHandler = [&](int ioErr) { }; +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) + { + /* callback received on error */ + }; StartNextPendingJobExecutionSubscriptionRequest subscriptionRequest; subscriptionRequest.ThingName = ""; @@ -1210,7 +1217,7 @@ publishRequest.StepTimeoutInMinutes = 15L; jobsClient.PublishStartNextPendingJobExecution( publishRequest, AWS_MQTT_QOS_AT_LEAST_ONCE, - publishHandler); + subAckHandler); ``` @@ -1233,9 +1240,17 @@ rc = jobsClient.SendJobsDescribe( ```cpp auto subscriptionHandler = [&](DescribeJobExecutionResponse *response, int ioErr) -{ }; -auto subAckHandler = [&](int) -{ }; + { + /* callback received on successfull operation */ + }; +auto subAckHandler = [&](int ioErr) + { + /* callback received when the server accepts the request */ + }; +auto failureHandler = [&](RejectedError *rejectedError, int ioErr) + { + /* callback received on error */ + }; // Get information about the job DescribeJobExecutionSubscriptionRequest describeJobExecutionSubscriptionRequest; @@ -1248,8 +1263,6 @@ jobsClient.SubscribeToDescribeJobExecutionAccepted( subscriptionHandler, subAckHandler); -auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { }; - jobsClient.SubscribeToDescribeJobExecutionRejected( describeJobExecutionSubscriptionRequest, AWS_MQTT_QOS_AT_LEAST_ONCE, @@ -1263,12 +1276,10 @@ describeJobExecutionRequest.IncludeJobDocument = true; Aws::Crt::UUID uuid; describeJobExecutionRequest.ClientToken = uuid.ToString(); -auto publishHandler = [&](int ioErr) { }; - jobsClient.PublishDescribeJobExecution( describeJobExecutionRequest, QTT_QOS_AT_LEAST_ONCE, - publishHandler); + subAckHandler); ``` @@ -1294,20 +1305,15 @@ rc = jobsClient->SendJobsUpdate(jobId, Jobs::JOB_EXECUTION_FAILED, statusDetails // Send an update about the status of the job auto failureHandler = [&](RejectedError *rejectedError, int ioErr) { - /* failure callback */ + /* callback received on error */ }; - auto subscribeHandler = [&](UpdateJobExecutionResponse *response, int ioErr) { - + /* callback received on success */ }; - auto subAckHandler = [&](int) { - }; - -auto publishHandler = [&](int ioErr) - { + /* callback received when the server accepts the request */ }; jobsClient.SubscribeToUpdateJobExecutionAccepted( @@ -1326,7 +1332,7 @@ publishRequest.ExpectedVersion = 0 jobsClient.PublishUpdateJobExecution( publishRequest, AWS_MQTT_QOS_AT_LEAST_ONCE, - publishHandler); + subAckHandler); ``` From b269eb73243ad35f74e07de12c7c466b98189e45 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 15 Feb 2024 20:22:20 -0800 Subject: [PATCH 27/33] Fix quoted links --- documents/MIGRATION_GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index f937fdf1c..941af4e23 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -302,7 +302,7 @@ object containing a description of the PUBLISH packet. The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation takes a `PublishPacket` instance and a [Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) -that contains a returned [`PublishResult`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) +that contains a returned [PublishResult](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_result.html) in its parameter that will contain different data depending on the `QoS` used in the publish. > [!NOTE] @@ -631,7 +631,7 @@ Mqtt5Client client = builder->Build(); > [!Note] > AWS IoT Core [limits the number of allowed operations per second](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). -The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) +The [getOperationStatistics](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object's queue of operations, which may help with tracking the number of in-flight messages. @@ -664,7 +664,7 @@ In the v2 SDK, operations timeout is set for the MQTT5 client with the builder m The default value is no timeout. As in the v1 SDK, failing to set a timeout can cause an operation to stuck forever, but it won't block the client. -The [`getOperationStatistics`](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) +The [getOperationStatistics](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#aa9bf915cfbcfc80b4dc47bbda3529f72) method returns the current state of an `Mqtt5Client` object's queue of operations, which may help with tracking operations. From 5c0c444b1d37fdc720719cff5e8e2aa17892fc5f Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 15 Feb 2024 20:33:48 -0800 Subject: [PATCH 28/33] Fix capitalization --- documents/MIGRATION_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 941af4e23..94f9fab24 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -12,7 +12,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S * [What's new in AWS IoT Device SDK for C++ v2](#whats-new-in-aws-iot-device-sdk-for-c-v2) * [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c-v2) * [Mqtt protocol](#mqtt-protocol) - * [client builder](#client-builder) + * [Client builder](#client-builder) * [Client Start](#client-start) * [Connection types and features](#connection-types-and-features) * [Lifecycle events](#lifecycle-events) From c9bd7e552a012dfa2c91167119ff71b3202f0f30 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 16 Feb 2024 07:37:16 -0800 Subject: [PATCH 29/33] fix typo and table --- documents/MIGRATION_GUIDE.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 94f9fab24..8a941d1d3 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -57,7 +57,6 @@ The v2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementatio This guide focuses on the MQTT5 because this version is significant improvement over MQTT3. For more information see the [MQTT5 features]($mqtt5-features) section. - ### Client Builder To access the AWS IoT service, you must initialize an MQTT client. @@ -167,16 +166,16 @@ and other connection-related features. For more information, refer to the [Connecting To AWS IoT Core](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#connecting-to-aws-iot-core) section of the MQTT5 user guide for detailed information and code snippets on each connection type and connection feature. -| Connection type/feature | v1 SDK | v2 SDK | User guide | -|----------------------------------------------------------|-----------------------------------------|----------------------------------|:----------:| -| MQTT over Secure WebSocket with AWS SigV4 authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-sigv4-authentication) | -| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | -| MQTT with X.509 certificate based mutual authentication | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-x509-based-mutual-tls) | -| MQTT with PKCS12 Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs12-method) | -| MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authentication) | -| MQTT with Windows Certificate Store Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-windows-certificate-store-method) | -| MQTT with PKCS11 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs11-method) | -| HTTP Proxy | $${\Large\color{orange}✔\*\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#adding-an-http-proxy) | +| Connection type/feature | v1 SDK | v2 SDK | User guide | +|----------------------------------------------------------|---------------------------------------|----------------------------------|:----------:| +| MQTT over Secure WebSocket with AWS SigV4 authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-sigv4-authentication) | +| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | +| MQTT with X.509 certificate based mutual authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-x509-based-mutual-tls) | +| MQTT with PKCS12 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs12-method) | +| MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authentication) | +| MQTT with Windows Certificate Store Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-windows-certificate-store-method) | +| MQTT with PKCS11 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs11-method) | +| HTTP Proxy | $${\Large\color{orange}✔\*\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#adding-an-http-proxy) | ${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ From 434b28fad556b11fb0d5a33dfe78a38b9c68ab84 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 16 Feb 2024 07:41:53 -0800 Subject: [PATCH 30/33] Remove extra lines --- documents/MIGRATION_GUIDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 8a941d1d3..6c76ae3c0 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -143,12 +143,14 @@ the semantinc confusion between client-level controls and internal recurrent net ```cpp std::shared_ptrclient = std::shared_ptr(MqttClient::Create(p_network_connection, ...); client.Connect(); + ``` #### Example of connecting to a server in the v2 SDK ```cpp std::shared_ptr client = builder->Build(); client.Start(); + ``` ### Connection Types and Features @@ -181,7 +183,6 @@ ${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 S [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ ${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP proxy, but systemwide proxy - ### Lifecycle Events Both v1 and v2 SDKs provide lifecycle events for the MQTT clients. From ebe0a49e25f08f6d4dc9813deec26ee44d1cf4a8 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 16 Feb 2024 08:38:16 -0800 Subject: [PATCH 31/33] more fixes --- documents/MIGRATION_GUIDE.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 6c76ae3c0..f9e32a14c 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -298,7 +298,7 @@ If you try to publish to a topic that is not allowed by a policy, AWS IoT Core s The v2 SDK provides only asynchronous non-blocking API. Begin by creeating a [PublishPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_publish_packet.html) -object containing a description of the PUBLISH packet. +object that contains a description of the PUBLISH packet. The [publish](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_mqtt5_client.html#a5f1214d3a574d91e1db7c97f8636de96) operation takes a `PublishPacket` instance and a [Aws::Crt::Mqtt5::OnPublishCompletionHandler](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#a6c8e5bc5d3a6eb7f4767f3c1ecd8524c) @@ -311,13 +311,13 @@ in its parameter that will contain different data depending on the `QoS` used in > closed but instead receive a PUBACK with a reason code. * For QoS 0 (AT\_MOST\_ONCE): Calling `getValue` will return `null` - and the promise will be complete as soon as the packet has been written to the socket. + and the callback will happen as soon as the packet has been written to the socket. * For QoS 1 (AT\_LEAST\_ONCE): Calling `getValue` will return a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) - and the promise will be complete as soon as the PUBACK is received from the broker. + and the callback will happen as soon as the PUBACK is received from the broker. If the operation fails for any reason before these respective completion events, -the promise is rejected with a descriptive error. You should always check the reason code of a +the failure callback is called with a descriptive error. You should always check the reason code of a [PubAckPacket](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_crt_1_1_mqtt5_1_1_pub_ack_packet.html) completion to determine if a QoS 1 publish operation actually succeeded. @@ -575,8 +575,7 @@ client->Stop(); The v1 SDK attempts to reconnect automatically until connection succeeds or `client.Disconnect()` is called -The v2 SDK attempts to reconnect automatically until connection succeeds or `client.Stop()` is called, -either the initial `client.Start()` succeeds or fails. +The v2 SDK attempts to reconnect automatically until connection succeeds or `client.Stop()` is called The reconnection parameters, such as min/max delays and [jitter modes](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_crt_1_1_mqtt5.html#ab88e42f90f56a82b1af57320ffadbafd), are configurable through [Aws::Crt::Mqtt5::ReconnectOptions](https://aws.github.io/aws-iot-device-sdk-cpp-v2/struct_aws_1_1_crt_1_1_mqtt5_1_1_reconnect_options.html). @@ -758,7 +757,7 @@ In the v2 SDK, logging is shutdown automatically with ApiHandle destruction when The v1 SDK is built with [AWS IoT device shadow support](http://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-shadows.html), which provides access to thing shadows (sometimes referred to as device shadows). -The v2 SDK also supports device shadow service, but with completely different API. +The v2 SDK also supports device shadow service, but with completely different APIs. First, you subscribe to special topics to get data and feedback from a service. The service client provides API for that. For example, `SubscribeToGetShadowAccepted` subscribes to a topic to which AWS IoT Core will publish a shadow document. The server will notify you if it cannot send you a requested document and via the `SubscribeToGetShadowRejected`.\ @@ -773,11 +772,11 @@ service provides detailed descriptions for the topics used to interact with the #### Example of creating a Device Shadow service client in the v1 SDK ```cpp -#include "shadow/Shadow.hpp" // Blocking and non-blocking API. String thingName = ""; std::chrono::milliseconds mqtt_command_timeout = 200; ResponseCode rc = client->Connect(/* ... */); + // 1st way Shadow shadowClient( client, @@ -879,7 +878,7 @@ shadowSubscriptionRequest.ThingName = ""; auto onGetShadowAccepted = [&](GetShadowResponse *response, int ioErr) { /* shadow document received. */ - /* The `response` object contains the shadow document. */ + /* The response object contains the shadow document. */ }; auto onGetShadowUpdatedAcceptedSubAck = [&](int ioErr) { }; auto onGetShadowRejected = [&](ErrorResponse *error, int ioErr) { @@ -1341,6 +1340,7 @@ For detailed descriptions for the topics used to interact with the Jobs service, For more information about the service clients, see API documentation for the v2 SDK [Jobs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/namespace_aws_1_1_iotjobs.html). + For code examples, see [Jobs](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/jobs/mqtt5_job_execution) samples. ### Client for AWS IoT fleet provisioning From 7526dab8821f93bb8d9a1488284337a0f8ada100 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Fri, 16 Feb 2024 13:34:03 -0800 Subject: [PATCH 32/33] fix --- documents/MIGRATION_GUIDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index f9e32a14c..941f09323 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -1175,6 +1175,7 @@ jobsClient.PublishGetPendingJobExecutions( ``` #### Example of execution of the next pending job in the v2 SDK + ```cpp // Gets and starts the next pending job execution for a thing From da4e0eff867d0f620d56c1ed625fba1e4b84ab26 Mon Sep 17 00:00:00 2001 From: Alfred Gedeon Date: Thu, 22 Feb 2024 16:59:16 -0800 Subject: [PATCH 33/33] fix comments --- documents/MIGRATION_GUIDE.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md index 941f09323..3dc23cf80 100644 --- a/documents/MIGRATION_GUIDE.md +++ b/documents/MIGRATION_GUIDE.md @@ -13,19 +13,19 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S * [How to get started with the SDK for C++ v2](#how-to-get-started-with-the-sdk-for-c-v2) * [Mqtt protocol](#mqtt-protocol) * [Client builder](#client-builder) - * [Client Start](#client-start) + * [Client start](#client-start) * [Connection types and features](#connection-types-and-features) * [Lifecycle events](#lifecycle-events) * [Publish](#publish) * [Subscribe](#subscribe) * [Unsubscribe](#unsubscribe) - * [Client Stop](#client-stop) + * [Client stop](#client-stop) * [Reconnects](#reconnects) * [Offline operations queue](#offline-operations-queue) * [Operation timeouts](#operation-timeouts) * [Logging](#logging) * [Client for AWS IOT Device Shadow](#client-for-aws-iot-device-shadow) - * [Client for AWS_IOT Jobs](#client-for-aws-iot-jobs) + * [Client for AWS IOT Jobs](#client-for-aws-iot-jobs) * [Client for AWS IOT fleet provisioning](#client-for-aws-iot-fleet-provisioning) * [Example](#example) * [How to get help](#how-to-get-help) @@ -40,7 +40,7 @@ and provides guidance on how to migrate your code to v2 from v1 of the AWS Iot S by calling `promise.set_value() `and then waiting for the returned `std::future<>` object to be resolved by calling `promise.get_future().wait()` * The v2 SDK provides implementation for MQTT5 protocol, the next step in evolution of the MQTT protocol. -* The v2 SDK Supports AWS_ IoT services such as for fleet provisioning. +* The v2 SDK supports the fleet provisioning AWS IoT service. ## How To get started with the SDK for C++ v2 @@ -55,7 +55,7 @@ The v1 SDK uses an MQTT version 3.1.1 client under the hood. The v2 SDK provides MQTT version 3.1.1 and MQTT version 5.0 client implementations. This guide focuses on the MQTT5 because this version is significant improvement over MQTT3. -For more information see the [MQTT5 features]($mqtt5-features) section. +For more information see the [MQTT5 features](#mqtt5-features) section. ### Client Builder @@ -133,8 +133,8 @@ std::shared_ptr client = builder->Build(); For more information, refer to the [Connection Types and Features](#connection-types-and-features) section for other connection types supported by the v2 SDK. -### Client Start -To connect to the server in the v1 SDK, you call the `connect` method on an `MQTTClient` instance. +### Client start +To connect to the server in the v1 SDK, you call the `connect` method on an `MqttClient` instance. The v2 SDK changed API terminology. You `Start` the MQTT5 client rather than `Connect` as in the v1 SDK. This removes the semantinc confusion between client-level controls and internal recurrent networking events related to connection. @@ -171,8 +171,8 @@ section of the MQTT5 user guide for detailed information and code snippets on ea | Connection type/feature | v1 SDK | v2 SDK | User guide | |----------------------------------------------------------|---------------------------------------|----------------------------------|:----------:| | MQTT over Secure WebSocket with AWS SigV4 authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-sigv4-authentication) | -| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | | MQTT with X.509 certificate based mutual authentication | $${\Large\color{green}✔}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-x509-based-mutual-tls) | +| Websocket Connection with Cognito Authentication Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#mqtt-over-websockets-with-cognito) | | MQTT with PKCS12 Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-pkcs12-method) | | MQTT with Custom Authorizer Method | $${\Large\color{orange}✔\*}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-custom-authentication) | | MQTT with Windows Certificate Store Method | $${\Large\color{red}✘}$$ | $${\Large\color{green}✔}$$ | [link](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/documents/MQTT5_Userguide.md#direct-mqtt-with-windows-certificate-store-method) | @@ -181,7 +181,8 @@ section of the MQTT5 user guide for detailed information and code snippets on ea ${\Large\color{orange}✔\*}$ - To get this connection type work in the v1 SDK, you need to implement the [Custom Authentication workflow](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authorizer.html).\ -${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow to specify HTTP proxy, but systemwide proxy +${\Large\color{orange}✔\*\*}$ - The v1 SDK does not allow specifying HTTP proxy, but it is possible to configure +systemwide proxy. ### Lifecycle Events @@ -192,10 +193,9 @@ The v1 SDK provides three lifecycle events: *ClientCoreState::ApplicationResubsc You can supply a custom callback function via the function `Create`. It is recommended to use lifecycle events callbacks to help determine the state of the MQTT client during operation. -The v2 SDK add 3 new lifecycle events and removes one(Resubscribe Callback), -providing 5 lifecycle events in total: *WithClientConnectionSuccessCallback*, -*WithClientConnectionFailureCallback*, *WithClientDisconnectionCallback*, *WithClientStoppedCallback*, -and *WithClientAttemptingConnectCallback*. +The v2 SDK provides a different set of the lifecycle events: providing 5 lifecycle events in total: +*WithClientConnectionSuccessCallback*, *WithClientConnectionFailureCallback*, *WithClientDisconnectionCallback*, +*WithClientStoppedCallback*, and *WithClientAttemptingConnectCallback*. It is also recommended to use lifecycle events callbacks on the v2 SDK. For more information, @@ -543,7 +543,7 @@ bool rc = client->Unsubscribe(unsub, unsubAck); ``` -### Client Stop +### Client stop In the v1 SDK, the `Disconnect` method in the `AWSIotMqttClient` class disconnects the client. Once disconnected, the client can connect again by calling `Connect`.