iothub_message.h

00001 // Copyright (c) Microsoft. All rights reserved.
00002 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
00003 
00004 /** @file   iothub_message.h
00005 *   @brief  The @c IoTHub_Message component encapsulates one message that
00006 *           can be transferred by an IoT hub client.
00007 */
00008 
00009 #ifndef IOTHUB_MESSAGE_H
00010 #define IOTHUB_MESSAGE_H
00011 
00012 #include "azure_c_shared_utility/macro_utils.h"
00013 #include "azure_c_shared_utility/map.h" 
00014 #include "azure_c_shared_utility/umock_c_prod.h"
00015 
00016 #ifdef __cplusplus
00017 #include <cstddef>
00018 extern "C" 
00019 {
00020 #else
00021 #include <stddef.h>
00022 #endif
00023 
00024 #define IOTHUB_MESSAGE_RESULT_VALUES         \
00025     IOTHUB_MESSAGE_OK,                       \
00026     IOTHUB_MESSAGE_INVALID_ARG,              \
00027     IOTHUB_MESSAGE_INVALID_TYPE,             \
00028     IOTHUB_MESSAGE_ERROR                     \
00029 
00030 /** @brief Enumeration specifying the status of calls to various  
00031  *  APIs in this module.
00032  */
00033 DEFINE_ENUM(IOTHUB_MESSAGE_RESULT, IOTHUB_MESSAGE_RESULT_VALUES);
00034 
00035 #define IOTHUBMESSAGE_CONTENT_TYPE_VALUES \
00036 IOTHUBMESSAGE_BYTEARRAY, \
00037 IOTHUBMESSAGE_STRING, \
00038 IOTHUBMESSAGE_UNKNOWN \
00039 
00040 /** @brief Enumeration specifying the content type of the a given  
00041   * message.
00042   */
00043 DEFINE_ENUM(IOTHUBMESSAGE_CONTENT_TYPE, IOTHUBMESSAGE_CONTENT_TYPE_VALUES);
00044 
00045 typedef struct IOTHUB_MESSAGE_HANDLE_DATA_TAG* IOTHUB_MESSAGE_HANDLE;
00046 
00047 /**
00048  * @brief   Creates a new IoT hub message from a byte array. The type of the
00049  *          message will be set to @c IOTHUBMESSAGE_BYTEARRAY.
00050  *
00051  * @param   byteArray   The byte array from which the message is to be created.
00052  * @param   size        The size of the byte array.
00053  *
00054  * @return  A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
00055  *          created or @c NULL in case an error occurs.
00056  */
00057 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_HANDLE, IoTHubMessage_CreateFromByteArray, const unsigned char*, byteArray, size_t, size);
00058 
00059 /**
00060  * @brief   Creates a new IoT hub message from a null terminated string.  The
00061  *          type of the message will be set to @c IOTHUBMESSAGE_STRING.
00062  *
00063  * @param   source  The null terminated string from which the message is to be
00064  *                  created.
00065  *
00066  * @return  A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
00067  *          created or @c NULL in case an error occurs.
00068  */
00069 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_HANDLE, IoTHubMessage_CreateFromString, const char*, source);
00070 
00071 /**
00072  * @brief   Creates a new IoT hub message with the content identical to that
00073  *          of the @p iotHubMessageHandle parameter.
00074  *
00075  * @param   iotHubMessageHandle Handle to the message that is to be cloned.
00076  *
00077  * @return  A valid @c IOTHUB_MESSAGE_HANDLE if the message was successfully
00078  *          cloned or @c NULL in case an error occurs.
00079  */
00080 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_HANDLE, IoTHubMessage_Clone, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00081 
00082 /**
00083  * @brief   Fetches a pointer and size for the data associated with the IoT
00084  *          hub message handle. If the content type of the message is not
00085  *          @c IOTHUBMESSAGE_BYTEARRAY then the function returns
00086  *          @c IOTHUB_MESSAGE_INVALID_ARG.
00087  *
00088  * @param   iotHubMessageHandle Handle to the message.
00089  * @param   buffer              Pointer to the memory location where the
00090  *                              pointer to the buffer will be written.
00091  * @param   size                The size of the buffer will be written to
00092  *                              this address.
00093  *
00094  * @return  Returns IOTHUB_MESSAGE_OK if the byte array was fetched successfully
00095  *          or an error code otherwise.
00096  */
00097 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_GetByteArray, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const unsigned char**, buffer, size_t*, size);
00098 
00099 /**
00100  * @brief   Returns the null terminated string stored in the message.
00101  *          If the content type of the message is not @c IOTHUBMESSAGE_STRING
00102  *          then the function returns @c NULL.
00103  *
00104  * @param   iotHubMessageHandle Handle to the message.
00105  *
00106  * @return  @c NULL if an error occurs or a pointer to the stored null
00107  *          terminated string otherwise.
00108  */
00109 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetString, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00110 
00111 /**
00112  * @brief   Returns the content type of the message given by parameter
00113  *          @c iotHubMessageHandle.
00114  *
00115  * @param   iotHubMessageHandle Handle to the message.
00116  *
00117  * @return  An @c IOTHUBMESSAGE_CONTENT_TYPE value.
00118  */
00119 MOCKABLE_FUNCTION(, IOTHUBMESSAGE_CONTENT_TYPE, IoTHubMessage_GetContentType, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00120 
00121 /**
00122  * @brief   Gets a handle to the message's properties map.
00123  *
00124  * @param   iotHubMessageHandle Handle to the message.
00125  *
00126  * @return  A @c MAP_HANDLE pointing to the properties map for this message.
00127  */
00128 MOCKABLE_FUNCTION(, MAP_HANDLE, IoTHubMessage_Properties, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00129 
00130 /**
00131 * @brief   Gets the MessageId from the IOTHUB_MESSAGE_HANDLE.
00132 *
00133 * @param   iotHubMessageHandle Handle to the message.
00134 *
00135 * @return  A const char* pointing to the Message Id.
00136 */
00137 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetMessageId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00138 
00139 /**
00140 * @brief   Sets the MessageId for the IOTHUB_MESSAGE_HANDLE.
00141 *
00142 * @param   iotHubMessageHandle Handle to the message.
00143 * @param   messageId Pointer to the memory location of the messageId
00144 *
00145 * @return  Returns IOTHUB_MESSAGE_OK if the messageId was set successfully
00146 *          or an error code otherwise.
00147 */
00148 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_SetMessageId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const char*, messageId);
00149 
00150 /**
00151 * @brief   Gets the CorrelationId from the IOTHUB_MESSAGE_HANDLE.
00152 *
00153 * @param   iotHubMessageHandle Handle to the message.
00154 *
00155 * @return  A const char* pointing to the Correlation Id.
00156 */
00157 MOCKABLE_FUNCTION(, const char*, IoTHubMessage_GetCorrelationId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00158 
00159 /**
00160 * @brief   Sets the CorrelationId for the IOTHUB_MESSAGE_HANDLE.
00161 *
00162 * @param   iotHubMessageHandle Handle to the message.
00163 * @param   correlationId Pointer to the memory location of the messageId
00164 *
00165 * @return  Returns IOTHUB_MESSAGE_OK if the messageId was set successfully
00166 *          or an error code otherwise.
00167 */
00168 MOCKABLE_FUNCTION(, IOTHUB_MESSAGE_RESULT, IoTHubMessage_SetCorrelationId, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle, const char*, correlationId);
00169 
00170 /**
00171  * @brief   Frees all resources associated with the given message handle.
00172  *
00173  * @param   iotHubMessageHandle Handle to the message.
00174  */
00175 MOCKABLE_FUNCTION(, void, IoTHubMessage_Destroy, IOTHUB_MESSAGE_HANDLE, iotHubMessageHandle);
00176 
00177 #ifdef __cplusplus
00178 }
00179 #endif
00180 
00181 #endif /* IOTHUB_MESSAGE_H */