Merge pull request #1313 from Azure/FixSendAsyncDocs

Improve *SendEventAsync documentation about how the message handle is treated (gh#1309)
Azure · Nov 13, 2019 · bb29fc1 · bb29fc1
2 parents 669efca + f6a548d
commit bb29fc1
Show file tree

Hide file tree

Showing 6 changed files with 24 additions and 6 deletions.
diff --git a/iothub_client/inc/iothub_client.h b/iothub_client/inc/iothub_client.h
@@ -120,7 +120,10 @@ extern "C"
     *
     *            @b NOTE: The application behavior is undefined if the user calls
     *            the ::IoTHubClient_Destroy function from within any callback.
-    *
+    * @remarks
+    *            The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
+    *            so this argument can be destroyed by the calling application right after IoTHubClient_SendEventAsync returns.
+    *            The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
     * @return    IOTHUB_CLIENT_OK upon success or an error code upon failure.
     */
     MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_SendEventAsync, IOTHUB_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);

diff --git a/iothub_client/inc/iothub_client_ll.h b/iothub_client/inc/iothub_client_ll.h
@@ -122,7 +122,10 @@ typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_CLIENT_LL_HANDLE;
     *
     *            @b NOTE: The application behavior is undefined if the user calls
     *            the ::IoTHubClient_LL_Destroy function from within any callback.
-    *
+    * @remarks
+    *            The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
+    *            so this argument can be destroyed by the calling application right after IoTHubClient_LL_SendEventAsync returns.
+    *            The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
     * @return    IOTHUB_CLIENT_OK upon success or an error code upon failure.
     */
      MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubClient_LL_SendEventAsync, IOTHUB_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);

diff --git a/iothub_client/inc/iothub_device_client.h b/iothub_client/inc/iothub_device_client.h
@@ -120,7 +120,10 @@ extern "C"
     *
     *           @b NOTE: The application behavior is undefined if the user calls
     *           the ::IoTHubDeviceClient_Destroy function from within any callback.
-    *
+    * @remarks
+    *           The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
+    *           so this argument can be destroyed by the calling application right after IoTHubDeviceClient_SendEventAsync returns.
+    *           The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
     * @return   IOTHUB_CLIENT_OK upon success or an error code upon failure.
     */
     MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_SendEventAsync, IOTHUB_DEVICE_CLIENT_HANDLE, iotHubClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);

diff --git a/iothub_client/inc/iothub_device_client_ll.h b/iothub_client/inc/iothub_device_client_ll.h
@@ -124,7 +124,10 @@ typedef struct IOTHUB_CLIENT_CORE_LL_HANDLE_DATA_TAG* IOTHUB_DEVICE_CLIENT_LL_HA
     *
     *           @b NOTE: The application behavior is undefined if the user calls
     *           the ::IoTHubDeviceClient_LL_Destroy function from within any callback.
-    *
+    * @remarks
+    *           The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
+    *           so this argument can be destroyed by the calling application right after IoTHubDeviceClient_LL_SendEventAsync returns.
+    *           The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
     * @return   IOTHUB_CLIENT_OK upon success or an error code upon failure.
     */
      MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubDeviceClient_LL_SendEventAsync, IOTHUB_DEVICE_CLIENT_LL_HANDLE, iotHubClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);

diff --git a/iothub_client/inc/iothub_module_client.h b/iothub_client/inc/iothub_module_client.h
@@ -78,7 +78,10 @@ extern "C"
     *
     *            @b NOTE: The application behavior is undefined if the user calls
     *            the ::IoTHubModuleClient_Destroy function from within any callback.
-    *
+    * @remarks
+    *           The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
+    *           so this argument can be destroyed by the calling application right after IoTHubModuleClient_SendEventAsync returns.
+    *           The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
     * @return    IOTHUB_CLIENT_OK upon success or an error code upon failure.
     */
     MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubModuleClient_SendEventAsync, IOTHUB_MODULE_CLIENT_HANDLE, iotHubModuleClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);

diff --git a/iothub_client/inc/iothub_module_client_ll.h b/iothub_client/inc/iothub_module_client_ll.h
@@ -91,7 +91,10 @@ extern "C"
     *
     *            @b NOTE: The application behavior is undefined if the user calls
     *            the ::IoTHubModuleClient_LL_Destroy function from within any callback.
-    *
+    * @remarks
+    *            The IOTHUB_MESSAGE_HANDLE instance provided as argument is copied by the function,
+    *            so this argument can be destroyed by the calling application right after IoTHubModuleClient_LL_SendEventAsync returns.
+    *            The copy of @c eventMessageHandle is later destroyed by the iothub client when the message is effectively sent, if a failure sending it occurs, or if the client is destroyed.
     * @return    IOTHUB_CLIENT_OK upon success or an error code upon failure.
     */
      MOCKABLE_FUNCTION(, IOTHUB_CLIENT_RESULT, IoTHubModuleClient_LL_SendEventAsync, IOTHUB_MODULE_CLIENT_LL_HANDLE, iotHubModuleClientHandle, IOTHUB_MESSAGE_HANDLE, eventMessageHandle, IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK, eventConfirmationCallback, void*, userContextCallback);