httpapiex.h

00001 // Copyright (c) Microsoft. All rights reserved.
00002 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
00003 
00004 /** @file httpapiex.h
00005 *   @brief      This is a utility module that provides HTTP requests with
00006 *               build-in retry capabilities.
00007 *
00008 *   @details    HTTAPIEX is a utility module that provides HTTP requests with build-in
00009 *               retry capability to an HTTP server. Features over "regular" HTTPAPI include:
00010 *                   - Optional parameters
00011 *                   - Implementation independent
00012 *                   - Retry mechanism
00013 *                   - Persistent options
00014 */
00015 
00016 #ifndef HTTPAPIEX_H
00017 #define HTTPAPIEX_H
00018 
00019 #include "azure_c_shared_utility/macro_utils.h"
00020 #include "azure_c_shared_utility/httpapi.h"
00021 #include "azure_c_shared_utility/umock_c_prod.h"
00022  
00023 #ifdef __cplusplus
00024 #include <cstddef>
00025 extern "C" {
00026 #else
00027 #include <stddef.h>
00028 #endif
00029 
00030 typedef struct HTTPAPIEX_HANDLE_DATA_TAG* HTTPAPIEX_HANDLE;
00031 
00032 #define HTTPAPIEX_RESULT_VALUES \
00033     HTTPAPIEX_OK, \
00034     HTTPAPIEX_ERROR, \
00035     HTTPAPIEX_INVALID_ARG, \
00036     HTTPAPIEX_RECOVERYFAILED
00037 /*to be continued*/
00038 
00039 /** @brief Enumeration specifying the status of calls to various APIs in this module.
00040 */
00041 DEFINE_ENUM(HTTPAPIEX_RESULT, HTTPAPIEX_RESULT_VALUES);
00042 
00043 /**
00044  * @brief   Creates an @c HTTPAPIEX_HANDLE that can be used in further calls.
00045  *
00046  * @param   hostName    Pointer to a null-terminated string that contains the host name
00047  *                      of an HTTP server.
00048  *                      
00049  *          If @p hostName is @c NULL then @c HTTPAPIEX_Create returns @c NULL. The @p
00050  *          hostName value is saved and associated with the returned handle. If creating
00051  *          the handle fails for any reason, then @c HTTAPIEX_Create returns @c NULL.
00052  *          Otherwise, @c HTTPAPIEX_Create returns an @c HTTAPIEX_HANDLE suitable for
00053  *          further calls to the module.
00054  *
00055  * @return  An @c HTTAPIEX_HANDLE suitable for further calls to the module.
00056  */
00057 MOCKABLE_FUNCTION(, HTTPAPIEX_HANDLE, HTTPAPIEX_Create, const char*, hostName);
00058 
00059 /**
00060  * @brief   Tries to execute an HTTP request.
00061  *
00062  * @param   handle                      A valid @c HTTPAPIEX_HANDLE value.
00063  * @param   requestType                 A value from the ::HTTPAPI_REQUEST_TYPE enum.
00064  * @param   relativePath                Relative path to send the request to on the server.
00065  * @param   requestHttpHeadersHandle    Handle to the request HTTP headers.
00066  * @param   requestContent              The request content.
00067  * @param   statusCode                  If non-null, the HTTP status code is written to this
00068  *                                      pointer.
00069  * @param   responseHttpHeadersHandle   Handle to the response HTTP headers.
00070  * @param   responseContent             The response content.
00071  *                                      
00072  *          @c HTTPAPIEX_ExecuteRequest tries to execute an HTTP request of type @p
00073  *          requestType, on the server's @p relativePath, pushing the request HTTP
00074  *          headers @p requestHttpHeadersHandle, having the content of the request
00075  *          as pointed to by @p requestContent. If successful,  @c HTTAPIEX_ExecuteRequest
00076  *          writes in the out @p parameter statusCode the HTTP status, populates the @p
00077  *          responseHeadersHandle with the response headers and copies the response body
00078  *          to @p responseContent.
00079  *
00080  * @return  An @c HTTAPIEX_HANDLE suitable for further calls to the module.
00081  */
00082 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);
00083 
00084 /**
00085  * @brief   Frees all resources used by the @c HTTPAPIEX_HANDLE object.
00086  *
00087  * @param   handle  The @c HTTPAPIEX_HANDLE object to be freed.
00088  */
00089 MOCKABLE_FUNCTION(, void, HTTPAPIEX_Destroy, HTTPAPIEX_HANDLE, handle);
00090 
00091 /**
00092  * @brief   Sets the option @p optionName to the value pointed to by @p value.
00093  *
00094  * @param   handle      The @c HTTPAPIEX_HANDLE representing this session.
00095  * @param   optionName  Name of the option.
00096  * @param   value       The value to be set for the option.
00097  *
00098  * @return  An @c HTTPAPIEX_RESULT indicating the status of the call.
00099  */
00100 MOCKABLE_FUNCTION(, HTTPAPIEX_RESULT, HTTPAPIEX_SetOption, HTTPAPIEX_HANDLE, handle, const char*, optionName, const void*, value);
00101 
00102 #ifdef __cplusplus
00103 }
00104 #endif
00105 
00106 #endif /* HTTPAPIEX_H */