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