Rename az_iot_hub_client_properties to az_iot_message_properties (Azu…

…re#1124)

CHANGELOG.md

@@ -5,10 +5,12 @@
 ### New Features
 
 - Add `az_json_writer_append_json_text()` to support appending existing JSON with the JSON writer.
-- Add supported, system properties for IoT Hub messages to az_iot_common.h
+- Add support for system properties for IoT Hub messages to `az_iot_common.h`.
 
 ### Breaking Changes
 
+- 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`.
+
 ### Bug Fixes
 
 ### Other Changes and Improvements

sdk/docs/iot/README.md

@@ -137,7 +137,7 @@ int main()
 
 ### Properties
 
-Included in the Azure SDK for Embedded C are helper functions to form and manage properties for IoT Hub services. Implementation starts by using the `az_iot_hub_client_properties_init()` API. The user is free to initialize using an empty, but appropriately sized, span to later append properties or an already populated span containing a properly formatted property buffer. "Properly formatted" properties follow the form `{key}={value}&{key}={value}`.
+Included in the Azure SDK for Embedded C are helper functions to form and manage properties for IoT Hub services. Implementation starts by using the `az_iot_message_properties_init()` API. The user is free to initialize using an empty, but appropriately sized, span to later append properties or an already populated span containing a properly formatted property buffer. "Properly formatted" properties follow the form `{key}={value}&{key}={value}`.
 
 Below is an example use case of appending properties.
 
@@ -150,10 +150,10 @@ void my_property_func()
   az_span property_span = az_span_create(property_buffer, sizeof(property_buffer));
 
   //Initialize the property struct with the span
-  az_iot_hub_client_properties props;
-  az_iot_hub_client_properties_init(&props, property_span, 0);
+  az_iot_message_properties props;
+  az_iot_message_properties_init(&props, property_span, 0);
   //Append properties
-  az_iot_hub_client_properties_append(&props, AZ_SPAN_FROM_STR("key"), AZ_SPAN_FROM_STR("value"));
+  az_iot_message_properties_append(&props, AZ_SPAN_FROM_STR("key"), AZ_SPAN_FROM_STR("value"));
   //At this point, you are able to pass the `props` to other APIs with property parameters.
 }
 ```
@@ -166,8 +166,8 @@ static az_span my_prop_span = AZ_SPAN_LITERAL_FROM_STR("my_device=contoso&my_key
 void my_property_func()
 {
   //Initialize the property struct with the span
-  az_iot_hub_client_properties props;
-  az_iot_hub_client_properties_init(&props, my_prop_span, az_span_size(my_prop_span));
+  az_iot_message_properties props;
+  az_iot_message_properties_init(&props, my_prop_span, az_span_size(my_prop_span));
   //At this point, you are able to pass the `props` to other APIs with property parameters.
 }
 ```

sdk/docs/iot/resources/iot_hub_flow.puml

@@ -74,7 +74,7 @@ az_iot_hub_client_sas_get_signature : - token_expiration_epoch_time
 az_iot_hub_client_sas_get_password: - Base64(HMAC-SHA256(signature, SharedAccessKey))
 az_iot_hub_client_sas_get_password: - key_name
 
-az_iot_hub_client_telemetry_get_publish_topic : - az_iot_hub_client_properties
+az_iot_hub_client_telemetry_get_publish_topic : - az_iot_message_properties
 
 state az_iot_hub_client_method_request <<STRUCT>>
 az_iot_hub_client_method_request: - request_id
@@ -84,7 +84,7 @@ az_iot_hub_client_methods_response_get_publish_topic: - request_id
 az_iot_hub_client_methods_response_get_publish_topic: - status
 
 state az_iot_hub_client_c2d_request <<STRUCT>>
-az_iot_hub_client_c2d_request : - az_iot_hub_client_properties
+az_iot_hub_client_c2d_request : - az_iot_message_properties
 
 az_iot_hub_client_twin_document_get_publish_topic : - request_id
 

sdk/inc/azure/iot/az_iot_common.h

@@ -61,17 +61,112 @@ typedef enum
   AZ_IOT_STATUS_TIMEOUT = 504,
 } az_iot_status;
 
+
 /**
- * @brief Supported IoT Hub message properties
+ *
+ * Properties APIs
+ *
+ *   IoT message properties are used for Device-to-Cloud (D2C) as well as Cloud-to-Device (C2D).
+ *   Properties are always appended to the MQTT topic of the published or received message and
+ *   must contain Uri-encoded keys and values.
  */
-#define AZ_IOT_HUB_MESSAGE_PROPERTIES_MESSAGE_ID \
+/**
+ * @brief Supported IoT message properties
+ */
+#define AZ_IOT_MESSAGE_PROPERTIES_MESSAGE_ID \
   "%24.mid" /**< Add unique identification to a message */
-#define AZ_IOT_HUB_MESSAGE_PROPERTIES_CORRELATION_ID \
+#define AZ_IOT_MESSAGE_PROPERTIES_CORRELATION_ID \
   "%24.cid" /**< Used in distributed tracing. More information here: \
 https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-distributed-tracing */
-#define AZ_IOT_HUB_MESSAGE_PROPERTIES_CONTENT_TYPE \
+#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_TYPE \
   "%24.ct" /**< URL encoded and of the form text%2Fplain or application%2Fjson, etc */
-#define AZ_IOT_HUB_MESSAGE_PROPERTIES_CONTENT_ENCODING "%24.ce" /**< UTF-8, UTF-16, etc */
+#define AZ_IOT_MESSAGE_PROPERTIES_CONTENT_ENCODING "%24.ce" /**< UTF-8, UTF-16, etc */
+
+/**
+ * @brief Telemetry or C2D properties.
+ *
+ */
+typedef struct
+{
+  struct
+  {
+    az_span properties_buffer;
+    int32_t properties_written;
+    uint32_t current_property_index;
+  } _internal;
+} az_iot_message_properties;
+
+/**
+ * @brief Initializes the Telemetry or C2D properties.
+ *
+ * @note The properties init API will not encode properties. In order to support
+ *       the following characters, they must be percent-encoded (RFC3986) as follows:
+ *          `/` : `%2F`
+ *          `%` : `%25`
+ *          `#` : `%23`
+ *          `&` : `%26`
+ *       Only these characters would have to be encoded. If you would like to avoid the need to
+ *       encode the names/values, avoid using these characters in names and values.
+ *
+ * @param[in] properties The #az_iot_message_properties to initialize
+ * @param[in] buffer Can either be an empty #az_span or an #az_span containing properly formatted
+ *                   (with above mentioned characters encoded if applicable) properties with the
+ *                   following format: {key}={value}&{key}={value}.
+ * @param[in] written_length The length of the properly formatted properties already initialized
+ * within the buffer. If the \p buffer is empty (uninitialized), this should be 0.
+ * @return #az_result
+ */
+AZ_NODISCARD az_result az_iot_message_properties_init(
+    az_iot_message_properties* properties,
+    az_span buffer,
+    int32_t written_length);
+
+/**
+ * @brief Appends a key-value property to the list of properties.
+ *
+ * @note The properties append API will not encode properties. In order to support
+ *       the following characters, they must be percent-encoded (RFC3986) as follows:
+ *          `/` : `%2F`
+ *          `%` : `%25`
+ *          `#` : `%23`
+ *          `&` : `%26`
+ *       Only these characters would have to be encoded. If you would like to avoid the need to
+ *       encode the names/values, avoid using these characters in names and values.
+ *
+ * @param[in] properties The #az_iot_message_properties to use for this call
+ * @param[in] name The name of the property.
+ * @param[in] value The value of the property.
+ * @return #az_result
+ */
+AZ_NODISCARD az_result az_iot_message_properties_append(
+    az_iot_message_properties* properties,
+    az_span name,
+    az_span value);
+
+/**
+ * @brief Finds the value of a property.
+ * @remark This will return the first value of the property with the given name if multiple
+ * properties with the same key exist.
+ *
+ * @param[in] properties The #az_iot_message_properties to use for this call
+ * @param[in] name The name of the property.
+ * @param[out] out_value An #az_span containing the value of the property.
+ * @return #az_result.
+ */
+AZ_NODISCARD az_result az_iot_message_properties_find(
+    az_iot_message_properties* properties,
+    az_span name,
+    az_span* out_value);
+
+/**
+ * @brief Iterates over the list of properties.
+ *
+ * @param[in] properties The #az_iot_message_properties to use for this call
+ * @param[out] out An #az_pair containing the key and the value of the next property.
+ * @return #az_result
+ */
+AZ_NODISCARD az_result
+az_iot_message_properties_next(az_iot_message_properties* properties, az_pair* out);
 
 /**
  * @brief Checks if the status indicates a successful operation.

sdk/inc/azure/iot/az_iot_hub_client.h

@@ -210,100 +210,6 @@ AZ_NODISCARD az_result az_iot_hub_client_sas_get_password(
     size_t mqtt_password_size,
     size_t* out_mqtt_password_length);
 
-/**
- *
- * Properties APIs
- *
- *   IoT Hub message properties are used for Device-to-Cloud (D2C) as well as Cloud-to-Device (C2D).
- *   Properties are always appended to the MQTT topic of the published or received message and
- *   must contain Uri-encoded keys and values.
- */
-
-/**
- * @brief Telemetry or C2D properties.
- *
- */
-typedef struct
-{
-  struct
-  {
-    az_span properties_buffer;
-    int32_t properties_written;
-    uint32_t current_property_index;
-  } _internal;
-} az_iot_hub_client_properties;
-
-/**
- * @brief Initializes the Telemetry or C2D properties.
- *
- * @note The properties init API will not encode properties. In order to support
- *       the following characters, they must be percent-encoded (RFC3986) as follows:
- *          `/` : `%2F`
- *          `%` : `%25`
- *          `#` : `%23`
- *          `&` : `%26`
- *       Only these characters would have to be encoded. If you would like to avoid the need to
- *       encode the names/values, avoid using these characters in names and values.
- *
- * @param[in] properties The #az_iot_hub_client_properties to initialize
- * @param[in] buffer Can either be an empty #az_span or an #az_span containing properly formatted
- *                   (with above mentioned characters encoded if applicable) properties with the
- *                   following format: {key}={value}&{key}={value}.
- * @param[in] written_length The length of the properly formatted properties already initialized
- * within the buffer. If the \p buffer is empty (uninitialized), this should be 0.
- * @return #az_result
- */
-AZ_NODISCARD az_result az_iot_hub_client_properties_init(
-    az_iot_hub_client_properties* properties,
-    az_span buffer,
-    int32_t written_length);
-
-/**
- * @brief Appends a key-value property to the list of properties.
- *
- * @note The properties append API will not encode properties. In order to support
- *       the following characters, they must be percent-encoded (RFC3986) as follows:
- *          `/` : `%2F`
- *          `%` : `%25`
- *          `#` : `%23`
- *          `&` : `%26`
- *       Only these characters would have to be encoded. If you would like to avoid the need to
- *       encode the names/values, avoid using these characters in names and values.
- *
- * @param[in] properties The #az_iot_hub_client_properties to use for this call
- * @param[in] name The name of the property.
- * @param[in] value The value of the property.
- * @return #az_result
- */
-AZ_NODISCARD az_result az_iot_hub_client_properties_append(
-    az_iot_hub_client_properties* properties,
-    az_span name,
-    az_span value);
-
-/**
- * @brief Finds the value of a property.
- * @remark This will return the first value of the property with the given name if multiple
- * properties with the same key exist.
- *
- * @param[in] properties The #az_iot_hub_client_properties to use for this call
- * @param[in] name The name of the property.
- * @param[out] out_value An #az_span containing the value of the property.
- * @return #az_result.
- */
-AZ_NODISCARD az_result az_iot_hub_client_properties_find(
-    az_iot_hub_client_properties* properties,
-    az_span name,
-    az_span* out_value);
-
-/**
- * @brief Iterates over the list of properties.
- *
- * @param[in] properties The #az_iot_hub_client_properties to use for this call
- * @param[out] out An #az_pair containing the key and the value of the next property.
- * @return #az_result
- */
-AZ_NODISCARD az_result
-az_iot_hub_client_properties_next(az_iot_hub_client_properties* properties, az_pair* out);
 
 /**
  *
@@ -317,7 +223,7 @@ az_iot_hub_client_properties_next(az_iot_hub_client_properties* properties, az_p
  * @remark This topic can also be used to set the MQTT Will message in the Connect message.
  *
  * @param[in] client The #az_iot_hub_client to use for this call.
- * @param[in] properties An optional #az_iot_hub_client_properties object (can be NULL).
+ * @param[in] properties An optional #az_iot_message_properties object (can be NULL).
  * @param[out] mqtt_topic A buffer with sufficient capacity to hold the MQTT topic. If
  *                        successful, contains a null-terminated string with the topic that
  *                        needs to be passed to the MQTT client.
@@ -328,7 +234,7 @@ az_iot_hub_client_properties_next(az_iot_hub_client_properties* properties, az_p
  */
 AZ_NODISCARD az_result az_iot_hub_client_telemetry_get_publish_topic(
     az_iot_hub_client const* client,
-    az_iot_hub_client_properties const* properties,
+    az_iot_message_properties const* properties,
     char* mqtt_topic,
     size_t mqtt_topic_size,
     size_t* out_mqtt_topic_length);
@@ -351,7 +257,7 @@ AZ_NODISCARD az_result az_iot_hub_client_telemetry_get_publish_topic(
  */
 typedef struct
 {
-  az_iot_hub_client_properties properties; /**< The properties associated with this C2D request. */
+  az_iot_message_properties properties; /**< The properties associated with this C2D request. */
 } az_iot_hub_client_c2d_request;
 
 /**

sdk/samples/iot/sample_pnp.c

@@ -144,25 +144,25 @@ static az_result is_component_in_model(
 // Get the telemetry topic for PnP
 az_result pnp_get_telemetry_topic(
     const az_iot_hub_client* client,
-    az_iot_hub_client_properties* properties,
+    az_iot_message_properties* properties,
     az_span component_name,
     char* mqtt_topic,
     size_t mqtt_topic_size,
     size_t* out_mqtt_topic_length)
 {
-  az_iot_hub_client_properties pnp_properties;
+  az_iot_message_properties pnp_properties;
 
   if (az_span_ptr(component_name) != NULL)
   {
     if (properties == NULL)
     {
       properties = &pnp_properties;
 
-      AZ_RETURN_IF_FAILED(az_iot_hub_client_properties_init(
+      AZ_RETURN_IF_FAILED(az_iot_message_properties_init(
           properties, AZ_SPAN_FROM_BUFFER(pnp_properties_buffer), 0));
     }
 
-    AZ_RETURN_IF_FAILED(az_iot_hub_client_properties_append(
+    AZ_RETURN_IF_FAILED(az_iot_message_properties_append(
         properties, component_telemetry_prop_span, component_name));
   }
 

sdk/samples/iot/sample_pnp.h

@@ -35,7 +35,7 @@ typedef az_result (*pnp_append_property_callback)(az_json_writer* jw, void* cont
  * @remark This topic can also be used to set the MQTT Will message in the Connect message.
  *
  * @param[in] client The #az_iot_hub_client to use for this call.
- * @param[in] properties An optional #az_iot_hub_client_properties object (can be NULL).
+ * @param[in] properties An optional #az_iot_message_properties object (can be NULL).
  * @param[in] component_name An optional component name if the telemetry is being sent from a
  *                           sub-component.
  * @param[out] mqtt_topic A buffer with sufficient capacity to hold the MQTT topic. If
@@ -48,7 +48,7 @@ typedef az_result (*pnp_append_property_callback)(az_json_writer* jw, void* cont
  */
 az_result pnp_get_telemetry_topic(
     const az_iot_hub_client* client,
-    az_iot_hub_client_properties* properties,
+    az_iot_message_properties* properties,
     az_span component_name,
     char* mqtt_topic,
     size_t mqtt_topic_size,