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 */
|
---|