Azure IoT / azure_c_shared_utility

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:   STM32F746_iothub_client_sample_mqtt f767zi_mqtt iothub_client_sample_amqp iothub_client_sample_http ... more

azure_c_shared_utility/httpapiex.h@2:20b88da3e604, 2016-05-09 (annotated)

Committer:
AzureIoTClient
Date:
Mon May 09 14:37:45 2016 -0700
Revision:
2:20b88da3e604
Parent:
0:fa2de1b79154
Child:
48:81866008bba4
1.0.6

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Azure.IoT Build 0:fa2de1b79154 1 // Copyright (c) Microsoft. All rights reserved.
Azure.IoT Build 0:fa2de1b79154 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
Azure.IoT Build 0:fa2de1b79154 3
Azure.IoT Build 0:fa2de1b79154 4 /** @file httpapiex.h
Azure.IoT Build 0:fa2de1b79154 5 * @brief This is a utility module that provides HTTP requests with
Azure.IoT Build 0:fa2de1b79154 6 * build-in retry capabilities.
Azure.IoT Build 0:fa2de1b79154 7 *
Azure.IoT Build 0:fa2de1b79154 8 * @details HTTAPIEX is a utility module that provides HTTP requests with build-in
Azure.IoT Build 0:fa2de1b79154 9 * retry capability to an HTTP server. Features over "regular" HTTPAPI include:
Azure.IoT Build 0:fa2de1b79154 10 * - Optional parameters
Azure.IoT Build 0:fa2de1b79154 11 * - Implementation independent
Azure.IoT Build 0:fa2de1b79154 12 * - Retry mechanism
Azure.IoT Build 0:fa2de1b79154 13 * - Persistent options
Azure.IoT Build 0:fa2de1b79154 14 */
Azure.IoT Build 0:fa2de1b79154 15
Azure.IoT Build 0:fa2de1b79154 16 #ifndef HTTPAPIEX_H
Azure.IoT Build 0:fa2de1b79154 17 #define HTTPAPIEX_H
Azure.IoT Build 0:fa2de1b79154 18
Azure.IoT Build 0:fa2de1b79154 19 #include "azure_c_shared_utility/macro_utils.h"
Azure.IoT Build 0:fa2de1b79154 20 #include "azure_c_shared_utility/httpapi.h"
AzureIoTClient 2:20b88da3e604 21 #include "azure_c_shared_utility/umock_c_prod.h"
Azure.IoT Build 0:fa2de1b79154 22
Azure.IoT Build 0:fa2de1b79154 23 #ifdef __cplusplus
Azure.IoT Build 0:fa2de1b79154 24 #include <cstddef>
Azure.IoT Build 0:fa2de1b79154 25 extern "C" {
Azure.IoT Build 0:fa2de1b79154 26 #else
Azure.IoT Build 0:fa2de1b79154 27 #include <stddef.h>
Azure.IoT Build 0:fa2de1b79154 28 #endif
Azure.IoT Build 0:fa2de1b79154 29
Azure.IoT Build 0:fa2de1b79154 30 typedef struct HTTPAPIEX_HANDLE_DATA_TAG* HTTPAPIEX_HANDLE;
Azure.IoT Build 0:fa2de1b79154 31
Azure.IoT Build 0:fa2de1b79154 32 #define HTTPAPIEX_RESULT_VALUES \
Azure.IoT Build 0:fa2de1b79154 33 HTTPAPIEX_OK, \
Azure.IoT Build 0:fa2de1b79154 34 HTTPAPIEX_ERROR, \
Azure.IoT Build 0:fa2de1b79154 35 HTTPAPIEX_INVALID_ARG, \
Azure.IoT Build 0:fa2de1b79154 36 HTTPAPIEX_RECOVERYFAILED
Azure.IoT Build 0:fa2de1b79154 37 /*to be continued*/
Azure.IoT Build 0:fa2de1b79154 38
Azure.IoT Build 0:fa2de1b79154 39 /** @brief Enumeration specifying the status of calls to various APIs in this module.
Azure.IoT Build 0:fa2de1b79154 40 */
Azure.IoT Build 0:fa2de1b79154 41 DEFINE_ENUM(HTTPAPIEX_RESULT, HTTPAPIEX_RESULT_VALUES);
Azure.IoT Build 0:fa2de1b79154 42
Azure.IoT Build 0:fa2de1b79154 43 /**
Azure.IoT Build 0:fa2de1b79154 44 * @brief Creates an @c HTTPAPIEX_HANDLE that can be used in further calls.
Azure.IoT Build 0:fa2de1b79154 45 *
Azure.IoT Build 0:fa2de1b79154 46 * @param hostName Pointer to a null-terminated string that contains the host name
Azure.IoT Build 0:fa2de1b79154 47 * of an HTTP server.
Azure.IoT Build 0:fa2de1b79154 48 *
Azure.IoT Build 0:fa2de1b79154 49 * If @p hostName is @c NULL then @c HTTPAPIEX_Create returns @c NULL. The @p
Azure.IoT Build 0:fa2de1b79154 50 * hostName value is saved and associated with the returned handle. If creating
Azure.IoT Build 0:fa2de1b79154 51 * the handle fails for any reason, then @c HTTAPIEX_Create returns @c NULL.
Azure.IoT Build 0:fa2de1b79154 52 * Otherwise, @c HTTPAPIEX_Create returns an @c HTTAPIEX_HANDLE suitable for
Azure.IoT Build 0:fa2de1b79154 53 * further calls to the module.
Azure.IoT Build 0:fa2de1b79154 54 *
Azure.IoT Build 0:fa2de1b79154 55 * @return An @c HTTAPIEX_HANDLE suitable for further calls to the module.
Azure.IoT Build 0:fa2de1b79154 56 */
AzureIoTClient 2:20b88da3e604 57 MOCKABLE_FUNCTION(, HTTPAPIEX_HANDLE, HTTPAPIEX_Create, const char*, hostName);
Azure.IoT Build 0:fa2de1b79154 58
Azure.IoT Build 0:fa2de1b79154 59 /**
Azure.IoT Build 0:fa2de1b79154 60 * @brief Tries to execute an HTTP request.
Azure.IoT Build 0:fa2de1b79154 61 *
Azure.IoT Build 0:fa2de1b79154 62 * @param handle A valid @c HTTPAPIEX_HANDLE value.
Azure.IoT Build 0:fa2de1b79154 63 * @param requestType A value from the ::HTTPAPI_REQUEST_TYPE enum.
Azure.IoT Build 0:fa2de1b79154 64 * @param relativePath Relative path to send the request to on the server.
Azure.IoT Build 0:fa2de1b79154 65 * @param requestHttpHeadersHandle Handle to the request HTTP headers.
Azure.IoT Build 0:fa2de1b79154 66 * @param requestContent The request content.
Azure.IoT Build 0:fa2de1b79154 67 * @param statusCode If non-null, the HTTP status code is written to this
Azure.IoT Build 0:fa2de1b79154 68 * pointer.
Azure.IoT Build 0:fa2de1b79154 69 * @param responseHttpHeadersHandle Handle to the response HTTP headers.
Azure.IoT Build 0:fa2de1b79154 70 * @param responseContent The response content.
Azure.IoT Build 0:fa2de1b79154 71 *
Azure.IoT Build 0:fa2de1b79154 72 * @c HTTPAPIEX_ExecuteRequest tries to execute an HTTP request of type @p
Azure.IoT Build 0:fa2de1b79154 73 * requestType, on the server's @p relativePath, pushing the request HTTP
Azure.IoT Build 0:fa2de1b79154 74 * headers @p requestHttpHeadersHandle, having the content of the request
Azure.IoT Build 0:fa2de1b79154 75 * as pointed to by @p requestContent. If successful, @c HTTAPIEX_ExecuteRequest
Azure.IoT Build 0:fa2de1b79154 76 * writes in the out @p parameter statusCode the HTTP status, populates the @p
Azure.IoT Build 0:fa2de1b79154 77 * responseHeadersHandle with the response headers and copies the response body
Azure.IoT Build 0:fa2de1b79154 78 * to @p responseContent.
Azure.IoT Build 0:fa2de1b79154 79 *
Azure.IoT Build 0:fa2de1b79154 80 * @return An @c HTTAPIEX_HANDLE suitable for further calls to the module.
Azure.IoT Build 0:fa2de1b79154 81 */
AzureIoTClient 2:20b88da3e604 82 MOCKABLE_FUNCTION(, HTTPAPIEX_RESULT, HTTPAPIEX_ExecuteRequest, HTTPAPIEX_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath, HTTP_HEADERS_HANDLE, requestHttpHeadersHandle, BUFFER_HANDLE, requestContent, unsigned int*, statusCode, HTTP_HEADERS_HANDLE, responseHttpHeadersHandle, BUFFER_HANDLE, responseContent);
Azure.IoT Build 0:fa2de1b79154 83
Azure.IoT Build 0:fa2de1b79154 84 /**
Azure.IoT Build 0:fa2de1b79154 85 * @brief Frees all resources used by the @c HTTPAPIEX_HANDLE object.
Azure.IoT Build 0:fa2de1b79154 86 *
Azure.IoT Build 0:fa2de1b79154 87 * @param handle The @c HTTPAPIEX_HANDLE object to be freed.
Azure.IoT Build 0:fa2de1b79154 88 */
AzureIoTClient 2:20b88da3e604 89 MOCKABLE_FUNCTION(, void, HTTPAPIEX_Destroy, HTTPAPIEX_HANDLE, handle);
Azure.IoT Build 0:fa2de1b79154 90
Azure.IoT Build 0:fa2de1b79154 91 /**
Azure.IoT Build 0:fa2de1b79154 92 * @brief Sets the option @p optionName to the value pointed to by @p value.
Azure.IoT Build 0:fa2de1b79154 93 *
Azure.IoT Build 0:fa2de1b79154 94 * @param handle The @c HTTPAPIEX_HANDLE representing this session.
Azure.IoT Build 0:fa2de1b79154 95 * @param optionName Name of the option.
Azure.IoT Build 0:fa2de1b79154 96 * @param value The value to be set for the option.
Azure.IoT Build 0:fa2de1b79154 97 *
Azure.IoT Build 0:fa2de1b79154 98 * @return An @c HTTPAPIEX_RESULT indicating the status of the call.
Azure.IoT Build 0:fa2de1b79154 99 */
AzureIoTClient 2:20b88da3e604 100 MOCKABLE_FUNCTION(, HTTPAPIEX_RESULT, HTTPAPIEX_SetOption, HTTPAPIEX_HANDLE, handle, const char*, optionName, const void*, value);
Azure.IoT Build 0:fa2de1b79154 101
Azure.IoT Build 0:fa2de1b79154 102 #ifdef __cplusplus
Azure.IoT Build 0:fa2de1b79154 103 }
Azure.IoT Build 0:fa2de1b79154 104 #endif
Azure.IoT Build 0:fa2de1b79154 105
Azure.IoT Build 0:fa2de1b79154 106 #endif /* HTTPAPIEX_H */