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@10:38383e246675, 2015-09-26 (annotated)

Committer:
AzureIoTClient
Date:
Sat Sep 26 00:18:01 2015 -0700
Revision:
10:38383e246675
Parent:
0:e393db310d89 
v1.0.0-preview.3

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AzureIoTClient 0:e393db310d89 1 // Copyright (c) Microsoft. All rights reserved.
AzureIoTClient 0:e393db310d89 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
AzureIoTClient 0:e393db310d89 3
AzureIoTClient 10:38383e246675 4 /** @file iothub_message.h
AzureIoTClient 10:38383e246675 5 * @brief The @c IoTHub_Message component encapsulates one message that
AzureIoTClient 10:38383e246675 6 * can be transferred by an IoT hub client.
AzureIoTClient 10:38383e246675 7 */
AzureIoTClient 10:38383e246675 8
AzureIoTClient 0:e393db310d89 9 #ifndef IOTHUB_MESSAGE_H
AzureIoTClient 0:e393db310d89 10 #define IOTHUB_MESSAGE_H
AzureIoTClient 0:e393db310d89 11
AzureIoTClient 0:e393db310d89 12 #include "macro_utils.h"
AzureIoTClient 0:e393db310d89 13 #include "map.h"
AzureIoTClient 0:e393db310d89 14
AzureIoTClient 0:e393db310d89 15 #ifdef __cplusplus
AzureIoTClient 0:e393db310d89 16 #include <cstddef>
AzureIoTClient 0:e393db310d89 17 extern "C"
AzureIoTClient 0:e393db310d89 18 {
AzureIoTClient 0:e393db310d89 19 #else
AzureIoTClient 0:e393db310d89 20 #include <stddef.h>
AzureIoTClient 0:e393db310d89 21 #endif
AzureIoTClient 0:e393db310d89 22
AzureIoTClient 0:e393db310d89 23 #define IOTHUB_MESSAGE_RESULT_VALUES \
AzureIoTClient 0:e393db310d89 24 IOTHUB_MESSAGE_OK, \
AzureIoTClient 0:e393db310d89 25 IOTHUB_MESSAGE_INVALID_ARG, \
AzureIoTClient 0:e393db310d89 26 IOTHUB_MESSAGE_INVALID_TYPE, \
AzureIoTClient 0:e393db310d89 27 IOTHUB_MESSAGE_ERROR \
AzureIoTClient 0:e393db310d89 28
AzureIoTClient 10:38383e246675 29 /** @brief Enumeration specifying the status of calls to various
AzureIoTClient 10:38383e246675 30 * APIs in this module.
AzureIoTClient 10:38383e246675 31 */
AzureIoTClient 0:e393db310d89 32 DEFINE_ENUM(IOTHUB_MESSAGE_RESULT, IOTHUB_MESSAGE_RESULT_VALUES);
AzureIoTClient 0:e393db310d89 33
AzureIoTClient 0:e393db310d89 34 #define IOTHUBMESSAGE_CONTENT_TYPE_VALUES \
AzureIoTClient 0:e393db310d89 35 IOTHUBMESSAGE_BYTEARRAY, \
AzureIoTClient 0:e393db310d89 36 IOTHUBMESSAGE_STRING, \
AzureIoTClient 0:e393db310d89 37 IOTHUBMESSAGE_UNKNOWN \
AzureIoTClient 0:e393db310d89 38
AzureIoTClient 10:38383e246675 39 /** @brief Enumeration specifying the content type of the a given
AzureIoTClient 10:38383e246675 40 * message.
AzureIoTClient 10:38383e246675 41 */
AzureIoTClient 0:e393db310d89 42 DEFINE_ENUM(IOTHUBMESSAGE_CONTENT_TYPE, IOTHUBMESSAGE_CONTENT_TYPE_VALUES);
AzureIoTClient 0:e393db310d89 43
AzureIoTClient 0:e393db310d89 44 typedef void* IOTHUB_MESSAGE_HANDLE;
AzureIoTClient 0:e393db310d89 45
AzureIoTClient 10:38383e246675 46 /**
AzureIoTClient 10:38383e246675 47 * @brief Creates a new IoT hub message from a byte array. The type of the
AzureIoTClient 10:38383e246675 48 * message will be set to @c IOTHUBMESSAGE_BYTEARRAY.
AzureIoTClient 10:38383e246675 49 *
AzureIoTClient 10:38383e246675 50 * @param byteArray The byte array from which the message is to be created.
AzureIoTClient 10:38383e246675 51 * @param size The size of the byte array.
AzureIoTClient 10:38383e246675 52 *
AzureIoTClient 10:38383e246675 53 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 10:38383e246675 54 * created or @c NULL in case an error occurs.
AzureIoTClient 10:38383e246675 55 */
AzureIoTClient 0:e393db310d89 56 extern IOTHUB_MESSAGE_HANDLE IoTHubMessage_CreateFromByteArray(const unsigned char* byteArray, size_t size);
AzureIoTClient 10:38383e246675 57
AzureIoTClient 10:38383e246675 58 /**
AzureIoTClient 10:38383e246675 59 * @brief Creates a new IoT hub message from a null terminated string. The
AzureIoTClient 10:38383e246675 60 * type of the message will be set to @c IOTHUBMESSAGE_STRING.
AzureIoTClient 10:38383e246675 61 *
AzureIoTClient 10:38383e246675 62 * @param source The null terminated string from which the message is to be
AzureIoTClient 10:38383e246675 63 * created.
AzureIoTClient 10:38383e246675 64 *
AzureIoTClient 10:38383e246675 65 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 10:38383e246675 66 * created or @c NULL in case an error occurs.
AzureIoTClient 10:38383e246675 67 */
AzureIoTClient 0:e393db310d89 68 extern IOTHUB_MESSAGE_HANDLE IoTHubMessage_CreateFromString(const char* source);
AzureIoTClient 0:e393db310d89 69
AzureIoTClient 10:38383e246675 70 /**
AzureIoTClient 10:38383e246675 71 * @brief Creates a new IoT hub message with the content identical to that
AzureIoTClient 10:38383e246675 72 * of the @p iotHubMessageHandle parameter.
AzureIoTClient 10:38383e246675 73 *
AzureIoTClient 10:38383e246675 74 * @param iotHubMessageHandle Handle to the message that is to be cloned.
AzureIoTClient 10:38383e246675 75 *
AzureIoTClient 10:38383e246675 76 * @return A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
AzureIoTClient 10:38383e246675 77 * cloned or @c NULL in case an error occurs.
AzureIoTClient 10:38383e246675 78 */
AzureIoTClient 0:e393db310d89 79 extern IOTHUB_MESSAGE_HANDLE IoTHubMessage_Clone(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 0:e393db310d89 80
AzureIoTClient 10:38383e246675 81 /**
AzureIoTClient 10:38383e246675 82 * @brief Fetches a pointer and size for the data associated with the IoT
AzureIoTClient 10:38383e246675 83 * hub message handle. If the content type of the message is not
AzureIoTClient 10:38383e246675 84 * @c IOTHUBMESSAGE_BYTEARRAY then the function returns
AzureIoTClient 10:38383e246675 85 * @c IOTHUB_MESSAGE_INVALID_ARG.
AzureIoTClient 10:38383e246675 86 *
AzureIoTClient 10:38383e246675 87 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 10:38383e246675 88 * @param buffer Pointer to the memory location where the
AzureIoTClient 10:38383e246675 89 * pointer to the buffer will be written.
AzureIoTClient 10:38383e246675 90 * @param size The size of the buffer will be written to
AzureIoTClient 10:38383e246675 91 * this address.
AzureIoTClient 10:38383e246675 92 *
AzureIoTClient 10:38383e246675 93 * @return Returns IOTHUB_MESSAGE_OK if the byte array was fetched successfully
AzureIoTClient 10:38383e246675 94 * or an error code otherwise.
AzureIoTClient 10:38383e246675 95 */
AzureIoTClient 0:e393db310d89 96 extern IOTHUB_MESSAGE_RESULT IoTHubMessage_GetByteArray(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle, const unsigned char** buffer, size_t* size);
AzureIoTClient 10:38383e246675 97
AzureIoTClient 10:38383e246675 98 /**
AzureIoTClient 10:38383e246675 99 * @brief Returns the null terminated string stored in the message.
AzureIoTClient 10:38383e246675 100 * If the content type of the message is not @c IOTHUBMESSAGE_STRING
AzureIoTClient 10:38383e246675 101 * then the function returns @c NULL.
AzureIoTClient 10:38383e246675 102 *
AzureIoTClient 10:38383e246675 103 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 10:38383e246675 104 *
AzureIoTClient 10:38383e246675 105 * @return @c NULL if an error occurs or a pointer to the stored null
AzureIoTClient 10:38383e246675 106 * terminated string otherwise.
AzureIoTClient 10:38383e246675 107 */
AzureIoTClient 0:e393db310d89 108 extern const char* IoTHubMessage_GetString(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 10:38383e246675 109
AzureIoTClient 10:38383e246675 110 /**
AzureIoTClient 10:38383e246675 111 * @brief Returns the content type of the message given by parameter
AzureIoTClient 10:38383e246675 112 * @c iotHubMessageHandle.
AzureIoTClient 10:38383e246675 113 *
AzureIoTClient 10:38383e246675 114 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 10:38383e246675 115 *
AzureIoTClient 10:38383e246675 116 * @return An @c IOTHUBMESSAGE_CONTENT_TYPE value.
AzureIoTClient 10:38383e246675 117 */
AzureIoTClient 0:e393db310d89 118 extern IOTHUBMESSAGE_CONTENT_TYPE IoTHubMessage_GetContentType(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 10:38383e246675 119
AzureIoTClient 10:38383e246675 120 /**
AzureIoTClient 10:38383e246675 121 * @brief Gets a handle to the message's properties map.
AzureIoTClient 10:38383e246675 122 *
AzureIoTClient 10:38383e246675 123 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 10:38383e246675 124 *
AzureIoTClient 10:38383e246675 125 * @return A @c MAP_HANDLE pointing to the properties map for this message.
AzureIoTClient 10:38383e246675 126 */
AzureIoTClient 0:e393db310d89 127 extern MAP_HANDLE IoTHubMessage_Properties(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 0:e393db310d89 128
AzureIoTClient 10:38383e246675 129 /**
AzureIoTClient 10:38383e246675 130 * @brief Frees all resources associated with the given message handle.
AzureIoTClient 10:38383e246675 131 *
AzureIoTClient 10:38383e246675 132 * @param iotHubMessageHandle Handle to the message.
AzureIoTClient 10:38383e246675 133 */
AzureIoTClient 0:e393db310d89 134 extern void IoTHubMessage_Destroy(IOTHUB_MESSAGE_HANDLE iotHubMessageHandle);
AzureIoTClient 0:e393db310d89 135
AzureIoTClient 0:e393db310d89 136 #ifdef __cplusplus
AzureIoTClient 0:e393db310d89 137 }
AzureIoTClient 0:e393db310d89 138 #endif
AzureIoTClient 0:e393db310d89 139
AzureIoTClient 0:e393db310d89 140 #endif /* IOTHUB_MESSAGE_H */