PublishAcknowledgementHandle fully opaque struct (#833)

Author: sbSteveK

include/aws/crt/mqtt/private/Mqtt5ClientCore.h

@@ -19,34 +19,6 @@ namespace Aws
     {
         namespace Mqtt5
         {
-            /**
-             * An opaque handle representing manual control over a publish acknowledgement for a received PUBLISH
-             * packet.
-             *
-             * Obtained by calling acquirePublishAcknowledgement() within the OnPublishReceivedHandler callback.
-             * Pass this handle to Mqtt5Client::InvokePublishAcknowledgement() at any later time to send the publish
-             * acknowledgement.
-             *
-             * @note acquirePublishAcknowledgement() must be called within the OnPublishReceivedHandler callback.
-             *       Calling it after the callback returns will return nullptr.
-             */
-            struct AWS_CRT_CPP_API PublishAcknowledgementHandle
-            {
-                friend class Mqtt5ClientCore;
-
-              private:
-                explicit PublishAcknowledgementHandle(uint64_t controlId) noexcept : m_controlId(controlId) {}
-
-                /**
-                 * Creates a PublishAcknowledgementHandle.
-                 */
-                static ScopedResource<PublishAcknowledgementHandle> s_create(
-                    Allocator *allocator,
-                    uint64_t controlId) noexcept;
-
-                uint64_t m_controlId;
-            };
-
             /**
              * The Mqtt5ClientCore is an internal class for Mqtt5Client. The class is used to handle communication
              * between Mqtt5Client and underlying c mqtt5 client. This class should only be used internally by

source/mqtt/Mqtt5ClientCore.cpp

@@ -20,18 +20,27 @@ namespace Aws
     {
         namespace Mqtt5
         {
-            ScopedResource<PublishAcknowledgementHandle> PublishAcknowledgementHandle::s_create(
+            /**
+             * We keep the definition of PublishAcknowledgementHandle here so it remains an incomplete type in all
+             * headers. This makes the type opaque to users. They can hold a
+             * ScopedResource<PublishAcknowledgementHandle> but cannot inspect, modify, or construct one directly.
+             */
+            struct PublishAcknowledgementHandle
+            {
+                explicit PublishAcknowledgementHandle(uint64_t controlId) noexcept : controlId(controlId) {}
+                uint64_t controlId;
+            };
+
+            static ScopedResource<PublishAcknowledgementHandle> s_createPublishAcknowledgementHandle(
                 Allocator *allocator,
                 uint64_t controlId) noexcept
             {
-                /* Manually call aws_mem_acquire here because PublishAcknowledgeHandle only has a private constructor
-                 * and cannot be used with Aws::Crt::New. Aws::Crt::Delete still clears memory appropriately. */
-                void *mem = aws_mem_acquire(allocator, sizeof(PublishAcknowledgementHandle));
-                if (!mem)
+                PublishAcknowledgementHandle *handle =
+                    Aws::Crt::New<PublishAcknowledgementHandle>(allocator, controlId);
+                if (!handle)
                 {
                     return ScopedResource<PublishAcknowledgementHandle>(nullptr, [](PublishAcknowledgementHandle *) {});
                 }
-                PublishAcknowledgementHandle *handle = new (mem) PublishAcknowledgementHandle(controlId);
                 return ScopedResource<PublishAcknowledgementHandle>(
                     handle, [allocator](PublishAcknowledgementHandle *p) { Aws::Crt::Delete(p, allocator); });
             }
@@ -246,7 +255,7 @@ namespace Aws
 
                             if (publishAcknowledgementId != 0)
                             {
-                                functor.handle = PublishAcknowledgementHandle::s_create(
+                                functor.handle = s_createPublishAcknowledgementHandle(
                                     client_core->m_allocator, publishAcknowledgementId);
                                 /* std::function requires a copyable callable so we wrap the move only functor
                                  * into a shared_ptr so the lambda can be copyable. */
@@ -716,7 +725,7 @@ namespace Aws
                     return false;
                 }
                 return aws_mqtt5_client_invoke_publish_acknowledgement(
-                           m_client, publishAcknowledgementHandle->m_controlId, nullptr) == AWS_OP_SUCCESS;
+                           m_client, publishAcknowledgementHandle->controlId, nullptr) == AWS_OP_SUCCESS;
             }
 
             void Mqtt5ClientCore::Close() noexcept