Make AZ_RETURN_IF... internal. (Azure#1160)

sdk/inc/azure/core/az_result.h

@@ -41,31 +41,6 @@ enum
 #define _az_RESULT_MAKE_SUCCESS(facility, code) \
   ((int32_t)(((int32_t)(facility) << 16) | (int32_t)(code)))
 
-/**
- * @brief Convenience macro to return if an operation failed.
- */
-#define AZ_RETURN_IF_FAILED(exp) \
-  do \
-  { \
-    az_result const _result = (exp); \
-    if (az_result_failed(_result)) \
-    { \
-      return _result; \
-    } \
-  } while (0)
-
-/**
- * @brief Convenience macro to return if the provided span is not of the expected, required size.
- */
-#define AZ_RETURN_IF_NOT_ENOUGH_SIZE(span, required_size) \
-  do \
-  { \
-    if (az_span_size(span) < required_size || required_size < 0) \
-    { \
-      return AZ_ERROR_INSUFFICIENT_SPAN_SIZE; \
-    } \
-  } while (0)
-
 // az_result Bits:
 //   - 31 Severity (0 - success, 1 - failure).
 //   - 16..30 Facility.

sdk/inc/azure/core/internal/az_result_internal.h

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * @file
+ *
+ * @brief Definition of #az_result related internal helper functions.
+ *
+ * @note You MUST NOT use any symbols (macros, functions, structures, enums, etc.)
+ * prefixed with an underscore ('_') directly in your application code. These symbols
+ * are part of Azure SDK's internal implementation; we do not document these symbols
+ * and they are subject to change in future versions of the SDK which would break your code.
+ */
+
+#ifndef _az_RESULT_INTERNAL_H
+#define _az_RESULT_INTERNAL_H
+
+#include <azure/core/az_result.h>
+#include <azure/core/az_span.h>
+
+#include <stdint.h>
+
+#include <azure/core/_az_cfg_prefix.h>
+
+/**
+ * @brief Convenience macro to return if an operation failed.
+ */
+#define _az_RETURN_IF_FAILED(exp) \
+  do \
+  { \
+    az_result const _az_result = (exp); \
+    if (az_result_failed(_az_result)) \
+    { \
+      return _az_result; \
+    } \
+  } while (0)
+
+/**
+ * @brief Convenience macro to return if the provided span is not of the expected, required size.
+ */
+#define _az_RETURN_IF_NOT_ENOUGH_SIZE(span, required_size) \
+  do \
+  { \
+    int32_t const _az_req_sz = (required_size); \
+    if (az_span_size(span) < _az_req_sz || _az_req_sz < 0) \
+    { \
+      return AZ_ERROR_INSUFFICIENT_SPAN_SIZE; \
+    } \
+  } while (0)
+
+#include <azure/core/_az_cfg_suffix.h>
+
+#endif // _az_RESULT_INTERNAL_H

sdk/samples/iot/iot_sample_common.c

@@ -82,7 +82,7 @@ static az_result read_configuration_entry(
     (void)printf("%s = %s\n", env_name, hide_value ? "***" : env_value);
     az_span env_span = az_span_create_from_str(env_value);
 
-    AZ_RETURN_IF_NOT_ENOUGH_SIZE(destination, az_span_size(env_span));
+    IOT_SAMPLE_RETURN_IF_NOT_ENOUGH_SIZE(destination, az_span_size(env_span));
     az_span_copy(destination, env_span);
     *out_env_value = az_span_slice(destination, 0, az_span_size(env_span));
   }
@@ -105,7 +105,7 @@ az_result iot_sample_read_environment_variables(
   if (type == PAHO_IOT_HUB)
   {
     out_env_vars->hub_hostname = AZ_SPAN_FROM_BUFFER(iot_sample_hub_hostname_buffer);
-    AZ_RETURN_IF_FAILED(read_configuration_entry(
+    IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
         IOT_SAMPLE_ENV_HUB_HOSTNAME,
         NULL,
         false,
@@ -121,7 +121,7 @@ az_result iot_sample_read_environment_variables(
       case PAHO_IOT_HUB_TELEMETRY_SAMPLE:
       case PAHO_IOT_HUB_TWIN_SAMPLE:
         out_env_vars->hub_device_id = AZ_SPAN_FROM_BUFFER(iot_sample_hub_device_id_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_HUB_DEVICE_ID,
             NULL,
             false,
@@ -130,7 +130,7 @@ az_result iot_sample_read_environment_variables(
 
         out_env_vars->x509_cert_pem_file_path
             = AZ_SPAN_FROM_BUFFER(iot_sample_x509_cert_pem_file_path_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_DEVICE_X509_CERT_PEM_FILE_PATH,
             NULL,
             false,
@@ -140,15 +140,15 @@ az_result iot_sample_read_environment_variables(
 
       case PAHO_IOT_HUB_SAS_TELEMETRY_SAMPLE:
         out_env_vars->hub_device_id = AZ_SPAN_FROM_BUFFER(iot_sample_hub_device_id_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_HUB_SAS_DEVICE_ID,
             NULL,
             false,
             out_env_vars->hub_device_id,
             &(out_env_vars->hub_device_id)));
 
         out_env_vars->hub_sas_key = AZ_SPAN_FROM_BUFFER(iot_sample_hub_sas_key_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_HUB_SAS_KEY,
             NULL,
             true,
@@ -157,9 +157,10 @@ az_result iot_sample_read_environment_variables(
 
         char duration_buffer[IOT_SAMPLE_SAS_KEY_DURATION_TIME_DIGITS];
         az_span duration = AZ_SPAN_FROM_BUFFER(duration_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_SAS_KEY_DURATION_MINUTES, "120", false, duration, &duration));
-        AZ_RETURN_IF_FAILED(az_span_atou32(duration, &(out_env_vars->sas_key_duration_minutes)));
+        IOT_SAMPLE_RETURN_IF_FAILED(
+            az_span_atou32(duration, &(out_env_vars->sas_key_duration_minutes)));
         break;
 
       default:
@@ -171,7 +172,7 @@ az_result iot_sample_read_environment_variables(
   {
     out_env_vars->provisioning_id_scope
         = AZ_SPAN_FROM_BUFFER(iot_sample_provisioning_id_scope_buffer);
-    AZ_RETURN_IF_FAILED(read_configuration_entry(
+    IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
         IOT_SAMPLE_ENV_PROVISIONING_ID_SCOPE,
         NULL,
         false,
@@ -183,7 +184,7 @@ az_result iot_sample_read_environment_variables(
       case PAHO_IOT_PROVISIONING_SAMPLE:
         out_env_vars->provisioning_registration_id
             = AZ_SPAN_FROM_BUFFER(iot_sample_provisioning_registration_id_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_PROVISIONING_REGISTRATION_ID,
             NULL,
             false,
@@ -192,7 +193,7 @@ az_result iot_sample_read_environment_variables(
 
         out_env_vars->x509_cert_pem_file_path
             = AZ_SPAN_FROM_BUFFER(iot_sample_x509_cert_pem_file_path_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_DEVICE_X509_CERT_PEM_FILE_PATH,
             NULL,
             false,
@@ -203,7 +204,7 @@ az_result iot_sample_read_environment_variables(
       case PAHO_IOT_PROVISIONING_SAS_SAMPLE:
         out_env_vars->provisioning_registration_id
             = AZ_SPAN_FROM_BUFFER(iot_sample_provisioning_registration_id_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_PROVISIONING_SAS_REGISTRATION_ID,
             NULL,
             false,
@@ -212,7 +213,7 @@ az_result iot_sample_read_environment_variables(
 
         out_env_vars->provisioning_sas_key
             = AZ_SPAN_FROM_BUFFER(iot_sample_provisioning_sas_key_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_PROVISIONING_SAS_KEY,
             NULL,
             true,
@@ -221,9 +222,10 @@ az_result iot_sample_read_environment_variables(
 
         char duration_buffer[IOT_SAMPLE_SAS_KEY_DURATION_TIME_DIGITS];
         az_span duration = AZ_SPAN_FROM_BUFFER(duration_buffer);
-        AZ_RETURN_IF_FAILED(read_configuration_entry(
+        IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
             IOT_SAMPLE_ENV_SAS_KEY_DURATION_MINUTES, "120", false, duration, &duration));
-        AZ_RETURN_IF_FAILED(az_span_atou32(duration, &(out_env_vars->sas_key_duration_minutes)));
+        IOT_SAMPLE_RETURN_IF_FAILED(
+            az_span_atou32(duration, &(out_env_vars->sas_key_duration_minutes)));
         break;
 
       default:
@@ -239,7 +241,7 @@ az_result iot_sample_read_environment_variables(
 
   out_env_vars->x509_trust_pem_file_path
       = AZ_SPAN_FROM_BUFFER(iot_sample_x509_trust_pem_file_path_buffer);
-  AZ_RETURN_IF_FAILED(read_configuration_entry(
+  IOT_SAMPLE_RETURN_IF_FAILED(read_configuration_entry(
       IOT_SAMPLE_ENV_DEVICE_X509_TRUST_PEM_FILE_PATH,
       "",
       false,

sdk/samples/iot/iot_sample_common.h

@@ -18,42 +18,65 @@
 //
 // Logging
 //
-#define IOT_SAMPLE_LOG_ERROR(...)                                                  \
-  do                                                                               \
-  {                                                                                \
+#define IOT_SAMPLE_LOG_ERROR(...) \
+  do \
+  { \
     (void)fprintf(stderr, "ERROR:\t\t%s:%s():%d: ", __FILE__, __func__, __LINE__); \
-    (void)fprintf(stderr, __VA_ARGS__);                                            \
-    (void)fprintf(stderr, "\n");                                                   \
-    fflush(stdout);                                                                \
-    fflush(stderr);                                                                \
+    (void)fprintf(stderr, __VA_ARGS__); \
+    (void)fprintf(stderr, "\n"); \
+    fflush(stdout); \
+    fflush(stderr); \
   } while (0)
 
 #define IOT_SAMPLE_LOG_SUCCESS(...) \
-  do                                \
-  {                                 \
-    (void)printf("SUCCESS:\t");     \
-    (void)printf(__VA_ARGS__);      \
-    (void)printf("\n");             \
+  do \
+  { \
+    (void)printf("SUCCESS:\t"); \
+    (void)printf(__VA_ARGS__); \
+    (void)printf("\n"); \
   } while (0)
 
-#define IOT_SAMPLE_LOG(...)    \
-  do                           \
-  {                            \
-    (void)printf("\t\t");      \
+#define IOT_SAMPLE_LOG(...) \
+  do \
+  { \
+    (void)printf("\t\t"); \
     (void)printf(__VA_ARGS__); \
-    (void)printf("\n");        \
+    (void)printf("\n"); \
   } while (0)
 
-#define IOT_SAMPLE_LOG_AZ_SPAN(span_description, span)                       \
-  do                                                                         \
-  {                                                                          \
-    (void)printf("\t\t%s ", span_description);                               \
-    char* buffer = (char*)az_span_ptr(span);                                 \
+#define IOT_SAMPLE_LOG_AZ_SPAN(span_description, span) \
+  do \
+  { \
+    (void)printf("\t\t%s ", span_description); \
+    char* buffer = (char*)az_span_ptr(span); \
     for (int32_t az_span_i = 0; az_span_i < az_span_size(span); az_span_i++) \
-    {                                                                        \
-      putchar(*buffer++);                                                    \
-    }                                                                        \
-    (void)printf("\n");                                                      \
+    { \
+      putchar(*buffer++); \
+    } \
+    (void)printf("\n"); \
+  } while (0)
+
+//
+// Error handling
+//
+#define IOT_SAMPLE_RETURN_IF_FAILED(exp) \
+  do \
+  { \
+    az_result const _iot_sample_result = (exp); \
+    if (az_result_failed(_iot_sample_result)) \
+    { \
+      return _iot_sample_result; \
+    } \
+  } while (0)
+
+#define IOT_SAMPLE_RETURN_IF_NOT_ENOUGH_SIZE(span, required_size) \
+  do \
+  { \
+    int32_t _iot_sample_req_sz = (required_size); \
+    if (az_span_size(span) < _iot_sample_req_sz || _iot_sample_req_sz < 0) \
+    { \
+      return AZ_ERROR_INSUFFICIENT_SPAN_SIZE; \
+    } \
   } while (0)
 
 //
@@ -137,7 +160,8 @@ typedef enum
  * @return An #az_result value indicating the result of the operation.
  * @retval #AZ_OK All required environment variables successfully read-in.
  * @retval #AZ_ERROR_ARG Sample type or name is undefined, or environment variable is not set.
- * @retval #AZ_RETURN_IF_NOT_ENOUGH_SIZE Not enough space set aside to store environment variable.
+ * @retval #AZ_ERROR_INSUFFICIENT_SPAN_SIZE Not enough space set aside to store environment
+ * variable.
  */
 az_result iot_sample_read_environment_variables(
     iot_sample_type type,

sdk/samples/iot/paho_iot_hub_pnp_component_sample.c

@@ -25,9 +25,9 @@
 #include <azure/core/az_span.h>
 #include <azure/iot/az_iot_hub_client.h>
 
-#include "pnp/pnp_protocol.h"
 #include "pnp/pnp_device_info_component.h"
 #include "pnp/pnp_mqtt_message.h"
+#include "pnp/pnp_protocol.h"
 #include "pnp/pnp_thermostat_component.h"
 
 #define SAMPLE_TYPE PAHO_IOT_HUB
@@ -910,11 +910,11 @@ static az_result temp_controller_get_telemetry_message(pnp_mqtt_message* message
 
   // Build the telemetry message.
   az_json_writer jw;
-  AZ_RETURN_IF_FAILED(az_json_writer_init(&jw, message->payload_span, NULL));
-  AZ_RETURN_IF_FAILED(az_json_writer_append_begin_object(&jw));
-  AZ_RETURN_IF_FAILED(az_json_writer_append_property_name(&jw, working_set_name));
-  AZ_RETURN_IF_FAILED(az_json_writer_append_int32(&jw, working_set_ram_in_kibibytes));
-  AZ_RETURN_IF_FAILED(az_json_writer_append_end_object(&jw));
+  IOT_SAMPLE_RETURN_IF_FAILED(az_json_writer_init(&jw, message->payload_span, NULL));
+  IOT_SAMPLE_RETURN_IF_FAILED(az_json_writer_append_begin_object(&jw));
+  IOT_SAMPLE_RETURN_IF_FAILED(az_json_writer_append_property_name(&jw, working_set_name));
+  IOT_SAMPLE_RETURN_IF_FAILED(az_json_writer_append_int32(&jw, working_set_ram_in_kibibytes));
+  IOT_SAMPLE_RETURN_IF_FAILED(az_json_writer_append_end_object(&jw));
   message->out_payload_span = az_json_writer_get_bytes_used_in_destination(&jw);
 
   return rc;
@@ -935,14 +935,14 @@ static az_result append_json_token_callback(az_json_writer* jw, void* value)
   switch (value_token.kind)
   {
     case AZ_JSON_TOKEN_NUMBER:
-      AZ_RETURN_IF_FAILED(az_json_token_get_double(&value_token, &value_as_double));
-      AZ_RETURN_IF_FAILED(
+      IOT_SAMPLE_RETURN_IF_FAILED(az_json_token_get_double(&value_token, &value_as_double));
+      IOT_SAMPLE_RETURN_IF_FAILED(
           az_json_writer_append_double(jw, value_as_double, DOUBLE_DECIMAL_PLACE_DIGITS));
       break;
     case AZ_JSON_TOKEN_STRING:
-      AZ_RETURN_IF_FAILED(az_json_token_get_string(
+      IOT_SAMPLE_RETURN_IF_FAILED(az_json_token_get_string(
           &value_token, property_scratch_buffer, sizeof(property_scratch_buffer), &string_length));
-      AZ_RETURN_IF_FAILED(az_json_writer_append_string(
+      IOT_SAMPLE_RETURN_IF_FAILED(az_json_writer_append_string(
           jw, az_span_create((uint8_t*)property_scratch_buffer, string_length)));
       break;
     default: