Changing az_iot_provisioning_client_register_get_request_payload options behavior (#2188)

* Renaming AZ_IGNORE_DEPRECATIONS to AZ_PUSH_IGNORE_DEPRECATIONS.

* Changing behavior of az_iot_provisioning_client_register_get_request_payload to accept NULL options.

* Addressing PR comments. Updating readme.md contents.

* Automatic CLang changes.

sdk/inc/azure/core/_az_cfg.h

@@ -107,10 +107,10 @@
 #endif
 
 #ifdef _MSC_VER
-#define AZ_IGNORE_DEPRECATIONS _Pragma("warning(push)") _Pragma("warning(disable:4996)")
+#define AZ_PUSH_IGNORE_DEPRECATIONS _Pragma("warning(push)") _Pragma("warning(disable:4996)")
 #define AZ_POP_WARNINGS _Pragma("warning(pop)")
 #else
-#define AZ_IGNORE_DEPRECATIONS \
+#define AZ_PUSH_IGNORE_DEPRECATIONS \
   _Pragma("GCC diagnostic push") _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
 #define AZ_POP_WARNINGS _Pragma("GCC diagnostic pop")
 #endif

sdk/inc/azure/iot/az_iot_hub_client.h

@@ -102,10 +102,10 @@ AZ_NODISCARD az_iot_hub_client_options az_iot_hub_client_options_default();
  * topic names (listed below) and of the IoT Hub (listed below)
  * http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718106
  * https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#device-identity-properties
- * @param[in] options A reference to an #az_iot_hub_client_options structure. If `NULL` is passed,
- * the hub client will use the default options. If using custom options, please initialize first by
- * calling az_iot_hub_client_options_default() and then populating relevant options with your own
- * values.
+ * @param[in] options __[nullable]__ A reference to an #az_iot_hub_client_options structure. If
+ * `NULL` is passed, the hub client will use the default options. If using custom options, please
+ * initialize first by calling az_iot_hub_client_options_default() and then populating relevant
+ * options with your own values.
  * @pre \p client must not be `NULL`.
  * @pre \p iot_hub_hostname must be a valid span of size greater than 0.
  * @pre \p device_id must be a valid span of size greater than 0.

sdk/inc/azure/iot/az_iot_provisioning_client.h

@@ -78,7 +78,9 @@ AZ_NODISCARD az_iot_provisioning_client_options az_iot_provisioning_client_optio
  * part of the certificate subject). Must conform to the limitations listed in the link below:
  * https://docs.microsoft.com/azure/iot-dps/concepts-service#registration-id
  * @param[in] options __[nullable]__ A reference to an #az_iot_provisioning_client_options
- * structure. Can be `NULL` for default options.
+ * structure. If `NULL` is passed, the provisioning client will use the default options. If using
+ * custom options, please initialize first by calling az_iot_provisioning_client_options_default()
+ * and then populating relevant options with your own values.
  * @pre \p client must not be `NULL`.
  * @pre \p global_device_hostname must be a valid span of size greater than 0.
  * @pre \p id_scope must be a valid span of size greater than 0.
@@ -477,14 +479,16 @@ az_iot_provisioning_client_payload_options_default();
  * @param[in] client The #az_iot_provisioning_client to use for this call.
  * @param[in] custom_payload_property __[nullable]__ Custom JSON to be added to this payload.
  * Can be `NULL`.
- * @param[in] options __[nullable]__ Reserved field for future options to this function.  Must be
- * `NULL`.
+ * @param[in] options __[nullable]__ A reference to an #az_iot_provisioning_client_payload_options
+ * structure. If `NULL` is passed, the provisioning client will use the default options. If using
+ * custom options, please initialize first by calling
+ * az_iot_provisioning_client_payload_options_default() and then populating relevant options with
+ * your own values.
  * @param[out] mqtt_payload A buffer with sufficient capacity to hold the MQTT payload.
  * @param[in] mqtt_payload_size The size, in bytes of \p mqtt_payload.
  * @param[out] out_mqtt_payload_length Contains the length, in bytes, written to \p mqtt_payload on
  * success.
  * @pre \p client must not be `NULL`.
- * @pre \p options must be `NULL`.
  * @pre \p mqtt_payload must not be `NULL`.
  * @pre \p mqtt_payload_size must be greater than 0.
  * @pre \p out_mqtt_payload_length must not be `NULL`.

sdk/samples/iot/README.md

