Azure IoT / iothub_client

Microsoft Azure IoTHub client libraries

Dependents:   sht15_remote_monitoring RobotArmDemo iothub_client_sample_amqp f767zi_mqtt ... more

This library implements the Microsoft Azure IoTHub client library. The code is replicated from https://github.com/Azure/azure-iot-sdks

iothub_message.h@74:ea0021abecf7, 2017-08-25 (annotated)

Committer:
AzureIoTClient
Date:
Fri Aug 25 11:22:43 2017 -0700
Revision:
74:ea0021abecf7
Parent:
53:1e5a1ca1f274
Child:
77:e4e36df9caee
1.1.22

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AzureIoTClient 16:deba40344375 1 // Copyright (c) Microsoft. All rights reserved.
AzureIoTClient 16:deba40344375 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
AzureIoTClient 16:deba40344375 3
AzureIoTClient 16:deba40344375 4 /** @file iothub_message.h
AzureIoTClient 16:deba40344375 5 * @brief The @c IoTHub_Message component encapsulates one message that
AzureIoTClient 16:deba40344375 6 * can be transferred by an IoT hub client.
AzureIoTClient 16:deba40344375 7 */
AzureIoTClient 16:deba40344375 8
AzureIoTClient 16:deba40344375 9 #ifndef IOTHUB_MESSAGE_H
AzureIoTClient 16:deba40344375 10 #define IOTHUB_MESSAGE_H
AzureIoTClient 16:deba40344375 11
Azure.IoT Build 38:a05929a75111 12 #include "azure_c_shared_utility/macro_utils.h"
Azure.IoT Build 38:a05929a75111 13 #include "azure_c_shared_utility/map.h"
AzureIoTClient 53:1e5a1ca1f274 14 #include "azure_c_shared_utility/umock_c_prod.h"
AzureIoTClient 16:deba40344375 15
AzureIoTClient 16:deba40344375 16 #ifdef __cplusplus
AzureIoTClient 16:deba40344375 17 #include <cstddef>
AzureIoTClient 16:deba40344375 18 extern "C"
AzureIoTClient 16:deba40344375 19 {
AzureIoTClient 16:deba40344375 20 #else
AzureIoTClient 16:deba40344375 21 #include <stddef.h>
AzureIoTClient 16:deba40344375 22 #endif
AzureIoTClient 16:deba40344375 23
AzureIoTClient 16:deba40344375 24 #define IOTHUB_MESSAGE_RESULT_VALUES \
AzureIoTClient 16:deba40344375 25 IOTHUB_MESSAGE_OK, \
AzureIoTClient 16:deba40344375 26 IOTHUB_MESSAGE_INVALID_ARG, \
AzureIoTClient 16:deba40344375 27 IOTHUB_MESSAGE_INVALID_TYPE, \
AzureIoTClient 16:deba40344375 28 IOTHUB_MESSAGE_ERROR \
AzureIoTClient 16:deba40344375 29
AzureIoTClient 16:deba40344375 30 /** @brief Enumeration specifying the status of calls to various
AzureIoTClient 16:deba40344375 31 * APIs in this module.
AzureIoTClient 16:deba40344375 32 */
AzureIoTClient 16:deba40344375 33 DEFINE_ENUM(IOTHUB_MESSAGE_RESULT, IOTHUB_MESSAGE_RESULT_VALUES);
AzureIoTClient 16:deba40344375 34
AzureIoTClient 16:deba40344375 35 #define IOTHUBMESSAGE_CONTENT_TYPE_VALUES \
AzureIoTClient 16:deba40344375 36 IOTHUBMESSAGE_BYTEARRAY, \
AzureIoTClient 16:deba40344375 37 IOTHUBMESSAGE_STRING, \
AzureIoTClient 16:deba40344375 38 IOTHUBMESSAGE_UNKNOWN \
AzureIoTClient 16:deba40344375 39
AzureIoTClient 16:deba40344375 40 /** @brief Enumeration specifying the content type of the a given
AzureIoTClient 16:deba40344375 41 * message.
AzureIoTClient 16:deba40344375 42 */
AzureIoTClient 16:deba40344375 43 DEFINE_ENUM(IOTHUBMESSAGE_CONTENT_TYPE, IOTHUBMESSAGE_CONTENT_TYPE_VALUES);
AzureIoTClient 16:deba40344375 44
AzureIoTClient 48:cc5d91f2b06d 45 typedef struct IOTHUB_MESSAGE_HANDLE_DATA_TAG* IOTHUB_MESSAGE_HANDLE;
AzureIoTClient 16:deba40344375 46
AzureIoTClient 16:deba40344375 47 /**
AzureIoTClient 16:deba40344375 48 * @brief Creates a new IoT hub message from a byte array. The type of the
AzureIoTClient 16:deba40344375 49 * message will be set to @c IOTHUBMESSAGE_BYTEARRAY.
AzureIoTClient 16:deba40344375 50 *
AzureIoTClient 16:deba40344375 51 * @param byteArray The byte array from which the message is to be created.
AzureIoTClient 16:deba40344375 52 * @param size The size of the byte array.
AzureIoTClient 16:deba40344375 53 *
AzureIoTClient 16:deba40344375 54 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 16:deba40344375 55 * created or @c NULL in case an error occurs.
AzureIoTClient 16:deba40344375 56 */
AzureIoTClient 50:bbc71457b0ea 57 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_HANDLE, IoTHubMessage_CreateFromByteArray, const unsigned char*, byteArray, size_t, size);
AzureIoTClient 16:deba40344375 58
AzureIoTClient 16:deba40344375 59 /**
AzureIoTClient 16:deba40344375 60 * @brief Creates a new IoT hub message from a null terminated string. The
AzureIoTClient 16:deba40344375 61 * type of the message will be set to @c IOTHUBMESSAGE_STRING.
AzureIoTClient 16:deba40344375 62 *
AzureIoTClient 16:deba40344375 63 * @param source The null terminated string from which the message is to be
AzureIoTClient 16:deba40344375 64 * created.
AzureIoTClient 16:deba40344375 65 *
AzureIoTClient 16:deba40344375 66 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 16:deba40344375 67 * created or @c NULL in case an error occurs.
AzureIoTClient 16:deba40344375 68 */
AzureIoTClient 50:bbc71457b0ea 69 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_HANDLE, IoTHubMessage_CreateFromString, const char*, source);
AzureIoTClient 16:deba40344375 70
AzureIoTClient 16:deba40344375 71 /**
AzureIoTClient 16:deba40344375 72 * @brief Creates a new IoT hub message with the content identical to that
AzureIoTClient 16:deba40344375 73 * of the @p iotHubMessageHandle parameter.
AzureIoTClient 16:deba40344375 74 *
AzureIoTClient 16:deba40344375 75 * @param iotHubMessageHandle Handle to the message that is to be cloned.
AzureIoTClient 16:deba40344375 76 *
AzureIoTClient 16:deba40344375 77 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 16:deba40344375 78 * cloned or @c NULL in case an error occurs.
AzureIoTClient 16:deba40344375 79 */
AzureIoTClient 50:bbc71457b0ea 80 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_HANDLE, IoTHubMessage_Clone, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 16:deba40344375 81
AzureIoTClient 16:deba40344375 82 /**
AzureIoTClient 16:deba40344375 83 * @brief Fetches a pointer and size for the data associated with the IoT
AzureIoTClient 16:deba40344375 84 * hub message handle. If the content type of the message is not
AzureIoTClient 16:deba40344375 85 * @c IOTHUBMESSAGE_BYTEARRAY then the function returns
AzureIoTClient 16:deba40344375 86 * @c IOTHUB_MESSAGE_INVALID_ARG.
AzureIoTClient 16:deba40344375 87 *
AzureIoTClient 16:deba40344375 88 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 89 * @param buffer Pointer to the memory location where the
AzureIoTClient 16:deba40344375 90 * pointer to the buffer will be written.
AzureIoTClient 16:deba40344375 91 * @param size The size of the buffer will be written to
AzureIoTClient 16:deba40344375 92 * this address.
AzureIoTClient 16:deba40344375 93 *
AzureIoTClient 16:deba40344375 94 * @return Returns IOTHUB_MESSAGE_OK if the byte array was fetched successfully
AzureIoTClient 16:deba40344375 95 * or an error code otherwise.
AzureIoTClient 16:deba40344375 96 */
AzureIoTClient 50:bbc71457b0ea 97 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_GetByteArray, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const unsigned char**, buffer, size_t*, size);
AzureIoTClient 16:deba40344375 98
AzureIoTClient 16:deba40344375 99 /**
AzureIoTClient 16:deba40344375 100 * @brief Returns the null terminated string stored in the message.
AzureIoTClient 16:deba40344375 101 * If the content type of the message is not @c IOTHUBMESSAGE_STRING
AzureIoTClient 16:deba40344375 102 * then the function returns @c NULL.
AzureIoTClient 16:deba40344375 103 *
AzureIoTClient 16:deba40344375 104 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 105 *
AzureIoTClient 16:deba40344375 106 * @return @c NULL if an error occurs or a pointer to the stored null
AzureIoTClient 16:deba40344375 107 * terminated string otherwise.
AzureIoTClient 16:deba40344375 108 */
AzureIoTClient 50:bbc71457b0ea 109 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetString, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 16:deba40344375 110
AzureIoTClient 16:deba40344375 111 /**
AzureIoTClient 16:deba40344375 112 * @brief Returns the content type of the message given by parameter
AzureIoTClient 16:deba40344375 113 * @c iotHubMessageHandle.
AzureIoTClient 16:deba40344375 114 *
AzureIoTClient 16:deba40344375 115 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 116 *
AzureIoTClient 74:ea0021abecf7 117 * @remarks This function retrieves the standardized type of the payload, which indicates if @c iotHubMessageHandle was created using a String or a Byte Array.
AzureIoTClient 74:ea0021abecf7 118 *
AzureIoTClient 16:deba40344375 119 * @return An @c IOTHUBMESSAGE_CONTENT_TYPE value.
AzureIoTClient 16:deba40344375 120 */
AzureIoTClient 50:bbc71457b0ea 121 MOCKABLE_FUNCTION(, IOTHUBMESSAGE_CONTENT_TYPE, IoTHubMessage_GetContentType, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 16:deba40344375 122
AzureIoTClient 16:deba40344375 123 /**
AzureIoTClient 74:ea0021abecf7 124 * @brief Sets the content-type of the message payload, as per supported values on RFC 2046.
AzureIoTClient 74:ea0021abecf7 125 *
AzureIoTClient 74:ea0021abecf7 126 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 74:ea0021abecf7 127 *
AzureIoTClient 74:ea0021abecf7 128 * @param contentType String defining the type of the payload (e.g., text/plain).
AzureIoTClient 74:ea0021abecf7 129 *
AzureIoTClient 74:ea0021abecf7 130 * @return An @c IOTHUB_MESSAGE_RESULT value.
AzureIoTClient 74:ea0021abecf7 131 */
AzureIoTClient 74:ea0021abecf7 132 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_SetContentTypeSystemProperty, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const char*, contentType);
AzureIoTClient 74:ea0021abecf7 133
AzureIoTClient 74:ea0021abecf7 134 /**
AzureIoTClient 74:ea0021abecf7 135 * @brief Returns the content-type of the message payload, if defined.
AzureIoTClient 74:ea0021abecf7 136 *
AzureIoTClient 74:ea0021abecf7 137 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 74:ea0021abecf7 138 *
AzureIoTClient 74:ea0021abecf7 139 * @return A string with the content-type value if defined (or NULL otherwise).
AzureIoTClient 74:ea0021abecf7 140 */
AzureIoTClient 74:ea0021abecf7 141 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetContentTypeSystemProperty, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 74:ea0021abecf7 142
AzureIoTClient 74:ea0021abecf7 143 /**
AzureIoTClient 74:ea0021abecf7 144 * @brief Sets the content-encoding of the message payload, as per supported values on RFC 2616.
AzureIoTClient 74:ea0021abecf7 145 *
AzureIoTClient 74:ea0021abecf7 146 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 74:ea0021abecf7 147 *
AzureIoTClient 74:ea0021abecf7 148 * @param contentEncoding String defining the encoding of the payload (e.g., utf-8).
AzureIoTClient 74:ea0021abecf7 149 *
AzureIoTClient 74:ea0021abecf7 150 * @return An @c IOTHUB_MESSAGE_RESULT value.
AzureIoTClient 74:ea0021abecf7 151 */
AzureIoTClient 74:ea0021abecf7 152 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_SetContentEncodingSystemProperty, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const char*, contentEncoding);
AzureIoTClient 74:ea0021abecf7 153
AzureIoTClient 74:ea0021abecf7 154 /**
AzureIoTClient 74:ea0021abecf7 155 * @brief Returns the content-encoding of the message payload, if defined.
AzureIoTClient 74:ea0021abecf7 156 *
AzureIoTClient 74:ea0021abecf7 157 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 74:ea0021abecf7 158 *
AzureIoTClient 74:ea0021abecf7 159 * @return A string with the content-encoding value if defined (or NULL otherwise).
AzureIoTClient 74:ea0021abecf7 160 */
AzureIoTClient 74:ea0021abecf7 161 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetContentEncodingSystemProperty, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 74:ea0021abecf7 162
AzureIoTClient 74:ea0021abecf7 163 /**
AzureIoTClient 16:deba40344375 164 * @brief Gets a handle to the message's properties map.
AzureIoTClient 16:deba40344375 165 *
AzureIoTClient 16:deba40344375 166 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 167 *
AzureIoTClient 16:deba40344375 168 * @return A @c MAP_HANDLE pointing to the properties map for this message.
AzureIoTClient 16:deba40344375 169 */
AzureIoTClient 50:bbc71457b0ea 170 MOCKABLE_FUNCTION(, MAP_HANDLE, IoTHubMessage_Properties, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 16:deba40344375 171
AzureIoTClient 16:deba40344375 172 /**
AzureIoTClient 18:1e9adb15c645 173 * @brief Gets the MessageId from the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 174 *
AzureIoTClient 18:1e9adb15c645 175 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 176 *
AzureIoTClient 18:1e9adb15c645 177 * @return A const char* pointing to the Message Id.
AzureIoTClient 18:1e9adb15c645 178 */
AzureIoTClient 50:bbc71457b0ea 179 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetMessageId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 18:1e9adb15c645 180
AzureIoTClient 18:1e9adb15c645 181 /**
AzureIoTClient 18:1e9adb15c645 182 * @brief Sets the MessageId for the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 183 *
AzureIoTClient 18:1e9adb15c645 184 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 185 * @param messageId Pointer to the memory location of the messageId
AzureIoTClient 18:1e9adb15c645 186 *
AzureIoTClient 18:1e9adb15c645 187 * @return Returns IOTHUB_MESSAGE_OK if the messageId was set successfully
AzureIoTClient 18:1e9adb15c645 188 * or an error code otherwise.
AzureIoTClient 18:1e9adb15c645 189 */
AzureIoTClient 50:bbc71457b0ea 190 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_SetMessageId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const char*, messageId);
AzureIoTClient 18:1e9adb15c645 191
AzureIoTClient 18:1e9adb15c645 192 /**
AzureIoTClient 18:1e9adb15c645 193 * @brief Gets the CorrelationId from the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 194 *
AzureIoTClient 18:1e9adb15c645 195 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 196 *
AzureIoTClient 18:1e9adb15c645 197 * @return A const char* pointing to the Correlation Id.
AzureIoTClient 18:1e9adb15c645 198 */
AzureIoTClient 50:bbc71457b0ea 199 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetCorrelationId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 18:1e9adb15c645 200
AzureIoTClient 18:1e9adb15c645 201 /**
AzureIoTClient 18:1e9adb15c645 202 * @brief Sets the CorrelationId for the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 203 *
AzureIoTClient 18:1e9adb15c645 204 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 205 * @param correlationId Pointer to the memory location of the messageId
AzureIoTClient 18:1e9adb15c645 206 *
AzureIoTClient 18:1e9adb15c645 207 * @return Returns IOTHUB_MESSAGE_OK if the messageId was set successfully
AzureIoTClient 18:1e9adb15c645 208 * or an error code otherwise.
AzureIoTClient 18:1e9adb15c645 209 */
AzureIoTClient 50:bbc71457b0ea 210 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_SetCorrelationId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const char*, correlationId);
AzureIoTClient 18:1e9adb15c645 211
AzureIoTClient 18:1e9adb15c645 212 /**
AzureIoTClient 16:deba40344375 213 * @brief Frees all resources associated with the given message handle.
AzureIoTClient 16:deba40344375 214 *
AzureIoTClient 16:deba40344375 215 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 216 */
AzureIoTClient 50:bbc71457b0ea 217 MOCKABLE_FUNCTION(, void, IoTHubMessage_Destroy, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
AzureIoTClient 16:deba40344375 218
AzureIoTClient 16:deba40344375 219 #ifdef __cplusplus
AzureIoTClient 16:deba40344375 220 }
AzureIoTClient 16:deba40344375 221 #endif
AzureIoTClient 16:deba40344375 222
AzureIoTClient 16:deba40344375 223 #endif /* IOTHUB_MESSAGE_H */