Migrate Mqtt5ClientBuilder from deprecated New* to Create* APIs

documents/MIGRATION_GUIDE.md

@@ -100,26 +100,25 @@ std::shared_ptr<MqttClient>client = std::shared_ptr<MqttClient>(
                 mqtt_timeout,
                 /* disconnect handler */, nullptr,
                 /* reconnect handler */, nullptr,
-                /* resubscribe handler */, nullptr);
+                /* resubscribe handler */, nullptr));
 ```
 
 #### Example of creating a client in the v2 SDK
 
 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).
+the most recommended method to create an MQTT5 client will be [CreateMqtt5ClientBuilderWithMtlsFromPath](https://aws.github.io/aws-iot-device-sdk-cpp-v2/class_aws_1_1_iot_1_1_mqtt5_client_builder.html#a21c365a232be4447b21eb56cc55d4b62).
 
 ```cpp
 util::String clientEndpoint = "<prefix>-ats.iot.<region>.amazonaws.com";
 util::String certificateFile = "<certificate file>";  // X.509 based certificate file
 util::String privateKeyFile = "<private key file>";   // PEM encoded private key file
-uint32_t clientPort = <port number>
+uint32_t clientPort = <port number>;
 String client_id = "unique client id";
 
-std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder(
-            Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(
-                    clientEndpoint,
-                    certificateFile,
-                    privateKeyFile));
+std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder =
+        Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(
+                clientEndpoint, certificateFile.c_str(), privateKeyFile.c_str());
+
 std::shared_ptr<Mqtt5::ConnectPacket> connectOptions =
         Aws::Crt::MakeShared<Mqtt5::ConnectPacket>(Aws::Crt::DefaultAllocatorImplementation());
 util::String clientId = "client_id";

documents/MQTT5_Userguide.md