@@ -32,6 +32,7 @@
     - [IoT Plug and Play Multiple Component Sample](#iot-plug-and-play-multiple-component-sample)
     - [IoT Provisioning Certificate Sample](#iot-provisioning-certificate-sample)
     - [IoT Provisioning SAS Sample](#iot-provisioning-sas-sample)
+    - [*Preview* IoT Provisioning CSR and TrustBundle Sample](#preview-iot-provisioning-csr-and-trustbundle-sample)
   - [Using IoT Hub with an ECC Server Certificate Chain](#using-iot-hub-with-an-ecc-server-certificate-chain)
   - [Next Steps and Additional Documentation](#next-steps-and-additional-documentation)
   - [Troubleshooting](#troubleshooting)

sdk/samples/iot/paho_iot_pnp_with_provisioning_sample.c

@@ -250,7 +250,7 @@ static void register_device_with_provisioning_service(void)
   uint8_t mqtt_payload[MQTT_PAYLOAD_BUFFER_LENGTH];
   size_t mqtt_payload_length;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   rc = az_iot_provisioning_client_get_request_payload(
       &provisioning_client,
       custom_registration_payload_property,
@@ -259,7 +259,6 @@ static void register_device_with_provisioning_service(void)
       sizeof(mqtt_payload),
       &mqtt_payload_length);
   AZ_POP_WARNINGS
-
   if (az_result_failed(rc))
   {
     IOT_SAMPLE_LOG_ERROR(

sdk/src/azure/iot/az_iot_provisioning_client.c

@@ -641,10 +641,7 @@ AZ_NODISCARD az_result az_iot_provisioning_client_register_get_request_payload(
     size_t mqtt_payload_size,
     size_t* out_mqtt_payload_length)
 {
-  (void)options;
-
   _az_PRECONDITION_NOT_NULL(client);
-  _az_PRECONDITION_NOT_NULL(options);
   _az_PRECONDITION_NOT_NULL(mqtt_payload);
   _az_PRECONDITION(mqtt_payload_size > 0);
   _az_PRECONDITION_NOT_NULL(out_mqtt_payload_length);
@@ -665,7 +662,7 @@ AZ_NODISCARD az_result az_iot_provisioning_client_register_get_request_payload(
     _az_RETURN_IF_FAILED(az_json_writer_append_json_text(&json_writer, custom_payload_property));
   }
 
-  if (az_span_size(options->certificate_signing_request) > 0)
+  if (options != NULL && az_span_size(options->certificate_signing_request) > 0)
   {
     _az_RETURN_IF_FAILED(az_json_writer_append_property_name(&json_writer, prov_csr_request_label));
     _az_RETURN_IF_FAILED(

sdk/tests/iot/provisioning/test_az_iot_provisioning_client_register_get_request_payload.c

@@ -66,7 +66,7 @@ static void test_az_iot_provisioning_client_get_request_payload_NULL_client_fail
   uint8_t payload[TEST_PAYLOAD_RESERVE_SIZE];
   size_t payload_len;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ASSERT_PRECONDITION_CHECKED(az_iot_provisioning_client_get_request_payload(
       NULL, AZ_SPAN_EMPTY, NULL, payload, sizeof(payload), &payload_len));
   AZ_POP_WARNINGS
@@ -86,7 +86,7 @@ static void test_az_iot_provisioning_client_get_request_payload_non_NULL_reserve
   uint8_t payload[TEST_PAYLOAD_RESERVE_SIZE];
   size_t payload_len;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ASSERT_PRECONDITION_CHECKED(az_iot_provisioning_client_get_request_payload(
       &client,
       AZ_SPAN_EMPTY,
@@ -110,7 +110,7 @@ static void test_az_iot_provisioning_client_get_request_payload_NULL_mqtt_payloa
 
   size_t payload_len;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ASSERT_PRECONDITION_CHECKED(az_iot_provisioning_client_get_request_payload(
       &client, AZ_SPAN_EMPTY, NULL, NULL, 1, &payload_len));
   AZ_POP_WARNINGS
@@ -130,7 +130,7 @@ static void test_az_iot_provisioning_client_get_request_payload_zero_payload_siz
   uint8_t payload[TEST_PAYLOAD_RESERVE_SIZE];
   size_t payload_len;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ASSERT_PRECONDITION_CHECKED(az_iot_provisioning_client_get_request_payload(
       &client, AZ_SPAN_EMPTY, NULL, payload, 0, &payload_len));
   AZ_POP_WARNINGS
@@ -149,33 +149,15 @@ static void test_az_iot_provisioning_client_get_request_payload_NULL_payload_len
 
   uint8_t payload[TEST_PAYLOAD_RESERVE_SIZE];
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ASSERT_PRECONDITION_CHECKED(az_iot_provisioning_client_get_request_payload(
       &client, AZ_SPAN_EMPTY, NULL, payload, 1, NULL));
   AZ_POP_WARNINGS
 }
 
-static void test_az_iot_provisioning_client_register_get_request_payload_NULL_options_fails()
-{
-  az_iot_provisioning_client client;
-  az_result ret = az_iot_provisioning_client_init(
-      &client,
-      test_global_device_hostname,
-      AZ_SPAN_FROM_STR(TEST_ID_SCOPE),
-      AZ_SPAN_FROM_STR(TEST_REGISTRATION_ID),
-      NULL);
-  assert_int_equal(AZ_OK, ret);
-
-  uint8_t payload[TEST_PAYLOAD_RESERVE_SIZE];
-  size_t payload_len;
-
-  ASSERT_PRECONDITION_CHECKED(az_iot_provisioning_client_register_get_request_payload(
-      &client, AZ_SPAN_EMPTY, NULL, payload, 1, &payload_len));
-}
-
 #endif // AZ_NO_PRECONDITION_CHECKING
 
-static void test_az_iot_provisioning_client_get_request_payload_no_custom_payload()
+static void test_az_iot_provisioning_client_get_request_payload_no_custom_payload_succeed()
 {
   az_iot_provisioning_client client = { 0 };
   az_result ret = az_iot_provisioning_client_init(
@@ -193,7 +175,7 @@ static void test_az_iot_provisioning_client_get_request_payload_no_custom_payloa
   memset(payload, 0xCC, sizeof(payload));
   size_t payload_len = 0xBAADC0DE;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ret = az_iot_provisioning_client_get_request_payload(
       &client, AZ_SPAN_EMPTY, NULL, payload, sizeof(payload), &payload_len);
   AZ_POP_WARNINGS
@@ -203,7 +185,7 @@ static void test_az_iot_provisioning_client_get_request_payload_no_custom_payloa
   assert_int_equal((uint8_t)0xCC, payload[expected_payload_len]);
 }
 
-static void test_az_iot_provisioning_client_get_request_payload_custom_payload()
+static void test_az_iot_provisioning_client_get_request_payload_custom_payload_succeed()
 {
   az_iot_provisioning_client client = { 0 };
   az_result ret = az_iot_provisioning_client_init(
@@ -222,7 +204,7 @@ static void test_az_iot_provisioning_client_get_request_payload_custom_payload()
   memset(payload, 0xCC, sizeof(payload));
   size_t payload_len = 0xBAADC0DE;
 
-  AZ_IGNORE_DEPRECATIONS
+  AZ_PUSH_IGNORE_DEPRECATIONS
   ret = az_iot_provisioning_client_get_request_payload(
       &client, test_custom_payload, NULL, payload, sizeof(payload), &payload_len);
   assert_int_equal(AZ_OK, ret);
@@ -232,7 +214,7 @@ static void test_az_iot_provisioning_client_get_request_payload_custom_payload()
   AZ_POP_WARNINGS
 }
 
-static void test_az_iot_provisioning_client_register_get_request_payload_with_csr()
+static void test_az_iot_provisioning_client_register_get_request_payload_with_csr_succeed()
 {
   az_iot_provisioning_client client = { 0 };
   az_result ret = az_iot_provisioning_client_init(
@@ -267,6 +249,34 @@ static void test_az_iot_provisioning_client_register_get_request_payload_with_cs
   assert_int_equal((uint8_t)0xCC, payload[expected_payload_len]);
 }
 
+static void test_az_iot_provisioning_client_register_get_request_payload_NULL_options_succeed()
+{
+  az_iot_provisioning_client client = { 0 };
+  az_result ret = az_iot_provisioning_client_init(
+      &client,
+      test_global_device_hostname,
+      AZ_SPAN_FROM_STR(TEST_ID_SCOPE),
+      AZ_SPAN_FROM_STR(TEST_REGISTRATION_ID),
+      NULL);
+  assert_int_equal(AZ_OK, ret);
+
+  char expected_payload[]
+      = "{\"registrationId\":\"" TEST_REGISTRATION_ID "\",\"payload\":" TEST_CUSTOM_PAYLOAD "}";
+  size_t expected_payload_len = sizeof(expected_payload) - 1;
+
+  uint8_t payload[TEST_PAYLOAD_RESERVE_SIZE];
+  memset(payload, 0xCC, sizeof(payload));
+  size_t payload_len = 0xBAADC0DE;
+
+  ret = az_iot_provisioning_client_register_get_request_payload(
+      &client, test_custom_payload, NULL, payload, sizeof(payload), &payload_len);
+
+  assert_int_equal(AZ_OK, ret);
+  assert_int_equal(payload_len, expected_payload_len);
+  assert_memory_equal(expected_payload, payload, expected_payload_len);
+  assert_int_equal((uint8_t)0xCC, payload[expected_payload_len]);
+}
+
 int test_az_iot_provisioning_client_register_get_request_payload()
 {
 #ifndef AZ_NO_PRECONDITION_CHECKING
@@ -280,13 +290,13 @@ int test_az_iot_provisioning_client_register_get_request_payload()
     cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_NULL_mqtt_payload_fails),
     cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_zero_payload_size_fails),
     cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_NULL_payload_length_fails),
-    cmocka_unit_test(
-        test_az_iot_provisioning_client_register_get_request_payload_NULL_options_fails),
 #endif // AZ_NO_PRECONDITION_CHECKING
 
-    cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_no_custom_payload),
-    cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_custom_payload),
-    cmocka_unit_test(test_az_iot_provisioning_client_register_get_request_payload_with_csr),
+    cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_no_custom_payload_succeed),
+    cmocka_unit_test(test_az_iot_provisioning_client_get_request_payload_custom_payload_succeed),
+    cmocka_unit_test(test_az_iot_provisioning_client_register_get_request_payload_with_csr_succeed),
+    cmocka_unit_test(
+        test_az_iot_provisioning_client_register_get_request_payload_NULL_options_succeed),
   };
 
   return cmocka_run_group_tests_name("az_iot_provisioning_client_payload", tests, NULL, NULL);