manual puback instructions

README.md

@@ -24,6 +24,7 @@ The primary purpose of the AWS IoT Device SDK for C++ v2 is to simplify the proc
 * Integrated service clients for AWS IoT Core services
 * Secure device connections to AWS IoT Core using MQTT protocol including MQTT 5.0
 * Support for [multiple authentication methods and connection types](./documents/MQTT5_Userguide.md#connecting-to-aws-iot-core)
+* Support for [manual publish acknowledgement](./documents/MQTT5_Userguide.md#manual-publish-acknowledgement) for control over QoS 1 PUBACK delivery
 
 #### Supported AWS IoT Core services
 

documents/FAQ.md

@@ -14,6 +14,7 @@
 * [What certificates do I need?](#what-certificates-do-i-need)
 * [Where can I find MQTT 311 Samples?](#where-can-i-find-mqtt-311-samples)
 * [Certificate and Private Key Usage Across Different Versions of the SDK on macOS](#certificate-and-private-key-usage-across-different-versions-of-the-sdk-on-macos)
+* [Manual Publish Acknowledgement and QoS 1 Redelivery](#manual-publish-acknowledgement-and-qos-1-redelivery)
 * [I still have more questions about this sdk?](#i-still-have-more-questions-about-this-sdk)
 
 ### Where should I start?
@@ -180,6 +181,18 @@ The MQTT 3.1.1 samples can be found in the v1.40.0 samples folder [here](https:/
 ### Certificate and Private Key Usage Across Different Versions of the SDK on macOS
 A certificate and private key pair cannot be shared on a macOS device between aws-iot-device-sdk-cpp-v2 v1.41.0 and any other versions. In the update to v1.41.0 we migrated macOS from using Apple's deprecated Security Framework to SecItem API. In doing so, certificate and private keys are imported in a non-backwards compatible manner into the Apple Keychain.
 
+### Manual Publish Acknowledgement and QoS 1 Redelivery
+
+When using [manual publish acknowledgement](./MQTT5_Userguide.md#manual-publish-acknowledgement), there are two important behaviors to be aware of regarding QoS 1 message redelivery:
+
+**Broker redelivery of unacknowledged publishes**
+
+The AWS IoT broker will periodically resend unacknowledged QoS 1 PUBLISH packets. These redeliveries should be treated as duplicates even if the DUP flag in the PUBLISH packet is not set. If the manual publish acknowledgement is not acquired again for a redelivered packet, the acknowledgement will be sent automatically.
+
+**Session resumption after disconnect/reconnect**
+
+Upon a disconnect and reconnect of the MQTT5 client, if a session is resumed, any previously acquired acknowledgement handle is void. The broker will resend the unacknowledged PUBLISH packet, and the acknowledgement must be reacquired from that resent packet. If the resent packet is not handled for manual acknowledgement, the acknowledgement will be sent automatically.
+
 ### I still have more questions about this SDK?
 
 * [Here](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) are the AWS IoT Core docs for more details about IoT Core

documents/MQTT5_Userguide.md

@@ -24,6 +24,8 @@
         - [Subscribe](#subscribe)
         - [Unsubscribe](#unsubscribe)
         - [Publish](#publish)
+* [Advanced Operations and Settings](#advanced-operations-and-settings)
+    + [Manual Publish Acknowledgement](#manual-publish-acknowledgement)
 * [MQTT5 Best Practices](#mqtt5-best-practices)
 
 # Introduction
@@ -757,6 +759,73 @@ If the PUBLISH was a QoS 1 publish, then the completion callback returns a PubAc
 ```
 
 
+## Advanced Operations and Settings
+
+### Manual Publish Acknowledgement
+
+By default, the MQTT5 client automatically sends a PUBACK for every QoS 1 PUBLISH it receives, immediately after the `OnPublishReceivedHandler` callback returns. Manual publish acknowledgement gives you control over when that PUBACK is sent, allowing you to defer acknowledgement until after your application has fully processed the message — for example, after persisting it to a database or forwarding it to another service.
+
+To take manual control of the PUBACK, call `eventData.acquirePublishAcknowledgement()` **within** the `OnPublishReceivedHandler` callback. This returns a `ScopedResource<PublishAcknowledgementHandle>` that you can store and use later to send the PUBACK by calling `client->InvokePublishAcknowledgement()`.
+
+**Important constraints:**
+* `acquirePublishAcknowledgement()` must be called within the `OnPublishReceivedHandler` callback. Calling it after the callback returns or from a different thread will return `nullptr`.
+* `acquirePublishAcknowledgement()` may only be called once per received PUBLISH. Subsequent calls return `nullptr`.
+* This is only relevant for QoS 1 messages. For QoS 0 messages, `acquirePublishAcknowledgement()` returns `nullptr`.
+* If `acquirePublishAcknowledgement()` is not called (or returns `nullptr`), the client will automatically send the PUBACK when the callback returns.
+
+The following example shows how to acquire the acknowledgement handle within the callback and invoke it later:
+
+```cpp
+    // A shared location to store the acknowledgement handle for later use
+    Crt::ScopedResource<Mqtt5::PublishAcknowledgementHandle> pendingAck;
+
+    // Set the publish received callback on the builder
+    builder->WithPublishReceivedCallback(
+        [&pendingAck](const Mqtt5::PublishReceivedEventData &eventData) {
+            if (eventData.publishPacket == nullptr)
+                return;
+
+            fprintf(stdout, "Publish received on topic %s\n",
+                eventData.publishPacket->getTopic().c_str());
+
+            // Acquire manual control of the PUBACK for this QoS 1 message.
+            // This must be called within the callback. After the callback returns,
+            // acquirePublishAcknowledgement() will return nullptr.
+            pendingAck = eventData.acquirePublishAcknowledgement();
+
+            if (pendingAck == nullptr)
+            {
+                // QoS 0 message or acknowledgement already taken — nothing to do.
+                return;
+            }
+
+            // The PUBACK will NOT be sent automatically because we acquired the handle.
+        });
+
+    std::shared_ptr<Aws::Crt::Mqtt5Client> client = builder->Build();
+
+    // ... connect, subscribe, and receive messages ...
+
+    // After processing is complete, send the PUBACK by invoking the acknowledgement.
+    if (pendingAck != nullptr)
+    {
+        if (!client->InvokePublishAcknowledgement(*pendingAck))
+        {
+            fprintf(stdout, "Failed to invoke publish acknowledgement.\n");
+        }
+    }
+
+```
+
+**AWS IoT broker redelivery behavior**
+
+The AWS IoT broker will periodically resend unacknowledged QoS 1 PUBLISH packets. These redeliveries should be treated as duplicates even if the DUP flag in the PUBLISH packet is not set. If `acquirePublishAcknowledgement()` is not called again for a redelivered packet, the acknowledgement will be sent automatically.
+
+**Session resumption after disconnect/reconnect**
+
+Upon a disconnect and reconnect of the MQTT5 client, if a session is resumed, any previously acquired `ScopedResource<PublishAcknowledgementHandle>` is void. The broker will resend the unacknowledged PUBLISH packet, and `acquirePublishAcknowledgement()` must be called again within the callback for that resent packet. If the resent packet is not handled for manual acknowledgement, the acknowledgement will be sent automatically.
+
+
 # MQTT5 Best Practices
 
 Below are some best practices for the MQTT5 client that are recommended to follow for the best development experience: