| 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 httpapi.h |
| 5 |
* @deprecated Applications should not directly use this header file. They should use httpapiex.h instead. |
| 6 |
* |
| 7 |
* @brief Deprecated module implements the standard HTTP API used by the C IoT client |
| 8 |
* library. |
| 9 |
* |
| 10 |
* @details For example, on the Windows platform the HTTP API code uses |
| 11 |
* WinHTTP and for Linux it uses curl and so forth. HTTPAPI must support |
| 12 |
* HTTPs (HTTP+SSL). |
| 13 |
* |
| 14 |
* @remarks This header file is deprecated in the sense that applications should not directly invoke it. |
| 15 |
* It remains the contract that instantiations of the HTTP clients on various platforms |
| 16 |
* (e.g. curl and WinHTTP) are implemented to. |
| 17 |
* |
| 18 |
* Applications should not directly invoke functions in this header because this layer does |
| 19 |
* not follow the standard allocation/copying rules of the rest of the SDK. When passed |
| 20 |
* a memory buffer, this layer points directly to the memory and does not make a copy or use reference counting. |
| 21 |
* This means there can be a crash if the caller free()'s the data but this layer needs it. |
| 22 |
* The httpapiex.h layer follows the conventions throughout the rest of the SDK and is |
| 23 |
* therefore safer and less likely to cause unexpected problems for callers. |
| 24 |
*/ |
| 25 |
|
| 26 |
#ifndef HTTPAPI_H |
| 27 |
#define HTTPAPI_H |
| 28 |
|
| 29 |
#ifdef __cplusplus |
| 30 |
#include <cstddef> |
| 31 |
#else |
| 32 |
#include <stddef.h> |
| 33 |
#endif |
| 34 |
|
| 35 |
#include "azure_macro_utils/macro_utils.h" |
| 36 |
#include "azure_c_shared_utility/httpheaders.h" |
| 37 |
#include "azure_c_shared_utility/buffer_.h" |
| 38 |
#include "umock_c/umock_c_prod.h" |
| 39 |
|
| 40 |
#ifdef __cplusplus |
| 41 |
extern "C" { |
| 42 |
#endif |
| 43 |
|
| 44 |
typedef struct HTTP_HANDLE_DATA_TAG* HTTP_HANDLE; |
| 45 |
|
| 46 |
#define AMBIGUOUS_STATUS_CODE (300) |
| 47 |
|
| 48 |
#define HTTPAPI_RESULT_VALUES \ |
| 49 |
HTTPAPI_OK, \ |
| 50 |
HTTPAPI_INVALID_ARG, \ |
| 51 |
HTTPAPI_ERROR, \ |
| 52 |
HTTPAPI_OPEN_REQUEST_FAILED, \ |
| 53 |
HTTPAPI_SET_OPTION_FAILED, \ |
| 54 |
HTTPAPI_SEND_REQUEST_FAILED, \ |
| 55 |
HTTPAPI_RECEIVE_RESPONSE_FAILED, \ |
| 56 |
HTTPAPI_QUERY_HEADERS_FAILED, \ |
| 57 |
HTTPAPI_QUERY_DATA_AVAILABLE_FAILED, \ |
| 58 |
HTTPAPI_READ_DATA_FAILED, \ |
| 59 |
HTTPAPI_ALREADY_INIT, \ |
| 60 |
HTTPAPI_NOT_INIT, \ |
| 61 |
HTTPAPI_HTTP_HEADERS_FAILED, \ |
| 62 |
HTTPAPI_STRING_PROCESSING_ERROR, \ |
| 63 |
HTTPAPI_ALLOC_FAILED, \ |
| 64 |
HTTPAPI_INIT_FAILED, \ |
| 65 |
HTTPAPI_INSUFFICIENT_RESPONSE_BUFFER, \ |
| 66 |
HTTPAPI_SET_X509_FAILURE, \ |
| 67 |
HTTPAPI_SET_TIMEOUTS_FAILED \ |
| 68 |
|
| 69 |
/** @brief Enumeration specifying the possible return values for the APIs in |
| 70 |
* this module. |
| 71 |
*/ |
| 72 |
MU_DEFINE_ENUM(HTTPAPI_RESULT, HTTPAPI_RESULT_VALUES); |
| 73 |
|
| 74 |
#define HTTPAPI_REQUEST_TYPE_VALUES\ |
| 75 |
HTTPAPI_REQUEST_GET, \ |
| 76 |
HTTPAPI_REQUEST_POST, \ |
| 77 |
HTTPAPI_REQUEST_PUT, \ |
| 78 |
HTTPAPI_REQUEST_DELETE, \ |
| 79 |
HTTPAPI_REQUEST_PATCH, \ |
| 80 |
HTTPAPI_REQUEST_HEAD \ |
| 81 |
|
| 82 |
|
| 83 |
/** @brief Enumeration specifying the HTTP request verbs accepted by |
| 84 |
* the HTTPAPI module. |
| 85 |
*/ |
| 86 |
MU_DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES); |
| 87 |
|
| 88 |
#define MAX_HOSTNAME_LEN 65 |
| 89 |
#define MAX_USERNAME_LEN 65 |
| 90 |
#define MAX_PASSWORD_LEN 65 |
| 91 |
|
| 92 |
/** |
| 93 |
* @deprecated Applications should not directly invoke this function. They should use httpapiex.h instead. |
| 94 |
* |
| 95 |
* @brief Global initialization for the HTTP API component. |
| 96 |
* |
| 97 |
* Platform specific implementations are expected to initialize |
| 98 |
* the underlying HTTP API stacks. |
| 99 |
* |
| 100 |
* @return @c HTTPAPI_OK if initialization is successful or an error |
| 101 |
* code in case it fails. |
| 102 |
*/ |
| 103 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_Init); |
| 104 |
|
| 105 |
/** @brief Free resources allocated in ::HTTPAPI_Init. |
| 106 |
* |
| 107 |
* @deprecated Applications should not directly invoke this function. They should use httpapiex.h instead. |
| 108 |
* |
| 109 |
*/ |
| 110 |
MOCKABLE_FUNCTION(, void, HTTPAPI_Deinit); |
| 111 |
|
| 112 |
/** |
| 113 |
* @deprecated Applications should not directly invoke this function. They should use httpapiex.h instead. |
| 114 |
* |
| 115 |
* @brief Creates an HTTPS connection to the host specified by the @p |
| 116 |
* hostName parameter. |
| 117 |
* |
| 118 |
* @param hostName Name of the host. |
| 119 |
* |
| 120 |
* This function returns a handle to the newly created connection. |
| 121 |
* You can use the handle in subsequent calls to execute specific |
| 122 |
* HTTP calls using ::HTTPAPI_ExecuteRequest. |
| 123 |
* |
| 124 |
* @return A @c HTTP_HANDLE to the newly created connection or @c NULL in |
| 125 |
* case an error occurs. |
| 126 |
*/ |
| 127 |
MOCKABLE_FUNCTION(, HTTP_HANDLE, HTTPAPI_CreateConnection, const char*, hostName); |
| 128 |
|
| 129 |
/** |
| 130 |
* |
| 131 |
* @deprecated Applications should not directly invoke this function. They should use httpapiex.h instead. |
| 132 |
* |
| 133 |
* @brief Closes a connection created with ::HTTPAPI_CreateConnection. |
| 134 |
* |
| 135 |
* @param handle The handle to the HTTP connection created via ::HTTPAPI_CreateConnection. |
| 136 |
* |
| 137 |
* All resources allocated by ::HTTPAPI_CreateConnection should be |
| 138 |
* freed in ::HTTPAPI_CloseConnection. |
| 139 |
*/ |
| 140 |
MOCKABLE_FUNCTION(, void, HTTPAPI_CloseConnection, HTTP_HANDLE, handle); |
| 141 |
|
| 142 |
/** |
| 143 |
* @brief Sends the HTTP request to the host and handles the response for |
| 144 |
* the HTTP call. |
| 145 |
* |
| 146 |
* @param handle The handle to the HTTP connection created |
| 147 |
* via ::HTTPAPI_CreateConnection. |
| 148 |
* @param requestType Specifies which HTTP method is used (GET, |
| 149 |
* POST, DELETE, PUT, PATCH). |
| 150 |
* @param relativePath Specifies the relative path of the URL |
| 151 |
* excluding the host name. |
| 152 |
* @param httpHeadersHandle Specifies a set of HTTP headers (name-value |
| 153 |
* pairs) to be added to the |
| 154 |
* HTTP request. The @p httpHeadersHandle |
| 155 |
* handle can be created and setup with |
| 156 |
* the proper name-value pairs by using the |
| 157 |
* HTTPHeaders APIs available in @c |
| 158 |
* HTTPHeaders.h. |
| 159 |
* @param content Specifies a pointer to the request body. |
| 160 |
* This value is optional and can be @c NULL. |
| 161 |
* @param contentLength Specifies the request body size (this is |
| 162 |
* typically added into the HTTP headers as |
| 163 |
* the Content-Length header). This value is |
| 164 |
* optional and can be 0. |
| 165 |
* @param statusCode This is an out parameter, where |
| 166 |
* ::HTTPAPI_ExecuteRequest returns the status |
| 167 |
* code from the HTTP response (200, 201, 400, |
| 168 |
* 401, etc.) |
| 169 |
* @param responseHeadersHandle This is an HTTP headers handle to which |
| 170 |
* ::HTTPAPI_ExecuteRequest must add all the |
| 171 |
* HTTP response headers so that the caller of |
| 172 |
* ::HTTPAPI_ExecuteRequest can inspect them. |
| 173 |
* You can manipulate @p responseHeadersHandle |
| 174 |
* by using the HTTPHeaders APIs available in |
| 175 |
* @c HTTPHeaders.h |
| 176 |
* @param responseContent This is a buffer that must be filled by |
| 177 |
* ::HTTPAPI_ExecuteRequest with the contents |
| 178 |
* of the HTTP response body. The buffer size |
| 179 |
* must be increased by the |
| 180 |
* ::HTTPAPI_ExecuteRequest implementation in |
| 181 |
* order to fit the response body. |
| 182 |
* ::HTTPAPI_ExecuteRequest must also handle |
| 183 |
* chunked transfer encoding for HTTP responses. |
| 184 |
* To manipulate the @p responseContent buffer, |
| 185 |
* use the APIs available in @c Strings.h. |
| 186 |
* |
| 187 |
* @return @c HTTPAPI_OK if the API call is successful or an error |
| 188 |
* code in case it fails. |
| 189 |
*/ |
| 190 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_ExecuteRequest, HTTP_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath, |
| 191 |
HTTP_HEADERS_HANDLE, httpHeadersHandle, const unsigned char*, content, |
| 192 |
size_t, contentLength, unsigned int*, statusCode, |
| 193 |
HTTP_HEADERS_HANDLE, responseHeadersHandle, BUFFER_HANDLE, responseContent); |
| 194 |
|
| 195 |
/** |
| 196 |
* @deprecated Applications should not directly invoke this function. They should use httpapiex.h instead. |
| 197 |
* |
| 198 |
* @brief Sets the option named @p optionName bearing the value |
| 199 |
* @p value for the HTTP_HANDLE @p handle. |
| 200 |
* |
| 201 |
* @param handle The handle to the HTTP connection created via |
| 202 |
* ::HTTPAPI_CreateConnection. |
| 203 |
* @param optionName A @c NULL terminated string representing the name |
| 204 |
* of the option. |
| 205 |
* @param value A pointer to the value for the option. |
| 206 |
* |
| 207 |
* @return @c HTTPAPI_OK if initialization is successful or an error |
| 208 |
* code in case it fails. |
| 209 |
*/ |
| 210 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, const char*, optionName, const void*, value); |
| 211 |
|
| 212 |
/** |
| 213 |
* @deprecated Applications should not directly invoke this function. They should use httpapiex.h instead. |
| 214 |
* |
| 215 |
* @brief Clones the option named @p optionName bearing the value @p value |
| 216 |
* into the pointer @p savedValue. |
| 217 |
* |
| 218 |
* @param optionName A @c NULL terminated string representing the name of |
| 219 |
* the option |
| 220 |
* @param value A pointer to the value of the option. |
| 221 |
* @param savedValue This pointer receives the copy of the value of the |
| 222 |
* option. The copy needs to be free-able. |
| 223 |
* |
| 224 |
* @return @c HTTPAPI_OK if initialization is successful or an error |
| 225 |
* code in case it fails. |
| 226 |
*/ |
| 227 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue); |
| 228 |
|
| 229 |
#ifdef __cplusplus |
| 230 |
} |
| 231 |
#endif |
| 232 |
|
| 233 |
#endif /* HTTPAPI_H */ |