diff --git a/source/include/core_mqtt.h b/source/include/core_mqtt.h index 2f0f0b005..88216abb6 100644 --- a/source/include/core_mqtt.h +++ b/source/include/core_mqtt.h @@ -60,7 +60,7 @@ struct MQTTDeserializedInfo; /** * @ingroup mqtt_callback_types - * @brief Application provided callback to retrieve the current time in + * @brief Application provided function to query the current time in * milliseconds. * * @return The current time in milliseconds. @@ -228,12 +228,13 @@ typedef struct MQTTDeserializedInfo * * This function must be called on a #MQTTContext_t before any other function. * - * @note The #MQTTGetCurrentTimeFunc_t callback function must be defined. If + * @note The #MQTTGetCurrentTimeFunc_t function for querying time must be defined. If * there is no time implementation, it is the responsibility of the application - * to provide a dummy function to always return 0, and provide 0 timeouts for - * all calls to #MQTT_Connect, #MQTT_ProcessLoop, and #MQTT_ReceiveLoop. This - * will result in loop functions running for a single iteration, and #MQTT_Connect - * relying on #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet. + * to provide a dummy function to always return 0, provide 0 timeouts for + * all calls to #MQTT_Connect, #MQTT_ProcessLoop, and #MQTT_ReceiveLoop and configure + * the #MQTT_RECV_POLLING_TIMEOUT_MS and #MQTT_SEND_RETRY_TIMEOUT_MS configurations + * to be 0. This will result in loop functions running for a single iteration, and + * #MQTT_Connect relying on #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet. * * @param[in] pContext The context to initialize. * @param[in] pTransportInterface The transport interface to use with the context. @@ -310,8 +311,9 @@ MQTTStatus_t MQTT_Init( MQTTContext_t * pContext, * The network receive for CONNACK is retried up to the number of times * configured by #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT. * - * @note If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then the - * timeout MUST be set to 0. + * @note If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then a + * timeout value of 0 MUST be passed to the API, and the #MQTT_RECV_POLLING_TIMEOUT_MS + * and #MQTT_SEND_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0. * * @param[in] pContext Initialized MQTT context. * @param[in] pConnectInfo MQTT CONNECT packet information. @@ -596,8 +598,9 @@ MQTTStatus_t MQTT_Disconnect( MQTTContext_t * pContext ); * alive. * * @note Passing a timeout value of 0 will run the loop for a single iteration. - * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then this - * timeout MUST be set to 0. + * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then the timeout + * passed to the API MUST be 0, and the #MQTT_RECV_POLLING_TIMEOUT_MS and + * #MQTT_SEND_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0. * * @param[in] pContext Initialized and connected MQTT context. * @param[in] timeoutMs Minimum time in milliseconds that the receive loop will @@ -656,8 +659,9 @@ MQTTStatus_t MQTT_ProcessLoop( MQTTContext_t * pContext, * keep alive. * * @note Passing a timeout value of 0 will run the loop for a single iteration. - * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then this - * timeout MUST be set to 0. + * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then the timeout + * value passed to the API MUST be 0, and the #MQTT_RECV_POLLING_TIMEOUT_MS + * and #MQTT_SEND_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0. * * @param[in] pContext Initialized and connected MQTT context. * @param[in] timeoutMs Minimum time in milliseconds that the receive loop will diff --git a/source/include/core_mqtt_config_defaults.h b/source/include/core_mqtt_config_defaults.h index 497e3fc4e..dc4209325 100644 --- a/source/include/core_mqtt_config_defaults.h +++ b/source/include/core_mqtt_config_defaults.h @@ -117,9 +117,13 @@ * may be called multiple times until all of the expected number of bytes of the * packet are received. This timeout represents the maximum polling duration that * is allowed without any data reception from the network for the incoming packet. + * * If the timeout expires, the #MQTT_ProcessLoop and #MQTT_ReceiveLoop functions * return #MQTTRecvFailed. * + * @note If a dummy implementation of the #MQTTGetCurrentTimeFunc_t timer function, + * that always returns 0, is used, then #MQTT_RECV_POLLING_TIMEOUT_MS MUST be set to 0. + * * Possible values: Any positive 32 bit integer. Recommended to use a * small timeout value.
* Default value: `10` @@ -142,6 +146,9 @@ * If the timeout expires, the #MQTT_ProcessLoop and #MQTT_ReceiveLoop functions * return #MQTTSendFailed. * + * @note If a dummy implementation of the #MQTTGetCurrentTimeFunc_t timer function, + * that always returns 0, is used, then #MQTT_SEND_RETRY_TIMEOUT_MS MUST be set to 0. + * * Possible values: Any positive 32 bit integer. Recommended to use a small * timeout value.
* Default value: `10`