Azure IoT / iothub_amqp_transport

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   sht15_remote_monitoring RobotArmDemo iothub_client_sample_amqp iothub_client_sample_amqp ... more

message_queue.h@39:e98d5df6dc74, 2017-08-11 (annotated)

Committer:
AzureIoTClient
Date:
Fri Aug 11 14:01:56 2017 -0700
Revision:
39:e98d5df6dc74
1.1.21

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AzureIoTClient 39:e98d5df6dc74 1 // Copyright (c) Microsoft. All rights reserved.
AzureIoTClient 39:e98d5df6dc74 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
AzureIoTClient 39:e98d5df6dc74 3
AzureIoTClient 39:e98d5df6dc74 4 /** @file message_queue.h
AzureIoTClient 39:e98d5df6dc74 5 * @brief A generic message queue.
AzureIoTClient 39:e98d5df6dc74 6 */
AzureIoTClient 39:e98d5df6dc74 7
AzureIoTClient 39:e98d5df6dc74 8 #ifndef MESSAGE_QUEUE_H
AzureIoTClient 39:e98d5df6dc74 9 #define MESSAGE_QUEUE_H
AzureIoTClient 39:e98d5df6dc74 10
AzureIoTClient 39:e98d5df6dc74 11 #include "azure_c_shared_utility/macro_utils.h"
AzureIoTClient 39:e98d5df6dc74 12 #include "azure_c_shared_utility/umock_c_prod.h"
AzureIoTClient 39:e98d5df6dc74 13 #include "azure_c_shared_utility/optionhandler.h"
AzureIoTClient 39:e98d5df6dc74 14
AzureIoTClient 39:e98d5df6dc74 15 #ifdef __cplusplus
AzureIoTClient 39:e98d5df6dc74 16 extern "C"
AzureIoTClient 39:e98d5df6dc74 17 {
AzureIoTClient 39:e98d5df6dc74 18 #endif
AzureIoTClient 39:e98d5df6dc74 19
AzureIoTClient 39:e98d5df6dc74 20 typedef struct MESSAGE_QUEUE_TAG* MESSAGE_QUEUE_HANDLE;
AzureIoTClient 39:e98d5df6dc74 21 typedef void* MQ_MESSAGE_HANDLE;
AzureIoTClient 39:e98d5df6dc74 22 typedef void* USER_DEFINED_REASON;
AzureIoTClient 39:e98d5df6dc74 23
AzureIoTClient 39:e98d5df6dc74 24 #define MESSAGE_QUEUE_RESULT_STRINGS \
AzureIoTClient 39:e98d5df6dc74 25 MESSAGE_QUEUE_SUCCESS, \
AzureIoTClient 39:e98d5df6dc74 26 MESSAGE_QUEUE_ERROR, \
AzureIoTClient 39:e98d5df6dc74 27 MESSAGE_QUEUE_RETRYABLE_ERROR, \
AzureIoTClient 39:e98d5df6dc74 28 MESSAGE_QUEUE_TIMEOUT, \
AzureIoTClient 39:e98d5df6dc74 29 MESSAGE_QUEUE_CANCELLED
AzureIoTClient 39:e98d5df6dc74 30
AzureIoTClient 39:e98d5df6dc74 31 DEFINE_ENUM(MESSAGE_QUEUE_RESULT, MESSAGE_QUEUE_RESULT_STRINGS);
AzureIoTClient 39:e98d5df6dc74 32
AzureIoTClient 39:e98d5df6dc74 33 /**
AzureIoTClient 39:e98d5df6dc74 34 * @brief User-provided callback invoked by MESSAGE_QUEUE back to the user when a messages completes being processed.
AzureIoTClient 39:e98d5df6dc74 35 */
AzureIoTClient 39:e98d5df6dc74 36 typedef void(*MESSAGE_PROCESSING_COMPLETED_CALLBACK)(MQ_MESSAGE_HANDLE message, MESSAGE_QUEUE_RESULT result, USER_DEFINED_REASON reason, void* user_context);
AzureIoTClient 39:e98d5df6dc74 37
AzureIoTClient 39:e98d5df6dc74 38 /**
AzureIoTClient 39:e98d5df6dc74 39 * @brief Callback that MUST be invoked by PROCESS_MESSAGE_CALLBACK (user provided) to signal to MESSAGE_QUEUE that a message has been processed.
AzureIoTClient 39:e98d5df6dc74 40 * @remarks Besides causing MESSAGE_QUEUE to dequeue the message from its internal lists, causes MESSAGE_PROCESSING_COMPLETED_CALLBACK to be triggered.
AzureIoTClient 39:e98d5df6dc74 41 */
AzureIoTClient 39:e98d5df6dc74 42 typedef void(*PROCESS_MESSAGE_COMPLETED_CALLBACK)(MESSAGE_QUEUE_HANDLE message_queue, MQ_MESSAGE_HANDLE message, MESSAGE_QUEUE_RESULT result, USER_DEFINED_REASON reason);
AzureIoTClient 39:e98d5df6dc74 43
AzureIoTClient 39:e98d5df6dc74 44 /**
AzureIoTClient 39:e98d5df6dc74 45 * @brief User-provided callback invoked by MESSAGE_QUEUE when a messages is ready to be processed, getting internally moved from "pending" to "in-progress".
AzureIoTClient 39:e98d5df6dc74 46 */
AzureIoTClient 39:e98d5df6dc74 47 typedef void(*PROCESS_MESSAGE_CALLBACK)(MESSAGE_QUEUE_HANDLE message_queue, MQ_MESSAGE_HANDLE message, PROCESS_MESSAGE_COMPLETED_CALLBACK on_process_message_completed_callback, void* user_context);
AzureIoTClient 39:e98d5df6dc74 48
AzureIoTClient 39:e98d5df6dc74 49 typedef struct MESSAGE_QUEUE_CONFIG_TAG
AzureIoTClient 39:e98d5df6dc74 50 {
AzureIoTClient 39:e98d5df6dc74 51 /**
AzureIoTClient 39:e98d5df6dc74 52 * @brief Function that actually process (a.k.a, e.g, sends) a message previously queued.
AzureIoTClient 39:e98d5df6dc74 53 *
AzureIoTClient 39:e98d5df6dc74 54 * @remarks When MESSAGE_QUEUE is summoned to invoke @c on_process_message_callback (upon call to message_queue_do_work, when a message is moved from the pending to in-progress list),
AzureIoTClient 39:e98d5df6dc74 55 * it passes as arguments the MESSAGE_QUEUE handle and a callback function that MUST be invoked by @c on_process_message_callback once it completes.
AzureIoTClient 39:e98d5df6dc74 56 * The @c user_context passed is the same provided as argument by the upper layer on @c message_queue_add.
AzureIoTClient 39:e98d5df6dc74 57 */
AzureIoTClient 39:e98d5df6dc74 58 PROCESS_MESSAGE_CALLBACK on_process_message_callback;
AzureIoTClient 39:e98d5df6dc74 59 size_t max_message_enqueued_time_secs;
AzureIoTClient 39:e98d5df6dc74 60 size_t max_message_processing_time_secs;
AzureIoTClient 39:e98d5df6dc74 61 size_t max_retry_count;
AzureIoTClient 39:e98d5df6dc74 62 } MESSAGE_QUEUE_CONFIG;
AzureIoTClient 39:e98d5df6dc74 63
AzureIoTClient 39:e98d5df6dc74 64 /**
AzureIoTClient 39:e98d5df6dc74 65 * @brief Creates a new instance of MESSAGE_QUEUE.
AzureIoTClient 39:e98d5df6dc74 66 *
AzureIoTClient 39:e98d5df6dc74 67 * @param config Pointer to an @c MESSAGE_QUEUE_CONFIG structure
AzureIoTClient 39:e98d5df6dc74 68 *
AzureIoTClient 39:e98d5df6dc74 69 * @returns A non-NULL @c MESSAGE_QUEUE_HANDLE value that is used when invoking other API functions.
AzureIoTClient 39:e98d5df6dc74 70 */
AzureIoTClient 39:e98d5df6dc74 71 MOCKABLE_FUNCTION(, MESSAGE_QUEUE_HANDLE, message_queue_create, MESSAGE_QUEUE_CONFIG*, config);
AzureIoTClient 39:e98d5df6dc74 72
AzureIoTClient 39:e98d5df6dc74 73 /**
AzureIoTClient 39:e98d5df6dc74 74 * @brief Destroys an instance of MESSAGE_QUEUE, releasing all memory it allocated.
AzureIoTClient 39:e98d5df6dc74 75 *
AzureIoTClient 39:e98d5df6dc74 76 * @remarks All messages still pending to be processed and currently in-progress get bubbled up back to the upper-layer
AzureIoTClient 39:e98d5df6dc74 77 * through the @c on_message_processing_completed_callback (passed on the @c MESSAGE_QUEUE_CONFIG instance)
AzureIoTClient 39:e98d5df6dc74 78 * with the @c result set as @c MESSAGE_QUEUE_CANCELLED and @c reason set to @c NULL.
AzureIoTClient 39:e98d5df6dc74 79 *
AzureIoTClient 39:e98d5df6dc74 80 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 81 */
AzureIoTClient 39:e98d5df6dc74 82 MOCKABLE_FUNCTION(, void, message_queue_destroy, MESSAGE_QUEUE_HANDLE, message_queue);
AzureIoTClient 39:e98d5df6dc74 83
AzureIoTClient 39:e98d5df6dc74 84 /**
AzureIoTClient 39:e98d5df6dc74 85 * @brief Adds a new generic message to MESSAGE_QUEUE's pending list.
AzureIoTClient 39:e98d5df6dc74 86 *
AzureIoTClient 39:e98d5df6dc74 87 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 88 *
AzureIoTClient 39:e98d5df6dc74 89 * @param message A generic message to be queued and then processed (i.e., sent, consolidated, etc).
AzureIoTClient 39:e98d5df6dc74 90 *
AzureIoTClient 39:e98d5df6dc74 91 * @returns Zero if the no errors occur, non-zero otherwise.
AzureIoTClient 39:e98d5df6dc74 92 */
AzureIoTClient 39:e98d5df6dc74 93 MOCKABLE_FUNCTION(, int, message_queue_add, MESSAGE_QUEUE_HANDLE, message_queue, MQ_MESSAGE_HANDLE, message, MESSAGE_PROCESSING_COMPLETED_CALLBACK, on_message_processing_completed_callback, void*, user_context);
AzureIoTClient 39:e98d5df6dc74 94
AzureIoTClient 39:e98d5df6dc74 95 /**
AzureIoTClient 39:e98d5df6dc74 96 * @brief Causes all messages in-progress to be moved back to the beginning of the pending list.
AzureIoTClient 39:e98d5df6dc74 97 *
AzureIoTClient 39:e98d5df6dc74 98 * @remarks If on_message_process_completed_callback is invoked for any of message not in in-progress, it is disregarded.
AzureIoTClient 39:e98d5df6dc74 99 * Messages are queued back into the pending list in a way they will be sent first when message_queue_do_work is invoked again.
AzureIoTClient 39:e98d5df6dc74 100 *
AzureIoTClient 39:e98d5df6dc74 101 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 102 *
AzureIoTClient 39:e98d5df6dc74 103 * @returns Zero if the no errors occur, non-zero otherwise.
AzureIoTClient 39:e98d5df6dc74 104 */
AzureIoTClient 39:e98d5df6dc74 105 MOCKABLE_FUNCTION(, int, message_queue_move_all_back_to_pending, MESSAGE_QUEUE_HANDLE, message_queue);
AzureIoTClient 39:e98d5df6dc74 106
AzureIoTClient 39:e98d5df6dc74 107 /**
AzureIoTClient 39:e98d5df6dc74 108 * @brief Causes all messages pending to be sent and in-progress to be flushed back to the user through @c on_message_processing_completed_callback.
AzureIoTClient 39:e98d5df6dc74 109 *
AzureIoTClient 39:e98d5df6dc74 110 * @remarks @c on_message_processing_completed_callback gets invoked with @c result set as MESSAGE_QUEUE_CANCELLED and @c reason set to NULL.
AzureIoTClient 39:e98d5df6dc74 111 *
AzureIoTClient 39:e98d5df6dc74 112 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 113 */
AzureIoTClient 39:e98d5df6dc74 114 MOCKABLE_FUNCTION(, void, message_queue_remove_all, MESSAGE_QUEUE_HANDLE, message_queue);
AzureIoTClient 39:e98d5df6dc74 115
AzureIoTClient 39:e98d5df6dc74 116 /**
AzureIoTClient 39:e98d5df6dc74 117 * @brief Informs if there are messages pending to be sent and/or currently in-progress.
AzureIoTClient 39:e98d5df6dc74 118 *
AzureIoTClient 39:e98d5df6dc74 119 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 120 *
AzureIoTClient 39:e98d5df6dc74 121 * @param @c is_empty Set to @c true if there are any messages in pending to be sent and/or currently in-progress, @c false otherwise.
AzureIoTClient 39:e98d5df6dc74 122 *
AzureIoTClient 39:e98d5df6dc74 123 * @remarks The parameter @c is_empty is only set if no errors occur (like passing a NULL @c message_queue).
AzureIoTClient 39:e98d5df6dc74 124 *
AzureIoTClient 39:e98d5df6dc74 125 * @returns Zero if the no errors occur, non-zero otherwise.
AzureIoTClient 39:e98d5df6dc74 126 */
AzureIoTClient 39:e98d5df6dc74 127 MOCKABLE_FUNCTION(, int, message_queue_is_empty, MESSAGE_QUEUE_HANDLE, message_queue, bool*, is_empty);
AzureIoTClient 39:e98d5df6dc74 128
AzureIoTClient 39:e98d5df6dc74 129 /**
AzureIoTClient 39:e98d5df6dc74 130 * @brief Causes MESSAGE_QUEUE to go through its list of pending messages and move them to in-progress, as well as trigering retry and timeout controls.
AzureIoTClient 39:e98d5df6dc74 131 *
AzureIoTClient 39:e98d5df6dc74 132 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 133 */
AzureIoTClient 39:e98d5df6dc74 134 MOCKABLE_FUNCTION(, void, message_queue_do_work, MESSAGE_QUEUE_HANDLE, message_queue);
AzureIoTClient 39:e98d5df6dc74 135
AzureIoTClient 39:e98d5df6dc74 136 /**
AzureIoTClient 39:e98d5df6dc74 137 * @brief Sets the maximum time, in seconds, a message will be within MESSAGE_QUEUE (in either pending or in-progress lists).
AzureIoTClient 39:e98d5df6dc74 138 *
AzureIoTClient 39:e98d5df6dc74 139 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 140 *
AzureIoTClient 39:e98d5df6dc74 141 * @param seconds Number of seconds to set for this timeout. A value of zero de-activates this timeout control.
AzureIoTClient 39:e98d5df6dc74 142 *
AzureIoTClient 39:e98d5df6dc74 143 * @returns Zero if the no errors occur, non-zero otherwise.
AzureIoTClient 39:e98d5df6dc74 144 */
AzureIoTClient 39:e98d5df6dc74 145 MOCKABLE_FUNCTION(, int, message_queue_set_max_message_enqueued_time_secs, MESSAGE_QUEUE_HANDLE, message_queue, size_t, seconds);
AzureIoTClient 39:e98d5df6dc74 146
AzureIoTClient 39:e98d5df6dc74 147 /**
AzureIoTClient 39:e98d5df6dc74 148 * @brief Sets the maximum time, in seconds, a message will be in-progress within MESSAGE_QUEUE.
AzureIoTClient 39:e98d5df6dc74 149 *
AzureIoTClient 39:e98d5df6dc74 150 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 151 *
AzureIoTClient 39:e98d5df6dc74 152 * @param seconds Number of seconds to set for this timeout. A value of zero de-activates this timeout control.
AzureIoTClient 39:e98d5df6dc74 153 *
AzureIoTClient 39:e98d5df6dc74 154 * @returns Zero if the no errors occur, non-zero otherwise.
AzureIoTClient 39:e98d5df6dc74 155 */
AzureIoTClient 39:e98d5df6dc74 156 MOCKABLE_FUNCTION(, int, message_queue_set_max_message_processing_time_secs, MESSAGE_QUEUE_HANDLE, message_queue, size_t, seconds);
AzureIoTClient 39:e98d5df6dc74 157
AzureIoTClient 39:e98d5df6dc74 158 /**
AzureIoTClient 39:e98d5df6dc74 159 * @brief Sets the maximum number of times MESSAGE_QUEUE will try to re-process a message (no counting the initial attempt).
AzureIoTClient 39:e98d5df6dc74 160 *
AzureIoTClient 39:e98d5df6dc74 161 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 162 *
AzureIoTClient 39:e98d5df6dc74 163 * @param max_retry_count The number of times MESSAGE_QUEUE will try to re-process a message.
AzureIoTClient 39:e98d5df6dc74 164 *
AzureIoTClient 39:e98d5df6dc74 165 * @returns Zero if the no errors occur, non-zero otherwise.
AzureIoTClient 39:e98d5df6dc74 166 */
AzureIoTClient 39:e98d5df6dc74 167 MOCKABLE_FUNCTION(, int, message_queue_set_max_retry_count, MESSAGE_QUEUE_HANDLE, message_queue, size_t, max_retry_count);
AzureIoTClient 39:e98d5df6dc74 168
AzureIoTClient 39:e98d5df6dc74 169 /**
AzureIoTClient 39:e98d5df6dc74 170 * @brief Retrieves a blob with all the options currently set in the instance of MESSAGE_QUEUE.
AzureIoTClient 39:e98d5df6dc74 171 *
AzureIoTClient 39:e98d5df6dc74 172 * @param message_queue A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
AzureIoTClient 39:e98d5df6dc74 173 *
AzureIoTClient 39:e98d5df6dc74 174 * @returns A non-NULL @c OPTIONHANDLER_HANDLE if no errors occur, or NULL otherwise.
AzureIoTClient 39:e98d5df6dc74 175 */
AzureIoTClient 39:e98d5df6dc74 176 MOCKABLE_FUNCTION(, OPTIONHANDLER_HANDLE, message_queue_retrieve_options, MESSAGE_QUEUE_HANDLE, message_queue);
AzureIoTClient 39:e98d5df6dc74 177
AzureIoTClient 39:e98d5df6dc74 178 #ifdef __cplusplus
AzureIoTClient 39:e98d5df6dc74 179 }
AzureIoTClient 39:e98d5df6dc74 180 #endif
AzureIoTClient 39:e98d5df6dc74 181
AzureIoTClient 39:e98d5df6dc74 182 #endif /*MESSAGE_QUEUE_H*/