[453] | 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 */
|
---|