@@ -17,8 +17,8 @@
         - [Direct MQTT with Custom Authentication](#direct-mqtt-with-custom-authentication)
         - [MQTT over Websockets with Cognito](#mqtt-over-websockets-with-cognito)
         - [Direct MQTT with Windows Certificate Store Method](#direct-mqtt-with-windows-certificate-store-method)
-        - [Direct MQTT with PKCS11 Method](#direct-mqtt-with-pkcs11-method)
-        - [Direct MQTT with pkcs12 method](#direct-mqtt-with-pkcs12-method)
+        - [Direct MQTT with PKCS11 Method (Unix Only)](#direct-mqtt-with-pkcs11-method-unix-only)
+        - [Direct MQTT with pkcs12 method (macOS Only)](#direct-mqtt-with-pkcs12-method-macos-only)
     + [Adding an HTTP Proxy](#adding-an-http-proxy)
     + [Client Operations](#client-operations)
         - [Subscribe](#subscribe)
@@ -81,7 +81,7 @@ Example:
     std::shared_ptr<Mqtt5Client> client = nullptr;
 
     // Create Mqtt5Client Builder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(...);
+    std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(...);
 
     // Setup lifecycle callbacks
     builder->WithClientConnectionSuccessCallback(
@@ -115,10 +115,10 @@ Once a MQTT5 client builder has been created, it is ready to make a [MQTT5 clien
 ```cpp
 
     // Create Mqtt5Client Builder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(...);
+    std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(...);
 
     // Build Mqtt5Client
-    std::shared_ptr<Aws::Crt::Mqtt5Client> client = builder->Build();
+    std::shared_ptr<Aws::Crt::Mqtt5::Mqtt5Client> client = builder->Build();
 
     if (mqtt5Client == nullptr)
     {
@@ -142,7 +142,7 @@ The MQTT5 client emits a set of events related to state and network status chang
 ```cpp
 
     // Create Mqtt5Client Builder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(...);
+    std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(...);
 
 
     /* setup lifecycle event callbacks */
@@ -181,7 +181,7 @@ The MQTT5 client emits a set of events related to state and network status chang
         });
 
     // Build Mqtt5Client
-    std::shared_ptr<Aws::Crt::Mqtt5Client> client = builder->Build();
+    std::shared_ptr<Aws::Crt::Mqtt::Mqtt5Client> client = builder->Build();
 
     if (mqtt5Client == nullptr)
     {
@@ -253,7 +253,7 @@ Emitted once the client has shutdown any associated network connection and enter
 
 ```cpp
     // Create Mqtt5Client Builder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(...);
+    std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(...);
 
     builder->WithPublishReceivedCallback([](const Mqtt5::PublishReceivedEventData &eventData) {
         if (eventData.publishPacket == nullptr)
@@ -263,7 +263,7 @@ Emitted once the client has shutdown any associated network connection and enter
         fprintf(stdout, "\n");
     });
 
-    std::shared_ptr<Aws::Crt::Mqtt5Client> client = builder->Build();
+    std::shared_ptr<Aws::Crt::Mqtt::Mqtt5Client> client = builder->Build();
 ```
 
 
@@ -277,10 +277,10 @@ Invoking `start()` on the client will put it into an active state where it recur
 ```cpp
 
     // Create Mqtt5Client Builder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(...);
+     std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(...);
 
     // Build Mqtt5Client
-    std::shared_ptr<Aws::Crt::Mqtt5Client> client = builder->Build();
+    std::shared_ptr<Aws::Crt::Mqtt::Mqtt5Client> client = builder->Build();
 
     if (mqtt5Client == nullptr)
     {
@@ -322,16 +322,17 @@ For X509 based mutual TLS, you can create a client where the certificate and pri
 
 ```cpp
     // Create a Client using Mqtt5ClientBuilder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(
-        "<clientEndpoint>", "<certificateFilePath>", "<privateKeyFilePath>");
+    std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder =
+        Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(
+            "<clientEndpoint>", "<certificateFilePath>", "<privateKeyFilePath>");
 
     /* You can setup other client options and lifecycle event callbacks before call builder->Build().
     ** Once the the client get built, you could no longer update the client options or connection options
     ** on the created client.
     */
 
     // Build Mqtt5Client
-    std::shared_ptr<Aws::Crt::Mqtt5Client> client = builder->Build();
+    std::shared_ptr<Aws::Crt::Mqtt5::Mqtt5Client> client = builder->Build();
 
     if (client == nullptr)
     {
@@ -369,16 +370,17 @@ If the default credentials provider chain and AWS region are specified, you do n
     Aws::Iot::WebsocketConfig websocketConfig(<signing region>, provider);
 
     // Create a Client using Mqtt5ClientBuilder
-    Aws::Iot::Mqtt5ClientBuilder *builder = Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithWebsocket(
-        "<clientEndpoint>", websocketConfig);
+    std::shared_ptr<Aws::Iot::Mqtt5ClientBuilder> builder =
+        Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithWebsocket(
+            "<clientEndpoint>", websocketConfig);
 
     /* You can setup other client options and lifecycle event callbacks before call builder->Build().
     ** Once the the client get built, you could no longer update the client options or connection options
     ** on the created client.
     */
 
     // Build Mqtt5Client
-    std::shared_ptr<Aws::Crt::Mqtt5Client> mqtt5Client = builder->Build();
+    std::shared_ptr<Aws::Crt::Mqtt5::Mqtt5Client> mqtt5Client = builder->Build();
 
     if (mqtt5Client == nullptr)
     {
@@ -545,7 +547,7 @@ store, rather than simply being files on disk. To create a MQTT5 builder configu
 Note: This is the primary way to use HSM/TPMs on Windows.
 Note: Windows Certificate Store connection support is only available on Windows devices.
 
-### Direct MQTT with PKCS11 Method
+### Direct MQTT with PKCS11 Method (Unix Only)
 
 A MQTT5 direct connection can be made using a PKCS11 device rather than using a PEM encoded private key,
 the private key for mutual TLS is stored on a PKCS#11 compatible smart card or Hardware Security Module (HSM).
@@ -581,7 +583,7 @@ the private key for mutual TLS is stored on a PKCS#11 compatible smart card or H
 ```
 Note: Currently, TLS integration with PKCS#11 is only available on Unix devices.
 
-### Direct MQTT with PKCS12 Method
+### Direct MQTT with PKCS12 Method (macOS Only)
 A MQTT5 direct connection can be made using a PKCS12 file rather than using a PEM encoded private key.
 To create a MQTT5 builder configured for this connection, see the following code:
 ```cpp

samples/mqtt/mqtt5_aws_websocket/README.md

@@ -66,6 +66,11 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 </details>
 
+### Determining your signing region
+
+The `signing_region` parameter specifies the AWS region used to sign WebSocket connection requests via [SigV4 authentication](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). It must match the region of your AWS IoT Core endpoint.
+For example, if your endpoint is `abcdef12345-ats.iot.us-west-2.amazonaws.com`, the signing region is `us-west-2`.
+
 ## How to build
 
 To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/mqtt/mqtt5_aws_websocket/build` folder.

samples/mqtt/mqtt5_aws_websocket/main.cpp

@@ -134,9 +134,8 @@ int main(int argc, char *argv[])
     Aws::Iot::WebsocketConfig websocketConfig(cmdData.signingRegion, provider);
 
     // Create a Client using Mqtt5ClientBuilder
-    auto builder = std::unique_ptr<Aws::Iot::Mqtt5ClientBuilder>(
-        Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithWebsocket(
-            cmdData.endpoint, websocketConfig));
+    auto builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithWebsocket(
+        cmdData.endpoint, websocketConfig);
 
     // Check if the builder setup correctly.
     if (builder == nullptr)

samples/mqtt/mqtt5_x509/main.cpp

@@ -126,9 +126,8 @@ int main(int argc, char *argv[])
      * Create MQTT5 client builder using mutual TLS via X509 Certificate and Private Key,
      * The builder will be used to create the final client
      */
-    auto builder = std::unique_ptr<Aws::Iot::Mqtt5ClientBuilder>(
-        Aws::Iot::Mqtt5ClientBuilder::NewMqtt5ClientBuilderWithMtlsFromPath(
-            cmdData.endpoint, cmdData.cert.c_str(), cmdData.key.c_str()));
+    auto builder = Aws::Iot::Mqtt5ClientBuilder::CreateMqtt5ClientBuilderWithMtlsFromPath(
+        cmdData.endpoint, cmdData.cert.c_str(), cmdData.key.c_str());
 
     // Check if the builder setup correctly.
     if (builder == nullptr)