IoT SDK review updates (Azure#1178)

* az_iot_is_retriable_status

* update

* update

* update

* doc update

* update change log

* fix doxgen build break

* fixed PR issues

* added more context to global_device_hostname

* Update .gitignore

* Update CHANGELOG.md

* pr review

* Update az_iot_provisioning_client.c

CHANGELOG.md

@@ -14,6 +14,11 @@
 - Rename `az_iot_hub_client_properties` to `az_iot_message_properties` and move it from `az_iot_hub_client.h` to `az_iot_common.h`.
 - Remove `az_pair` from `az_iot_message_properties_next()` in favor of individual name and value `az_span` parameters.
 - In `az_result.h`, rename `az_failed()` to `az_result_failed()` and `az_succeeded()` to `az_result_succeeded()`.
+- `az_iot_is_success_status()` renamed to `az_iot_status_succeeded()`.
+- `az_iot_is_retriable_status()` renamed to `az_iot_status_retriable()`.
+- `az_iot_retry_calc_delay()` renamed to `az_iot_calculate_retry_delay()`.
+- `az_iot_hub_client_sas_get_password()` parameter `token_expiration_epoch_time` moved to second parameter.
+- `az_iot_provisioning_client_init()` parameter `global_device_endpoint` renamed to `global_device_hostname`.
 - Renamed the macro `AZ_SPAN_NULL` to `AZ_SPAN_EMPTY`.
 
 ### Bug Fixes

sdk/docs/iot/mqtt_state_machine.md

@@ -63,7 +63,7 @@ if(az_result_failed(az_iot_hub_client_sas_get_signature(client, unix_time + 3600
 
 // Application will Base64Encode the HMAC256 of the az_span_ptr(signature) containing az_span_size(signature) bytes with the Shared Access Key.
 
-if(az_result_failed(az_iot_hub_client_sas_get_password(client, base64_hmac_sha256_signature, NULL, password, password_size, &password_length)))
+if(az_result_failed(az_iot_hub_client_sas_get_password(client, NULL, base64_hmac_sha256_signature, password, password_size, &password_length)))
 {
     // error.
 }
@@ -175,13 +175,13 @@ The following APIs may be used to determine if the status indicates an error and
 
 ```C
 az_iot_status status = response.status;
-if (az_iot_is_success_status(status))
+if (az_iot_status_succeeded(status))
 {
     // success case
 }
 else
 {
-    if (az_iot_is_retriable_status(status))
+    if (az_iot_status_retriable(status))
     {
         // retry
     }
@@ -202,7 +202,7 @@ For connectivity issues at all layers (TCP, TLS, MQTT) as well as cases where th
 // The previous operation took operation_msec.
 // The application calculates random_msec between 0 and max_random_msec.
 
-int32_t delay_msec = az_iot_retry_calc_delay(operation_msec, attempt, min_retry_delay_msec, max_retry_delay_msec, random_msec);
+int32_t delay_msec = az_iot_calculate_retry_delay(operation_msec, attempt, min_retry_delay_msec, max_retry_delay_msec, random_msec);
 ```
 
 _Note 1_: The network stack may have used more time than the recommended delay before timing out. (e.g. The operation timed out after 2 minutes while the delay between operations is 1 second). In this case there is no need to delay the next operation.
@@ -229,7 +229,7 @@ if ( response.retry_after_seconds > 0 )
 }
 else
 {
-    delay_ms = az_iot_retry_calc_delay(operation_msec, attempt, min_retry_delay_msec, max_retry_delay_msec, random_msec);
+    delay_ms = az_iot_calculate_retry_delay(operation_msec, attempt, min_retry_delay_msec, max_retry_delay_msec, random_msec);
 }
 ```
 

sdk/docs/iot/resources/iot_retry_flow.puml

@@ -19,7 +19,7 @@ state Provisioning <<APP>> {
     state Provisioning_app_delay<<APP>>
     Provisioning_app_delay --> Register_Device : retry
     Provisioning_calculate_delay: - response.retry-after
-    Provisioning_calculate_delay: - az_iot_retry_calc_delay
+    Provisioning_calculate_delay: - az_iot_calculate_retry_delay
 
     ' Provisioning Non-retriable 
     Register_Device --> Provisioning_not_retriable_failure
@@ -43,7 +43,7 @@ state IoT_Hub <<APP>> {
     Hub_calculate_delay --> Hub_app_delay
     state Hub_app_delay<<APP>>
     Hub_app_delay --> Hub_Operation : retry
-    Hub_calculate_delay: - az_iot_retry_calc_delay
+    Hub_calculate_delay: - az_iot_calculate_retry_delay
 
     ' Hub Non-retriable 
     Hub_Operation --> Hub_not_retriable_failure

sdk/inc/azure/iot/az_iot_common.h

@@ -31,6 +31,8 @@ enum
 
 /**
  * @brief Azure IoT service status codes.
+ * 
+ * @note https://docs.microsoft.com/en-us/azure/iot-central/core/troubleshoot-connection#error-codes
  *
  */
 typedef enum
@@ -178,7 +180,7 @@ AZ_NODISCARD az_result az_iot_message_properties_next(
  * @param[in] status The #az_iot_status to verify.
  * @return `true` if the status indicates success. `false` otherwise.
  */
-AZ_NODISCARD AZ_INLINE bool az_iot_is_success_status(az_iot_status status)
+AZ_NODISCARD AZ_INLINE bool az_iot_status_succeeded(az_iot_status status)
 {
   return status < AZ_IOT_STATUS_BAD_REQUEST;
 }
@@ -190,7 +192,7 @@ AZ_NODISCARD AZ_INLINE bool az_iot_is_success_status(az_iot_status status)
  * @param[in] status The #az_iot_status to verify.
  * @return `true` if the operation should be retried. `false` otherwise.
  */
-AZ_NODISCARD AZ_INLINE bool az_iot_is_retriable_status(az_iot_status status)
+AZ_NODISCARD AZ_INLINE bool az_iot_status_retriable(az_iot_status status)
 {
   return ((status == AZ_IOT_STATUS_THROTTLED) || (status == AZ_IOT_STATUS_SERVER_ERROR));
 }
@@ -206,7 +208,7 @@ AZ_NODISCARD AZ_INLINE bool az_iot_is_retriable_status(az_iot_status status)
  * @param[in] random_msec A random value between 0 and the maximum allowed jitter, in milliseconds.
  * @return The recommended delay in milliseconds.
  */
-AZ_NODISCARD int32_t az_iot_retry_calc_delay(
+AZ_NODISCARD int32_t az_iot_calculate_retry_delay(
     int32_t operation_msec,
     int16_t attempt,
     int32_t min_retry_delay_msec,

sdk/inc/azure/iot/az_iot_hub_client.h

@@ -32,9 +32,7 @@
  */
 enum
 {
-  AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_QOS = 0,
-  AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_DUPLICATE = 0,
-  AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_RETAIN = 1
+  AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_QOS = 0
 };
 
 /**
@@ -203,8 +201,8 @@ AZ_NODISCARD az_result az_iot_hub_client_sas_get_signature(
  */
 AZ_NODISCARD az_result az_iot_hub_client_sas_get_password(
     az_iot_hub_client const* client,
-    az_span base64_hmac_sha256_signature,
     uint64_t token_expiration_epoch_time,
+    az_span base64_hmac_sha256_signature,
     az_span key_name,
     char* mqtt_password,
     size_t mqtt_password_size,

sdk/inc/azure/iot/az_iot_provisioning_client.h

@@ -69,7 +69,7 @@ AZ_NODISCARD az_iot_provisioning_client_options az_iot_provisioning_client_optio
  * @brief Initializes an Azure IoT Provisioning Client.
  *
  * @param[in] client The #az_iot_provisioning_client to use for this call.
- * @param[in] global_device_endpoint The global device endpoint.
+ * @param[in] global_device_hostname The device provisioning services global host name.
  * @param[in] id_scope The ID Scope.
  * @param[in] registration_id The Registration ID. This must match the client certificate name (CN
  *                            part of the certificate subject).
@@ -80,7 +80,7 @@ AZ_NODISCARD az_iot_provisioning_client_options az_iot_provisioning_client_optio
  */
 AZ_NODISCARD az_result az_iot_provisioning_client_init(
     az_iot_provisioning_client* client,
-    az_span global_device_endpoint,
+    az_span global_device_hostname,
     az_span id_scope,
     az_span registration_id,
     az_iot_provisioning_client_options const* options);
@@ -215,7 +215,7 @@ typedef struct
   az_span error_tracking_id; /**< Submit this ID when asking for Azure IoT service-desk help. */
   az_span
       error_timestamp; /**< Submit this timestamp when asking for Azure IoT service-desk help. */
-} az_iot_provisioning_client_registration_result;
+} az_iot_provisioning_client_registration_state;
 
 /**
  * @brief Register or query operation response.
@@ -235,7 +235,7 @@ typedef struct
                              * be used to convert this into
                              * the #az_iot_provisioning_client_operation_status enum. */
   uint32_t retry_after_seconds; /**< Recommended timeout before sending the next MQTT publish. */
-  az_iot_provisioning_client_registration_result
+  az_iot_provisioning_client_registration_state
       registration_result; /**< If the operation is complete (success or error), the
                                    registration state will contain the hub and device id in case of
                                    success. */
@@ -290,7 +290,9 @@ AZ_NODISCARD az_result az_iot_provisioning_client_parse_operation_status(
 
 /**
  * @brief Checks if the status indicates that the service has an authoritative result of the
- * register operation. The operation may have completed in either success or error.
+ * register operation. The operation may have completed in either success or error. Completed
+ * states are AZ_IOT_PROVISIONING_STATUS_ASSIGNED, AZ_IOT_PROVISIONING_STATUS_FAILED, or 
+ * AZ_IOT_PROVISIONING_STATUS_DISABLED.
  *
  * @param[in] operation_status The #az_iot_provisioning_client_operation_status obtained by calling
  * #az_iot_provisioning_client_parse_operation_status.
@@ -329,7 +331,7 @@ AZ_NODISCARD az_result az_iot_provisioning_client_register_get_publish_topic(
  * @remark The payload of the MQTT publish message should be empty.
  *
  * @param[in] client The #az_iot_provisioning_client to use for this call.
- * @param[in] register_response The received #az_iot_provisioning_client_register_response response.
+ * @param[in] operation_id The received operation_id from the #az_iot_provisioning_client_register_response response.
  * @param[out] mqtt_topic A buffer with sufficient capacity to hold the MQTT topic filter. If
  *                        successful, contains a null-terminated string with the topic filter that
  *                        needs to be passed to the MQTT client.
@@ -340,7 +342,7 @@ AZ_NODISCARD az_result az_iot_provisioning_client_register_get_publish_topic(
  */
 AZ_NODISCARD az_result az_iot_provisioning_client_query_status_get_publish_topic(
     az_iot_provisioning_client const* client,
-    az_iot_provisioning_client_register_response const* register_response,
+    az_span operation_id,
     char* mqtt_topic,
     size_t mqtt_topic_size,
     size_t* out_mqtt_topic_length);

sdk/samples/iot/aziot_esp8266/aziot_esp8266.ino

@@ -175,8 +175,8 @@ static int generateSasToken(char* sas_token, size_t size)
   // URl-encode base64 encoded encrypted signature
   if (az_result_failed(az_iot_hub_client_sas_get_password(
           &client,
-          b64enc_hmacsha256_signature_span,
           expiration,
+          b64enc_hmacsha256_signature_span,
           AZ_SPAN_EMPTY,
           sas_token,
           size,

sdk/samples/iot/generate_certificate.ps1

@@ -58,10 +58,10 @@ Write-Output "`nSAMPLE CERTIFICATE GENERATED:"
 Write-Output "Use the following command to set the environment variable for the samples:"
 
 if ($IsWindows) {
-  Write-Output "`n`t`$env:AZ_IOT_DEVICE_X509_CERT_PEM_FILE=$(Resolve-Path device_cert_store.pem)"
+  Write-Output "`n`t`$env:AZ_IOT_DEVICE_X509_CERT_PEM_FILE_PATH=$(Resolve-Path device_cert_store.pem)"
 }
 else {
-  Write-Output "`n`texport AZ_IOT_DEVICE_X509_CERT_PEM_FILE=$(Resolve-Path device_cert_store.pem)"
+  Write-Output "`n`texport AZ_IOT_DEVICE_X509_CERT_PEM_FILE_PATH=$(Resolve-Path device_cert_store.pem)"
 }
 
 Write-Output "`nDPS SAMPLE:"

sdk/samples/iot/paho_iot_hub_sas_telemetry_sample.c

@@ -259,8 +259,8 @@ static void generate_sas_key(void)
   size_t mqtt_password_length;
   rc = az_iot_hub_client_sas_get_password(
       &hub_client,
-      sas_base64_encoded_signed_signature,
       sas_duration,
+      sas_base64_encoded_signed_signature,
       AZ_SPAN_EMPTY,
       mqtt_password_buffer,
       sizeof(mqtt_password_buffer),

sdk/samples/iot/paho_iot_provisioning_sample.c

@@ -368,7 +368,7 @@ static void send_operation_query_message(
   if (az_result_failed(
           rc = az_iot_provisioning_client_query_status_get_publish_topic(
               &provisioning_client,
-              register_response,
+              register_response->operation_id,
               query_topic_buffer,
               sizeof(query_topic_buffer),
               NULL)))

sdk/samples/iot/paho_iot_provisioning_sas_sample.c

@@ -373,7 +373,7 @@ static void send_operation_query_message(
   if (az_result_failed(
           rc = az_iot_provisioning_client_query_status_get_publish_topic(
               &provisioning_client,
-              register_response,
+              register_response->operation_id,
               query_status_topic_buffer,
               sizeof(query_status_topic_buffer),
               NULL)))

sdk/src/azure/iot/az_iot_common.c

@@ -141,7 +141,7 @@ AZ_NODISCARD az_result az_iot_message_properties_next(
   return AZ_OK;
 }
 
-AZ_NODISCARD int32_t az_iot_retry_calc_delay(
+AZ_NODISCARD int32_t az_iot_calculate_retry_delay(
     int32_t operation_msec,
     int16_t attempt,
     int32_t min_retry_delay_msec,

sdk/src/azure/iot/az_iot_hub_client_sas.c

@@ -82,8 +82,8 @@ AZ_NODISCARD az_result az_iot_hub_client_sas_get_signature(
 
 AZ_NODISCARD az_result az_iot_hub_client_sas_get_password(
     az_iot_hub_client const* client,
-    az_span base64_hmac_sha256_signature,
     uint64_t token_expiration_epoch_time,
+    az_span base64_hmac_sha256_signature,
     az_span key_name,
     char* mqtt_password,
     size_t mqtt_password_size,

sdk/src/azure/iot/az_iot_provisioning_client.c

@@ -44,17 +44,17 @@ AZ_NODISCARD az_iot_provisioning_client_options az_iot_provisioning_client_optio
 
 AZ_NODISCARD az_result az_iot_provisioning_client_init(
     az_iot_provisioning_client* client,
-    az_span global_device_endpoint,
+    az_span global_device_hostname,
     az_span id_scope,
     az_span registration_id,
     az_iot_provisioning_client_options const* options)
 {
   _az_PRECONDITION_NOT_NULL(client);
-  _az_PRECONDITION_VALID_SPAN(global_device_endpoint, 1, false);
+  _az_PRECONDITION_VALID_SPAN(global_device_hostname, 1, false);
   _az_PRECONDITION_VALID_SPAN(id_scope, 1, false);
   _az_PRECONDITION_VALID_SPAN(registration_id, 1, false);
 
-  client->_internal.global_device_endpoint = global_device_endpoint;
+  client->_internal.global_device_endpoint = global_device_hostname;
   client->_internal.id_scope = id_scope;
   client->_internal.registration_id = registration_id;
 
@@ -183,7 +183,7 @@ AZ_NODISCARD az_result az_iot_provisioning_client_register_get_publish_topic(
 // Topic: $dps/registrations/GET/iotdps-get-operationstatus/?$rid=%s&operationId=%s
 AZ_NODISCARD az_result az_iot_provisioning_client_query_status_get_publish_topic(
     az_iot_provisioning_client const* client,
-    az_iot_provisioning_client_register_response const* register_response,
+    az_span operation_id,
     char* mqtt_topic,
     size_t mqtt_topic_size,
     size_t* out_mqtt_topic_length)
@@ -194,21 +194,20 @@ AZ_NODISCARD az_result az_iot_provisioning_client_query_status_get_publish_topic
   _az_PRECONDITION_NOT_NULL(mqtt_topic);
   _az_PRECONDITION(mqtt_topic_size > 0);
 
-  _az_PRECONDITION_NOT_NULL(register_response);
-  _az_PRECONDITION_VALID_SPAN(register_response->operation_id, 1, false);
+  _az_PRECONDITION_VALID_SPAN(operation_id, 1, false);
 
   az_span mqtt_topic_span = az_span_create((uint8_t*)mqtt_topic, (int32_t)mqtt_topic_size);
   az_span str_dps_registrations = _az_iot_provisioning_get_str_dps_registrations();
 
   int32_t required_length = az_span_size(str_dps_registrations)
       + az_span_size(str_get_iotdps_get_operationstatus)
-      + az_span_size(register_response->operation_id);
+      + az_span_size(operation_id);
 
   _az_RETURN_IF_NOT_ENOUGH_SIZE(mqtt_topic_span, required_length + (int32_t)sizeof((uint8_t)'\0'));
 
   az_span remainder = az_span_copy(mqtt_topic_span, str_dps_registrations);
   remainder = az_span_copy(remainder, str_get_iotdps_get_operationstatus);
-  remainder = az_span_copy(remainder, register_response->operation_id);
+  remainder = az_span_copy(remainder, operation_id);
   remainder = az_span_copy_u8(remainder, '\0');
 
   if (out_mqtt_topic_length)
@@ -219,10 +218,10 @@ AZ_NODISCARD az_result az_iot_provisioning_client_query_status_get_publish_topic
   return AZ_OK;
 }
 
-AZ_INLINE az_iot_provisioning_client_registration_result
+AZ_INLINE az_iot_provisioning_client_registration_state
 _az_iot_provisioning_registration_result_default()
 {
-  return (az_iot_provisioning_client_registration_result){ .assigned_hub_hostname = AZ_SPAN_EMPTY,
+  return (az_iot_provisioning_client_registration_state){ .assigned_hub_hostname = AZ_SPAN_EMPTY,
                                                            .device_id = AZ_SPAN_EMPTY,
                                                            .error_code = AZ_IOT_STATUS_UNKNOWN,
                                                            .extended_error_code = 0,
@@ -252,7 +251,7 @@ Documented at
 */
 AZ_INLINE az_result _az_iot_provisioning_client_parse_payload_error_code(
     az_json_reader* jr,
-    az_iot_provisioning_client_registration_result* out_state)
+    az_iot_provisioning_client_registration_state* out_state)
 {
   if (az_json_token_is_text_equal(&jr->token, AZ_SPAN_FROM_STR("errorCode")))
   {
@@ -268,7 +267,7 @@ AZ_INLINE az_result _az_iot_provisioning_client_parse_payload_error_code(
 
 AZ_INLINE az_result _az_iot_provisioning_client_payload_registration_result_parse(
     az_json_reader* jr,
-    az_iot_provisioning_client_registration_result* out_state)
+    az_iot_provisioning_client_registration_state* out_state)
 {
   if (jr->token.kind != AZ_JSON_TOKEN_BEGIN_OBJECT)
   {