| 1 |
httpapi_compact |
| 2 |
=============== |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
httpapi_compact implements a compact version of the HTTP (Hypertext Transfer Protocol). |
| 7 |
|
| 8 |
## References |
| 9 |
|
| 10 |
[http://](http://httpwg.org/) |
| 11 |
|
| 12 |
## Exposed API |
| 13 |
|
| 14 |
**SRS_HTTPAPI_COMPACT_21_001: [** The httpapi_compact shall implement the methods defined by the `httpapi.h`. |
| 15 |
```c |
| 16 |
/** |
| 17 |
* @brief Global initialization for the HTTP API component. |
| 18 |
* |
| 19 |
* Platform specific implementations are expected to initialize |
| 20 |
* the underlying HTTP API stacks. |
| 21 |
* |
| 22 |
* @return @c HTTPAPI_OK if initialization is successful or an error |
| 23 |
* code in case it fails. |
| 24 |
*/ |
| 25 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_Init); |
| 26 |
|
| 27 |
/** @brief Free resources allocated in ::HTTPAPI_Init. */ |
| 28 |
MOCKABLE_FUNCTION(, void, HTTPAPI_Deinit); |
| 29 |
|
| 30 |
/** |
| 31 |
* @brief Creates an HTTPS connection to the host specified by the @p |
| 32 |
* hostName parameter. |
| 33 |
* |
| 34 |
* @param hostName Name of the host. |
| 35 |
* |
| 36 |
* This function returns a handle to the newly created connection. |
| 37 |
* You can use the handle in subsequent calls to execute specific |
| 38 |
* HTTP calls using ::HTTPAPI_ExecuteRequest. |
| 39 |
* |
| 40 |
* @return A @c HTTP_HANDLE to the newly created connection or @c NULL in |
| 41 |
* case an error occurs. |
| 42 |
*/ |
| 43 |
MOCKABLE_FUNCTION(, HTTP_HANDLE, HTTPAPI_CreateConnection, const char*, hostName); |
| 44 |
|
| 45 |
/** |
| 46 |
* @brief Closes a connection created with ::HTTPAPI_CreateConnection. |
| 47 |
* |
| 48 |
* @param handle The handle to the HTTP connection created via ::HTTPAPI_CreateConnection. |
| 49 |
* |
| 50 |
* All resources allocated by ::HTTPAPI_CreateConnection should be |
| 51 |
* freed in ::HTTPAPI_CloseConnection. |
| 52 |
*/ |
| 53 |
MOCKABLE_FUNCTION(, void, HTTPAPI_CloseConnection, HTTP_HANDLE, handle); |
| 54 |
|
| 55 |
/** |
| 56 |
* @brief Sends the HTTP request to the host and handles the response for |
| 57 |
* the HTTP call. |
| 58 |
* |
| 59 |
* @param handle The handle to the HTTP connection created |
| 60 |
* via ::HTTPAPI_CreateConnection. |
| 61 |
* @param requestType Specifies which HTTP method is used (GET, |
| 62 |
* POST, DELETE, PUT, PATCH). |
| 63 |
* @param relativePath Specifies the relative path of the URL |
| 64 |
* excluding the host name. |
| 65 |
* @param httpHeadersHandle Specifies a set of HTTP headers (name-value |
| 66 |
* pairs) to be added to the |
| 67 |
* HTTP request. The @p httpHeadersHandle |
| 68 |
* handle can be created and setup with |
| 69 |
* the proper name-value pairs by using the |
| 70 |
* HTTPHeaders APIs available in @c |
| 71 |
* HTTPHeaders.h. |
| 72 |
* @param content Specifies a pointer to the request body. |
| 73 |
* This value is optional and can be @c NULL. |
| 74 |
* @param contentLength Specifies the request body size (this is |
| 75 |
* typically added into the HTTP headers as |
| 76 |
* the Content-Length header). This value is |
| 77 |
* optional and can be 0. |
| 78 |
* @param statusCode This is an out parameter, where |
| 79 |
* ::HTTPAPI_ExecuteRequest returns the status |
| 80 |
* code from the HTTP response (200, 201, 400, |
| 81 |
* 401, etc.) |
| 82 |
* @param responseHeadersHandle This is an HTTP headers handle to which |
| 83 |
* ::HTTPAPI_ExecuteRequest shall add all the |
| 84 |
* HTTP response headers so that the caller of |
| 85 |
* ::HTTPAPI_ExecuteRequest can inspect them. |
| 86 |
* You can manipulate @p responseHeadersHandle |
| 87 |
* by using the HTTPHeaders APIs available in |
| 88 |
* @c HTTPHeaders.h |
| 89 |
* @param responseContent This is a buffer that shall be filled by |
| 90 |
* ::HTTPAPI_ExecuteRequest with the contents |
| 91 |
* of the HTTP response body. The buffer size |
| 92 |
* shall be increased by the |
| 93 |
* ::HTTPAPI_ExecuteRequest implementation in |
| 94 |
* order to fit the response body. |
| 95 |
* ::HTTPAPI_ExecuteRequest shall also handle |
| 96 |
* chunked transfer encoding for HTTP responses. |
| 97 |
* To manipulate the @p responseContent buffer, |
| 98 |
* use the APIs available in @c Strings.h. |
| 99 |
* |
| 100 |
* @return @c HTTPAPI_OK if the API call is successful or an error |
| 101 |
* code in case it fails. |
| 102 |
*/ |
| 103 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_ExecuteRequest, HTTP_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath, |
| 104 |
HTTP_HEADERS_HANDLE, httpHeadersHandle, const unsigned char*, content, |
| 105 |
size_t, contentLength, unsigned int*, statusCode, |
| 106 |
HTTP_HEADERS_HANDLE, responseHeadersHandle, BUFFER_HANDLE, responseContent); |
| 107 |
|
| 108 |
/** |
| 109 |
* @brief Sets the option named @p optionName bearing the value |
| 110 |
* @p value for the HTTP_HANDLE @p handle. |
| 111 |
* |
| 112 |
* @param handle The handle to the HTTP connection created via |
| 113 |
* ::HTTPAPI_CreateConnection. |
| 114 |
* @param optionName A @c NULL terminated string representing the name |
| 115 |
* of the option. |
| 116 |
* @param value A pointer to the value for the option. |
| 117 |
* |
| 118 |
* @return @c HTTPAPI_OK if initialization is successful or an error |
| 119 |
* code in case it fails. |
| 120 |
*/ |
| 121 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, const char*, optionName, const void*, value); |
| 122 |
|
| 123 |
/** |
| 124 |
* @brief Clones the option named @p optionName bearing the value @p value |
| 125 |
* into the pointer @p savedValue. |
| 126 |
* |
| 127 |
* @param optionName A @c NULL terminated string representing the name of |
| 128 |
* the option |
| 129 |
* @param value A pointer to the value of the option. |
| 130 |
* @param savedValue This pointer receives the copy of the value of the |
| 131 |
* option. The copy needs to be free-able. |
| 132 |
* |
| 133 |
* @return @c HTTPAPI_OK if initialization is successful or an error |
| 134 |
* code in case it fails. |
| 135 |
*/ |
| 136 |
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue); |
| 137 |
``` |
| 138 |
**]** |
| 139 |
|
| 140 |
**SRS_HTTPAPI_COMPACT_21_002: [** The httpapi_compact shall support the http requests: |
| 141 |
```c |
| 142 |
#define HTTPAPI_REQUEST_TYPE_VALUES \ |
| 143 |
HTTPAPI_REQUEST_GET, \ |
| 144 |
HTTPAPI_REQUEST_POST, \ |
| 145 |
HTTPAPI_REQUEST_PUT, \ |
| 146 |
HTTPAPI_REQUEST_DELETE, \ |
| 147 |
HTTPAPI_REQUEST_PATCH \ |
| 148 |
|
| 149 |
/** @brief Enumeration specifying the HTTP request verbs accepted by |
| 150 |
* the HTTPAPI module. |
| 151 |
*/ |
| 152 |
MU_DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES); |
| 153 |
``` |
| 154 |
**]** |
| 155 |
|
| 156 |
**SRS_HTTPAPI_COMPACT_21_003: [** The httpapi_compact shall return error codes defined by HTTPAPI_RESULT: |
| 157 |
```c |
| 158 |
#define HTTPAPI_RESULT_VALUES \ |
| 159 |
HTTPAPI_OK, \ |
| 160 |
HTTPAPI_INVALID_ARG, \ |
| 161 |
HTTPAPI_ERROR, \ |
| 162 |
HTTPAPI_OPEN_REQUEST_FAILED, \ |
| 163 |
HTTPAPI_SET_OPTION_FAILED, \ |
| 164 |
HTTPAPI_SEND_REQUEST_FAILED, \ |
| 165 |
HTTPAPI_RECEIVE_RESPONSE_FAILED, \ |
| 166 |
HTTPAPI_QUERY_HEADERS_FAILED, \ |
| 167 |
HTTPAPI_QUERY_DATA_AVAILABLE_FAILED, \ |
| 168 |
HTTPAPI_READ_DATA_FAILED, \ |
| 169 |
HTTPAPI_ALREADY_INIT, \ |
| 170 |
HTTPAPI_NOT_INIT, \ |
| 171 |
HTTPAPI_HTTP_HEADERS_FAILED, \ |
| 172 |
HTTPAPI_STRING_PROCESSING_ERROR, \ |
| 173 |
HTTPAPI_ALLOC_FAILED, \ |
| 174 |
HTTPAPI_INIT_FAILED, \ |
| 175 |
HTTPAPI_INSUFFICIENT_RESPONSE_BUFFER, \ |
| 176 |
HTTPAPI_SET_X509_FAILURE, \ |
| 177 |
HTTPAPI_SET_TIMEOUTS_FAILED \ |
| 178 |
|
| 179 |
/** @brief Enumeration specifying the possible return values for the APIs in |
| 180 |
* this module. |
| 181 |
*/ |
| 182 |
MU_DEFINE_ENUM(HTTPAPI_RESULT, HTTPAPI_RESULT_VALUES); |
| 183 |
``` |
| 184 |
**]** |
| 185 |
|
| 186 |
|
| 187 |
### HTTPAPI_Init |
| 188 |
```c |
| 189 |
HTTPAPI_RESULT HTTPAPI_Init(void); |
| 190 |
``` |
| 191 |
|
| 192 |
**SRS_HTTPAPI_COMPACT_21_004: [** The HTTPAPI_Init shall allocate all memory to control the http protocol. **]** |
| 193 |
|
| 194 |
**SRS_HTTPAPI_COMPACT_21_006: [** If HTTPAPI_Init succeed allocating all the needed memory, it shall return HTTPAPI_OK. **]** |
| 195 |
|
| 196 |
**SRS_HTTPAPI_COMPACT_21_007: [** If there is not enough memory to control the http protocol, the HTTPAPI_Init shall return HTTPAPI_ALLOC_FAILED. **]** |
| 197 |
|
| 198 |
|
| 199 |
### HTTPAPI_Deinit |
| 200 |
```c |
| 201 |
void HTTPAPI_Deinit(void); |
| 202 |
``` |
| 203 |
|
| 204 |
**SRS_HTTPAPI_COMPACT_21_009: [** The HTTPAPI_Init shall release all memory allocated by the httpapi_compact. **]** |
| 205 |
|
| 206 |
|
| 207 |
### HTTPAPI_CreateConnection |
| 208 |
```c |
| 209 |
HTTP_HANDLE HTTPAPI_CreateConnection(const char* hostName); |
| 210 |
``` |
| 211 |
|
| 212 |
**SRS_HTTPAPI_COMPACT_21_011: [** The HTTPAPI_CreateConnection shall create an http connection to the host specified by the hostName parameter. **]** |
| 213 |
|
| 214 |
**SRS_HTTPAPI_COMPACT_21_012: [** The HTTPAPI_CreateConnection shall return a non-NULL handle on success. **]** |
| 215 |
|
| 216 |
**SRS_HTTPAPI_COMPACT_21_013: [** If there is not enough memory to control the http connection, the HTTPAPI_CreateConnection shall return NULL as the handle. **]** |
| 217 |
|
| 218 |
**SRS_HTTPAPI_COMPACT_21_014: [** If the hostName is NULL, the HTTPAPI_CreateConnection shall return NULL as the handle. **]** |
| 219 |
|
| 220 |
**SRS_HTTPAPI_COMPACT_21_015: [** If the hostName is empty, the HTTPAPI_CreateConnection shall return NULL as the handle. **]** |
| 221 |
|
| 222 |
**SRS_HTTPAPI_COMPACT_21_016: [** If the HTTPAPI_CreateConnection failed to create the connection, it shall return NULL as the handle. **]** |
| 223 |
|
| 224 |
|
| 225 |
### HTTPAPI_CloseConnection |
| 226 |
```c |
| 227 |
void HTTPAPI_CloseConnection(HTTP_HANDLE handle); |
| 228 |
``` |
| 229 |
|
| 230 |
**SRS_HTTPAPI_COMPACT_21_017: [** The HTTPAPI_CloseConnection shall close the connection previously created in HTTPAPI_ExecuteRequest. **]** |
| 231 |
|
| 232 |
**SRS_HTTPAPI_COMPACT_21_076: [** After close the connection, The HTTPAPI_CloseConnection shall destroy the connection previously created in HTTPAPI_CreateConnection. **]** |
| 233 |
|
| 234 |
**SRS_HTTPAPI_COMPACT_21_018: [** If there is a certificate associated to this connection, the HTTPAPI_CloseConnection shall free all allocated memory for the certificate. **]** |
| 235 |
|
| 236 |
**SRS_HTTPAPI_COMPACT_06_001: [** If there is a x509 client certificate associated to this connection, the HTTAPI_CloseConnection shall free all allocated memory for the certificate. **]** |
| 237 |
|
| 238 |
**SRS_HTTPAPI_COMPACT_06_002: [** If there is a x509 client private key associated to this connection, then HTTP_CloseConnection shall free all the allocated memory for the private key. **]** |
| 239 |
|
| 240 |
**SRS_HTTPAPI_COMPACT_21_019: [** If there is no previous connection, the HTTPAPI_CloseConnection shall not do anything. **]** |
| 241 |
|
| 242 |
**SRS_HTTPAPI_COMPACT_21_020: [** If the connection handle is NULL, the HTTPAPI_CloseConnection shall not do anything. **]** |
| 243 |
|
| 244 |
**SRS_HTTPAPI_COMPACT_21_084: [** The HTTPAPI_CloseConnection shall wait, at least, 10 seconds for the SSL close process. **]** |
| 245 |
|
| 246 |
**SRS_HTTPAPI_COMPACT_21_085: [** If the HTTPAPI_CloseConnection retries 10 seconds to close the connection without success, it shall destroy the connection anyway. **]** |
| 247 |
|
| 248 |
**SRS_HTTPAPI_COMPACT_21_086: [** The HTTPAPI_CloseConnection shall wait, at least, 100 milliseconds between retries. **]** |
| 249 |
|
| 250 |
**SRS_HTTPAPI_COMPACT_21_087: [** If the xio return anything different than 0, the HTTPAPI_CloseConnection shall destroy the connection anyway. **]** |
| 251 |
|
| 252 |
### HTTPAPI_ExecuteRequest |
| 253 |
```c |
| 254 |
HTTPAPI_RESULT HTTPAPI_ExecuteRequest(HTTP_HANDLE handle, HTTPAPI_REQUEST_TYPE requestType, const char* relativePath, |
| 255 |
HTTP_HEADERS_HANDLE httpHeadersHandle, const unsigned char* content, |
| 256 |
size_t contentLength, unsigned int* statusCode, |
| 257 |
HTTP_HEADERS_HANDLE responseHeadersHandle, BUFFER_HANDLE responseContent); |
| 258 |
``` |
| 259 |
|
| 260 |
**SRS_HTTPAPI_COMPACT_21_021: [** The HTTPAPI_ExecuteRequest shall execute the http communtication with the provided host, sending a request and reciving the response. **]** |
| 261 |
|
| 262 |
**SRS_HTTPAPI_COMPACT_21_022: [** If a Certificate was provided, the HTTPAPI_ExecuteRequest shall set this option on the transport layer. **]** |
| 263 |
|
| 264 |
**SRS_HTTPAPI_COMPACT_21_023: [** If the transport failed setting the Certificate, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]** |
| 265 |
|
| 266 |
**SRS_HTTPAPI_COMPACT_06_003: [** If the x509 client certificate is provided, the HTTPAPI_ExecuteRequest shall set this option on the transport layer. **]** |
| 267 |
|
| 268 |
**SRS_HTTPAPI_COMPACT_06_005: [** If the transport failed setting the client certificate, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]** |
| 269 |
|
| 270 |
**SRS_HTTPAPI_COMPACT_06_004: [** If the x509 client certificate private key is provided, the HTTPAPI_ExecuteRequest shall set this optionon the transport layer. **]** |
| 271 |
|
| 272 |
**SRS_HTTPAPI_COMPACT_06_006: [** If the transport failed setting the client certificate private key, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_SET_OPTION_FAILED. **]** |
| 273 |
|
| 274 |
**SRS_HTTPAPI_COMPACT_21_024: [** The HTTPAPI_ExecuteRequest shall open the transport connection with the host to send the request. **]** |
| 275 |
|
| 276 |
**SRS_HTTPAPI_COMPACT_21_025: [** If the open process failed, the HTTPAPI_ExecuteRequest shall not send any request and return HTTPAPI_OPEN_REQUEST_FAILED. **]** |
| 277 |
|
| 278 |
**SRS_HTTPAPI_COMPACT_21_026: [** If the open process succeed, the HTTPAPI_ExecuteRequest shall send the request message to the host. **]** |
| 279 |
|
| 280 |
**SRS_HTTPAPI_COMPACT_21_027: [** If the HTTPAPI_ExecuteRequest cannot create a buffer to send the request, it shall not send any request and return HTTPAPI_STRING_PROCESSING_ERROR. **]** |
| 281 |
|
| 282 |
**SRS_HTTPAPI_COMPACT_21_028: [** If the HTTPAPI_ExecuteRequest cannot send the request header, it shall return HTTPAPI_HTTP_HEADERS_FAILED. **]** |
| 283 |
|
| 284 |
**SRS_HTTPAPI_COMPACT_21_029: [** If the HTTPAPI_ExecuteRequest cannot send the buffer with the request, it shall return HTTPAPI_SEND_REQUEST_FAILED. **]** |
| 285 |
|
| 286 |
**SRS_HTTPAPI_COMPACT_21_030: [** At the end of the transmission, the HTTPAPI_ExecuteRequest shall receive the response from the host. **]** |
| 287 |
|
| 288 |
**SRS_HTTPAPI_COMPACT_21_032: [** If the HTTPAPI_ExecuteRequest cannot read the message with the request result, it shall return HTTPAPI_READ_DATA_FAILED. **]** |
| 289 |
|
| 290 |
**SRS_HTTPAPI_COMPACT_21_033: [** If the whole process succeed, the HTTPAPI_ExecuteRequest shall retur HTTPAPI_OK. **]** |
| 291 |
|
| 292 |
**SRS_HTTPAPI_COMPACT_21_034: [** If there is no previous connection, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]** |
| 293 |
|
| 294 |
**SRS_HTTPAPI_COMPACT_21_035: [** The HTTPAPI_ExecuteRequest shall execute resquest for types `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. **]** |
| 295 |
|
| 296 |
**SRS_HTTPAPI_COMPACT_21_036: [** The request type shall be provided in the parameter requestType. **]** |
| 297 |
|
| 298 |
**SRS_HTTPAPI_COMPACT_21_037: [** If the request type is unknown, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]** |
| 299 |
|
| 300 |
**SRS_HTTPAPI_COMPACT_21_038: [** The HTTPAPI_ExecuteRequest shall execute the resquest for the path in relativePath parameter. **]** |
| 301 |
|
| 302 |
**SRS_HTTPAPI_COMPACT_21_039: [** If the relativePath is NULL or invalid, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]** |
| 303 |
|
| 304 |
**SRS_HTTPAPI_COMPACT_21_040: [** The request shall contain the http header provided in httpHeadersHandle parameter. **]** |
| 305 |
|
| 306 |
**SRS_HTTPAPI_COMPACT_21_041: [** If the httpHeadersHandle is NULL or invalid, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]** |
| 307 |
|
| 308 |
**SRS_HTTPAPI_COMPACT_21_042: [** The request can contain the a content message, provided in content parameter. **]** |
| 309 |
|
| 310 |
**SRS_HTTPAPI_COMPACT_21_043: [** If the content is NULL, the HTTPAPI_ExecuteRequest shall send the request without content. **]** |
| 311 |
|
| 312 |
**SRS_HTTPAPI_COMPACT_21_044: [** If the content is not NULL, the number of bytes in the content shall be provided in contentLength parameter. **]** |
| 313 |
|
| 314 |
**SRS_HTTPAPI_COMPACT_21_045: [** If the contentLength is lower than one, the HTTPAPI_ExecuteRequest shall send the request without content. **]** |
| 315 |
|
| 316 |
**SRS_HTTPAPI_COMPACT_21_046: [** The HTTPAPI_ExecuteRequest shall return the http status reported by the host in the received response. **]** |
| 317 |
|
| 318 |
**SRS_HTTPAPI_COMPACT_21_047: [** The HTTPAPI_ExecuteRequest shall report the status in the statusCode parameter. **]** |
| 319 |
|
| 320 |
**SRS_HTTPAPI_COMPACT_21_048: [** If the statusCode is NULL, the HTTPAPI_ExecuteRequest shall report not report any status. **]** |
| 321 |
|
| 322 |
**SRS_HTTPAPI_COMPACT_21_049: [** If responseHeadersHandle is provide, the HTTPAPI_ExecuteRequest shall prepare a Response Header usign the HTTPHeaders_AddHeaderNameValuePair. **]** |
| 323 |
|
| 324 |
**SRS_HTTPAPI_COMPACT_21_050: [** If there is a content in the response, the HTTPAPI_ExecuteRequest shall copy it in the responseContent buffer. **]** |
| 325 |
|
| 326 |
**SRS_HTTPAPI_COMPACT_21_051: [** If the responseContent is NULL, the HTTPAPI_ExecuteRequest shall ignore any content in the response. **]** |
| 327 |
|
| 328 |
**SRS_HTTPAPI_COMPACT_21_052: [** If any memory allocation get fail, the HTTPAPI_ExecuteRequest shall return HTTPAPI_ALLOC_FAILED. **]** |
| 329 |
|
| 330 |
**SRS_HTTPAPI_COMPACT_21_053: [** The HTTPAPI_ExecuteRequest shall produce a set of http header to send to the host. **]** |
| 331 |
|
| 332 |
**SRS_HTTPAPI_COMPACT_21_054: [** If Http header maker cannot provide the number of headers, the HTTPAPI_ExecuteRequest shall return HTTPAPI_INVALID_ARG. **]** |
| 333 |
|
| 334 |
**SRS_HTTPAPI_COMPACT_21_055: [** If the HTTPAPI_ExecuteRequest cannot parser the received message, it shall return HTTPAPI_RECEIVE_RESPONSE_FAILED. **]** |
| 335 |
|
| 336 |
**SRS_HTTPAPI_COMPACT_21_073: [** The message received by the HTTPAPI_ExecuteRequest shall starts with a valid header. **]** |
| 337 |
|
| 338 |
**SRS_HTTPAPI_COMPACT_21_074: [** After the header, the message received by the HTTPAPI_ExecuteRequest can contain addition information about the content. **]** |
| 339 |
|
| 340 |
**SRS_HTTPAPI_COMPACT_21_075: [** The message received by the HTTPAPI_ExecuteRequest can contain a body with the message content. **]** |
| 341 |
|
| 342 |
**SRS_HTTPAPI_COMPACT_21_077: [** The HTTPAPI_ExecuteRequest shall wait, at least, 10 seconds for the SSL open process. **]** |
| 343 |
|
| 344 |
**SRS_HTTPAPI_COMPACT_21_078: [** If the HTTPAPI_ExecuteRequest cannot open the connection in 10 seconds, it shall fail and return HTTPAPI_OPEN_REQUEST_FAILED. **]** |
| 345 |
|
| 346 |
**SRS_HTTPAPI_COMPACT_21_079: [** The HTTPAPI_ExecuteRequest shall wait, at least, 20 seconds to send a buffer using the SSL connection. **]** |
| 347 |
|
| 348 |
**SRS_HTTPAPI_COMPACT_21_080: [** If the HTTPAPI_ExecuteRequest retries to send the message for 20 seconds without success, it shall fail and return HTTPAPI_SEND_REQUEST_FAILED. **]** |
| 349 |
|
| 350 |
**SRS_HTTPAPI_COMPACT_21_081: [** The HTTPAPI_ExecuteRequest shall try to read the message with the response up to 20 seconds. **]** |
| 351 |
|
| 352 |
**SRS_HTTPAPI_COMPACT_21_082: [** If the HTTPAPI_ExecuteRequest retries 20 seconds to receive the message without success, it shall fail and return HTTPAPI_READ_DATA_FAILED. **]** |
| 353 |
|
| 354 |
**SRS_HTTPAPI_COMPACT_21_083: [** The HTTPAPI_ExecuteRequest shall wait, at least, 100 milliseconds between retries. **]** |
| 355 |
|
| 356 |
**SRS_HTTPAPI_COMPACT_42_088: [** The message received by the HTTPAPI_ExecuteRequest should not contain http body. **]** |
| 357 |
|
| 358 |
|
| 359 |
### HTTPAPI_SetOption |
| 360 |
```c |
| 361 |
HTTPAPI_RESULT HTTPAPI_SetOption(HTTP_HANDLE handle, const char* optionName, const void* value); |
| 362 |
``` |
| 363 |
|
| 364 |
**SRS_HTTPAPI_COMPACT_21_056: [** The HTTPAPI_SetOption shall change the HTTP options. **]** |
| 365 |
|
| 366 |
**SRS_HTTPAPI_COMPACT_21_057: [** The HTTPAPI_SetOption shall receive a handle that identiry the HTTP connection. **]** |
| 367 |
|
| 368 |
**SRS_HTTPAPI_COMPACT_21_058: [** The HTTPAPI_SetOption shall receive the option as a pair optionName/value. **]** |
| 369 |
|
| 370 |
**SRS_HTTPAPI_COMPACT_21_059: [** If the handle is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]** |
| 371 |
|
| 372 |
**SRS_HTTPAPI_COMPACT_21_060: [** If the optionName is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]** |
| 373 |
|
| 374 |
**SRS_HTTPAPI_COMPACT_21_061: [** If the value is NULL, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]** |
| 375 |
|
| 376 |
**SRS_HTTPAPI_COMPACT_21_062: [** If any memory allocation get fail, the HTTPAPI_SetOption shall return HTTPAPI_ALLOC_FAILED. **]** |
| 377 |
|
| 378 |
**SRS_HTTPAPI_COMPACT_21_063: [** If the HTTP do not support the optionName, the HTTPAPI_SetOption shall return HTTPAPI_INVALID_ARG. **]** |
| 379 |
|
| 380 |
**SRS_HTTPAPI_COMPACT_21_064: [** If the HTTPAPI_SetOption get success setting the option, it shall return HTTPAPI_OK. **]** |
| 381 |
|
| 382 |
|
| 383 |
### HTTPAPI_CloneOption |
| 384 |
```c |
| 385 |
HTTPAPI_RESULT HTTPAPI_CloneOption(const char* optionName, const void* value, const void** savedValue); |
| 386 |
``` |
| 387 |
|
| 388 |
**SRS_HTTPAPI_COMPACT_21_065: [** The HTTPAPI_CloneOption shall provide the means to clone the HTTP option. **]** |
| 389 |
|
| 390 |
**SRS_HTTPAPI_COMPACT_21_066: [** The HTTPAPI_CloneOption shall return a clone of the value identified by the optionName. **]** |
| 391 |
|
| 392 |
**SRS_HTTPAPI_COMPACT_21_067: [** If the optionName is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]** |
| 393 |
|
| 394 |
**SRS_HTTPAPI_COMPACT_21_068: [** If the value is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]** |
| 395 |
|
| 396 |
**SRS_HTTPAPI_COMPACT_21_069: [** If the savedValue is NULL, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]** |
| 397 |
|
| 398 |
**SRS_HTTPAPI_COMPACT_21_070: [** If any memory allocation get fail, the HTTPAPI_CloneOption shall return HTTPAPI_ALLOC_FAILED. **]** |
| 399 |
|
| 400 |
**SRS_HTTPAPI_COMPACT_21_071: [** If the HTTP do not support the optionName, the HTTPAPI_CloneOption shall return HTTPAPI_INVALID_ARG. **]** |
| 401 |
|
| 402 |
**SRS_HTTPAPI_COMPACT_21_072: [** If the HTTPAPI_CloneOption get success setting the option, it shall return HTTPAPI_OK. **]** |