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@48:cc5d91f2b06d, 2016-08-12 (annotated)

Committer:
AzureIoTClient
Date:
Fri Aug 12 10:04:01 2016 -0700
Revision:
48:cc5d91f2b06d
Parent:
38:a05929a75111
Child:
50:bbc71457b0ea
1.0.10

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 16:deba40344375 14
AzureIoTClient 16:deba40344375 15 #ifdef __cplusplus
AzureIoTClient 16:deba40344375 16 #include <cstddef>
Azure.IoT Build 36:67300d5a4c1f 17 #include <ctime>
Azure.IoT Build 36:67300d5a4c1f 18 #include <cstdint>
AzureIoTClient 16:deba40344375 19 extern "C"
AzureIoTClient 16:deba40344375 20 {
AzureIoTClient 16:deba40344375 21 #else
AzureIoTClient 16:deba40344375 22 #include <stddef.h>
Azure.IoT Build 36:67300d5a4c1f 23 #include <time.h>
Azure.IoT Build 36:67300d5a4c1f 24 #include <stdint.h>
AzureIoTClient 16:deba40344375 25 #endif
AzureIoTClient 16:deba40344375 26
AzureIoTClient 16:deba40344375 27 #define IOTHUB_MESSAGE_RESULT_VALUES \
AzureIoTClient 16:deba40344375 28 IOTHUB_MESSAGE_OK, \
AzureIoTClient 16:deba40344375 29 IOTHUB_MESSAGE_INVALID_ARG, \
AzureIoTClient 16:deba40344375 30 IOTHUB_MESSAGE_INVALID_TYPE, \
AzureIoTClient 16:deba40344375 31 IOTHUB_MESSAGE_ERROR \
AzureIoTClient 16:deba40344375 32
AzureIoTClient 16:deba40344375 33 /** @brief Enumeration specifying the status of calls to various
AzureIoTClient 16:deba40344375 34 * APIs in this module.
AzureIoTClient 16:deba40344375 35 */
AzureIoTClient 16:deba40344375 36 DEFINE_ENUM(IOTHUB_MESSAGE_RESULT, IOTHUB_MESSAGE_RESULT_VALUES);
AzureIoTClient 16:deba40344375 37
AzureIoTClient 16:deba40344375 38 #define IOTHUBMESSAGE_CONTENT_TYPE_VALUES \
AzureIoTClient 16:deba40344375 39 IOTHUBMESSAGE_BYTEARRAY, \
AzureIoTClient 16:deba40344375 40 IOTHUBMESSAGE_STRING, \
AzureIoTClient 16:deba40344375 41 IOTHUBMESSAGE_UNKNOWN \
AzureIoTClient 16:deba40344375 42
AzureIoTClient 16:deba40344375 43 /** @brief Enumeration specifying the content type of the a given
AzureIoTClient 16:deba40344375 44 * message.
AzureIoTClient 16:deba40344375 45 */
AzureIoTClient 16:deba40344375 46 DEFINE_ENUM(IOTHUBMESSAGE_CONTENT_TYPE, IOTHUBMESSAGE_CONTENT_TYPE_VALUES);
AzureIoTClient 16:deba40344375 47
AzureIoTClient 48:cc5d91f2b06d 48 typedef struct IOTHUB_MESSAGE_HANDLE_DATA_TAG* IOTHUB_MESSAGE_HANDLE;
AzureIoTClient 16:deba40344375 49
AzureIoTClient 16:deba40344375 50 /**
AzureIoTClient 16:deba40344375 51 * @brief Creates a new IoT hub message from a byte array. The type of the
AzureIoTClient 16:deba40344375 52 * message will be set to @c IOTHUBMESSAGE_BYTEARRAY.
AzureIoTClient 16:deba40344375 53 *
AzureIoTClient 16:deba40344375 54 * @param byteArray The byte array from which the message is to be created.
AzureIoTClient 16:deba40344375 55 * @param size The size of the byte array.
AzureIoTClient 16:deba40344375 56 *
AzureIoTClient 16:deba40344375 57 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 16:deba40344375 58 * created or @c NULL in case an error occurs.
AzureIoTClient 16:deba40344375 59 */
AzureIoTClient 16:deba40344375 60 extern IOTHUB_MESSAGE_HANDLE IoTHubMessage_CreateFromByteArray(const unsigned char* byteArray, size_t size);
AzureIoTClient 16:deba40344375 61
AzureIoTClient 16:deba40344375 62 /**
AzureIoTClient 16:deba40344375 63 * @brief Creates a new IoT hub message from a null terminated string. The
AzureIoTClient 16:deba40344375 64 * type of the message will be set to @c IOTHUBMESSAGE_STRING.
AzureIoTClient 16:deba40344375 65 *
AzureIoTClient 16:deba40344375 66 * @param source The null terminated string from which the message is to be
AzureIoTClient 16:deba40344375 67 * created.
AzureIoTClient 16:deba40344375 68 *
AzureIoTClient 16:deba40344375 69 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 16:deba40344375 70 * created or @c NULL in case an error occurs.
AzureIoTClient 16:deba40344375 71 */
AzureIoTClient 16:deba40344375 72 extern IOTHUB_MESSAGE_HANDLE IoTHubMessage_CreateFromString(const char* source);
AzureIoTClient 16:deba40344375 73
AzureIoTClient 16:deba40344375 74 /**
AzureIoTClient 16:deba40344375 75 * @brief Creates a new IoT hub message with the content identical to that
AzureIoTClient 16:deba40344375 76 * of the @p iotHubMessageHandle parameter.
AzureIoTClient 16:deba40344375 77 *
AzureIoTClient 16:deba40344375 78 * @param iotHubMessageHandle Handle to the message that is to be cloned.
AzureIoTClient 16:deba40344375 79 *
AzureIoTClient 16:deba40344375 80 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 16:deba40344375 81 * cloned or @c NULL in case an error occurs.
AzureIoTClient 16:deba40344375 82 */
AzureIoTClient 16:deba40344375 83 extern IOTHUB_MESSAGE_HANDLE IoTHubMessage_Clone(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 16:deba40344375 84
AzureIoTClient 16:deba40344375 85 /**
AzureIoTClient 16:deba40344375 86 * @brief Fetches a pointer and size for the data associated with the IoT
AzureIoTClient 16:deba40344375 87 * hub message handle. If the content type of the message is not
AzureIoTClient 16:deba40344375 88 * @c IOTHUBMESSAGE_BYTEARRAY then the function returns
AzureIoTClient 16:deba40344375 89 * @c IOTHUB_MESSAGE_INVALID_ARG.
AzureIoTClient 16:deba40344375 90 *
AzureIoTClient 16:deba40344375 91 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 92 * @param buffer Pointer to the memory location where the
AzureIoTClient 16:deba40344375 93 * pointer to the buffer will be written.
AzureIoTClient 16:deba40344375 94 * @param size The size of the buffer will be written to
AzureIoTClient 16:deba40344375 95 * this address.
AzureIoTClient 16:deba40344375 96 *
AzureIoTClient 16:deba40344375 97 * @return Returns IOTHUB_MESSAGE_OK if the byte array was fetched successfully
AzureIoTClient 16:deba40344375 98 * or an error code otherwise.
AzureIoTClient 16:deba40344375 99 */
AzureIoTClient 16:deba40344375 100 extern IOTHUB_MESSAGE_RESULT IoTHubMessage_GetByteArray(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle, const unsigned char** buffer, size_t* size);
AzureIoTClient 16:deba40344375 101
AzureIoTClient 16:deba40344375 102 /**
AzureIoTClient 16:deba40344375 103 * @brief Returns the null terminated string stored in the message.
AzureIoTClient 16:deba40344375 104 * If the content type of the message is not @c IOTHUBMESSAGE_STRING
AzureIoTClient 16:deba40344375 105 * then the function returns @c NULL.
AzureIoTClient 16:deba40344375 106 *
AzureIoTClient 16:deba40344375 107 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 108 *
AzureIoTClient 16:deba40344375 109 * @return @c NULL if an error occurs or a pointer to the stored null
AzureIoTClient 16:deba40344375 110 * terminated string otherwise.
AzureIoTClient 16:deba40344375 111 */
AzureIoTClient 16:deba40344375 112 extern const char* IoTHubMessage_GetString(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 16:deba40344375 113
AzureIoTClient 16:deba40344375 114 /**
AzureIoTClient 16:deba40344375 115 * @brief Returns the content type of the message given by parameter
AzureIoTClient 16:deba40344375 116 * @c iotHubMessageHandle.
AzureIoTClient 16:deba40344375 117 *
AzureIoTClient 16:deba40344375 118 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 119 *
AzureIoTClient 16:deba40344375 120 * @return An @c IOTHUBMESSAGE_CONTENT_TYPE value.
AzureIoTClient 16:deba40344375 121 */
AzureIoTClient 16:deba40344375 122 extern IOTHUBMESSAGE_CONTENT_TYPE IoTHubMessage_GetContentType(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 16:deba40344375 123
AzureIoTClient 16:deba40344375 124 /**
AzureIoTClient 16:deba40344375 125 * @brief Gets a handle to the message's properties map.
AzureIoTClient 16:deba40344375 126 *
AzureIoTClient 16:deba40344375 127 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 128 *
AzureIoTClient 16:deba40344375 129 * @return A @c MAP_HANDLE pointing to the properties map for this message.
AzureIoTClient 16:deba40344375 130 */
AzureIoTClient 16:deba40344375 131 extern MAP_HANDLE IoTHubMessage_Properties(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 16:deba40344375 132
AzureIoTClient 16:deba40344375 133 /**
AzureIoTClient 18:1e9adb15c645 134 * @brief Gets the MessageId from the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 135 *
AzureIoTClient 18:1e9adb15c645 136 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 137 *
AzureIoTClient 18:1e9adb15c645 138 * @return A const char* pointing to the Message Id.
AzureIoTClient 18:1e9adb15c645 139 */
AzureIoTClient 18:1e9adb15c645 140 extern const char* IoTHubMessage_GetMessageId(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 18:1e9adb15c645 141
AzureIoTClient 18:1e9adb15c645 142 /**
AzureIoTClient 18:1e9adb15c645 143 * @brief Sets the MessageId for the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 144 *
AzureIoTClient 18:1e9adb15c645 145 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 146 * @param messageId Pointer to the memory location of the messageId
AzureIoTClient 18:1e9adb15c645 147 *
AzureIoTClient 18:1e9adb15c645 148 * @return Returns IOTHUB_MESSAGE_OK if the messageId was set successfully
AzureIoTClient 18:1e9adb15c645 149 * or an error code otherwise.
AzureIoTClient 18:1e9adb15c645 150 */
AzureIoTClient 18:1e9adb15c645 151 extern IOTHUB_MESSAGE_RESULT IoTHubMessage_SetMessageId(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle, const char* messageId);
AzureIoTClient 18:1e9adb15c645 152
AzureIoTClient 18:1e9adb15c645 153 /**
AzureIoTClient 18:1e9adb15c645 154 * @brief Gets the CorrelationId from the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 155 *
AzureIoTClient 18:1e9adb15c645 156 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 157 *
AzureIoTClient 18:1e9adb15c645 158 * @return A const char* pointing to the Correlation Id.
AzureIoTClient 18:1e9adb15c645 159 */
AzureIoTClient 18:1e9adb15c645 160 extern const char* IoTHubMessage_GetCorrelationId(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 18:1e9adb15c645 161
AzureIoTClient 18:1e9adb15c645 162 /**
AzureIoTClient 18:1e9adb15c645 163 * @brief Sets the CorrelationId for the IOTHUB_MESSAGE_HANDLE.
AzureIoTClient 18:1e9adb15c645 164 *
AzureIoTClient 18:1e9adb15c645 165 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 18:1e9adb15c645 166 * @param correlationId Pointer to the memory location of the messageId
AzureIoTClient 18:1e9adb15c645 167 *
AzureIoTClient 18:1e9adb15c645 168 * @return Returns IOTHUB_MESSAGE_OK if the messageId was set successfully
AzureIoTClient 18:1e9adb15c645 169 * or an error code otherwise.
AzureIoTClient 18:1e9adb15c645 170 */
AzureIoTClient 18:1e9adb15c645 171 extern IOTHUB_MESSAGE_RESULT IoTHubMessage_SetCorrelationId(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle, const char* correlationId);
AzureIoTClient 18:1e9adb15c645 172
AzureIoTClient 18:1e9adb15c645 173 /**
AzureIoTClient 16:deba40344375 174 * @brief Frees all resources associated with the given message handle.
AzureIoTClient 16:deba40344375 175 *
AzureIoTClient 16:deba40344375 176 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 16:deba40344375 177 */
AzureIoTClient 16:deba40344375 178 extern void IoTHubMessage_Destroy(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 16:deba40344375 179
AzureIoTClient 16:deba40344375 180 #ifdef __cplusplus
AzureIoTClient 16:deba40344375 181 }
AzureIoTClient 16:deba40344375 182 #endif
AzureIoTClient 16:deba40344375 183
AzureIoTClient 16:deba40344375 184 #endif /* IOTHUB_MESSAGE_H */