Xin Zhang / azure-iot-c-sdk-f767zi

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:   samplemqtt

c-utility/inc/azure_c_shared_utility/httpapiex.h@0:f7f1f0d76dd6, 2018-08-23 (annotated)

Committer:
XinZhangMS
Date:
Thu Aug 23 06:52:14 2018 +0000
Revision:
0:f7f1f0d76dd6
azure-c-sdk for mbed os supporting NUCLEO_F767ZI

Who changed what in which revision?

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