inc/azure_c_shared_utility/httpapi.h

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

/** @file httpapi.h
 *    @deprecated Applications should not directly use this header file.  They should use httpapiex.h instead.
 *
 *    @brief   Deprecated module implements the standard HTTP API used by the C IoT client
 *             library.
 *
 *    @details For example, on the Windows platform the HTTP API code uses
 *             WinHTTP and for Linux it uses curl and so forth. HTTPAPI must support
 *             HTTPs (HTTP+SSL).
 *    
 *    @remarks This header file is deprecated in the sense that applications should not directly invoke it.  
 *             It remains the contract that instantiations of the HTTP clients on various platforms
 *             (e.g. curl and WinHTTP) are implemented to.
 *
 *             Applications should not directly invoke functions in this header because this layer does
 *             not follow the standard allocation/copying rules of the rest of the SDK.  When passed
 *             a memory buffer, this layer points directly to the memory and does not make a copy or use reference counting.
 *             This means there can be a crash if the caller free()'s the data but this layer needs it.
 *             The httpapiex.h layer follows the conventions throughout the rest of the SDK and is 
 *             therefore safer and less likely to cause unexpected problems for callers.
 */

#ifndef HTTPAPI_H
#define HTTPAPI_H

#ifdef __cplusplus
#include <cstddef>
#else
#include <stddef.h>
#endif

#include "azure_macro_utils/macro_utils.h"
#include "azure_c_shared_utility/httpheaders.h"
#include "azure_c_shared_utility/buffer_.h"
#include "umock_c/umock_c_prod.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef struct HTTP_HANDLE_DATA_TAG* HTTP_HANDLE;

#define AMBIGUOUS_STATUS_CODE           (300)

#define HTTPAPI_RESULT_VALUES                \
HTTPAPI_OK,                                  \
HTTPAPI_INVALID_ARG,                         \
HTTPAPI_ERROR,                               \
HTTPAPI_OPEN_REQUEST_FAILED,                 \
HTTPAPI_SET_OPTION_FAILED,                   \
HTTPAPI_SEND_REQUEST_FAILED,                 \
HTTPAPI_RECEIVE_RESPONSE_FAILED,             \
HTTPAPI_QUERY_HEADERS_FAILED,                \
HTTPAPI_QUERY_DATA_AVAILABLE_FAILED,         \
HTTPAPI_READ_DATA_FAILED,                    \
HTTPAPI_ALREADY_INIT,                        \
HTTPAPI_NOT_INIT,                            \
HTTPAPI_HTTP_HEADERS_FAILED,                 \
HTTPAPI_STRING_PROCESSING_ERROR,             \
HTTPAPI_ALLOC_FAILED,                        \
HTTPAPI_INIT_FAILED,                         \
HTTPAPI_INSUFFICIENT_RESPONSE_BUFFER,        \
HTTPAPI_SET_X509_FAILURE,                    \
HTTPAPI_SET_TIMEOUTS_FAILED                  \

/** @brief Enumeration specifying the possible return values for the APIs in
 *           this module.
 */
MU_DEFINE_ENUM(HTTPAPI_RESULT, HTTPAPI_RESULT_VALUES);

#define HTTPAPI_REQUEST_TYPE_VALUES\
    HTTPAPI_REQUEST_GET,            \
    HTTPAPI_REQUEST_POST,           \
    HTTPAPI_REQUEST_PUT,            \
    HTTPAPI_REQUEST_DELETE,         \
    HTTPAPI_REQUEST_PATCH,          \
    HTTPAPI_REQUEST_HEAD            \


/** @brief Enumeration specifying the HTTP request verbs accepted by
 *    the HTTPAPI module.
 */
MU_DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES);

#define MAX_HOSTNAME_LEN        65
#define MAX_USERNAME_LEN        65
#define MAX_PASSWORD_LEN        65

/**
 * @deprecated Applications should not directly invoke this function.  They should use httpapiex.h instead.
 *
 * @brief    Global initialization for the HTTP API component.
 *
 *            Platform specific implementations are expected to initialize
 *            the underlying HTTP API stacks.
 *
 * @return    @c HTTPAPI_OK if initialization is successful or an error
 *             code in case it fails.
 */
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_Init);

/** @brief    Free resources allocated in ::HTTPAPI_Init. 
  *
  * @deprecated Applications should not directly invoke this function.  They should use httpapiex.h instead.
  *
*/
MOCKABLE_FUNCTION(, void, HTTPAPI_Deinit);

/**
 * @deprecated Applications should not directly invoke this function.  They should use httpapiex.h instead.
 *
 * @brief    Creates an HTTPS connection to the host specified by the @p
 *             hostName parameter.
 *
 * @param    hostName    Name of the host.
 *
 *            This function returns a handle to the newly created connection.
 *            You can use the handle in subsequent calls to execute specific
 *            HTTP calls using ::HTTPAPI_ExecuteRequest.
 *
 * @return    A @c HTTP_HANDLE to the newly created connection or @c NULL in
 *             case an error occurs.
 */
MOCKABLE_FUNCTION(, HTTP_HANDLE, HTTPAPI_CreateConnection, const char*, hostName);

/**
 *
 * @deprecated Applications should not directly invoke this function.  They should use httpapiex.h instead.
 *
 * @brief    Closes a connection created with ::HTTPAPI_CreateConnection.
 *
 * @param    handle    The handle to the HTTP connection created via ::HTTPAPI_CreateConnection.
 *
 *             All resources allocated by ::HTTPAPI_CreateConnection should be
 *             freed in ::HTTPAPI_CloseConnection.
 */
MOCKABLE_FUNCTION(, void, HTTPAPI_CloseConnection, HTTP_HANDLE, handle);

/**
 * @brief    Sends the HTTP request to the host and handles the response for
 *             the HTTP call.
 *
 * @param    handle                     The handle to the HTTP connection created
 *                                     via ::HTTPAPI_CreateConnection.
 * @param    requestType                 Specifies which HTTP method is used (GET,
 *                                     POST, DELETE, PUT, PATCH).
 * @param    relativePath             Specifies the relative path of the URL
 *                                     excluding the host name.
 * @param    httpHeadersHandle         Specifies a set of HTTP headers (name-value
 *                                     pairs) to be added to the
 *                                     HTTP request. The @p httpHeadersHandle
 *                                     handle can be created and setup with
 *                                     the proper name-value pairs by using the
 *                                     HTTPHeaders APIs available in @c
 *                                     HTTPHeaders.h.
 * @param    content                     Specifies a pointer to the request body.
 *                                     This value is optional and can be @c NULL.
 * @param    contentLength             Specifies the request body size (this is
 *                                     typically added into the HTTP headers as
 *                                     the Content-Length header). This value is
 *                                     optional and can be 0.
 * @param   statusCode               This is an out parameter, where
 *                                     ::HTTPAPI_ExecuteRequest returns the status
 *                                     code from the HTTP response (200, 201, 400,
 *                                     401, etc.)
 * @param    responseHeadersHandle    This is an HTTP headers handle to which
 *                                     ::HTTPAPI_ExecuteRequest must add all the
 *                                     HTTP response headers so that the caller of
 *                                     ::HTTPAPI_ExecuteRequest can inspect them.
 *                                     You can manipulate @p responseHeadersHandle
 *                                     by using the HTTPHeaders APIs available in
 *                                     @c HTTPHeaders.h
 * @param    responseContent             This is a buffer that must be filled by
 *                                     ::HTTPAPI_ExecuteRequest with the contents
 *                                     of the HTTP response body. The buffer size
 *                                     must be increased by the
 *                                     ::HTTPAPI_ExecuteRequest implementation in
 *                                     order to fit the response body.
 *                                     ::HTTPAPI_ExecuteRequest must also handle
 *                                     chunked transfer encoding for HTTP responses.
 *                                     To manipulate the @p responseContent buffer,
 *                                     use the APIs available in @c Strings.h.
 *
 * @return    @c HTTPAPI_OK if the API call is successful or an error
 *             code in case it fails.
 */
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_ExecuteRequest, HTTP_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath,
                                             HTTP_HEADERS_HANDLE, httpHeadersHandle, const unsigned char*, content,
                                             size_t, contentLength, unsigned int*, statusCode,
                                             HTTP_HEADERS_HANDLE, responseHeadersHandle, BUFFER_HANDLE, responseContent);

/**
 * @deprecated Applications should not directly invoke this function.  They should use httpapiex.h instead.
 *
 * @brief    Sets the option named @p optionName bearing the value
 *             @p value for the HTTP_HANDLE @p handle.
 *
 * @param    handle          The handle to the HTTP connection created via
 *                         ::HTTPAPI_CreateConnection.
 * @param    optionName    A @c NULL terminated string representing the name
 *                         of the option.
 * @param    value          A pointer to the value for the option.
 *
 * @return    @c HTTPAPI_OK if initialization is successful or an error
 *             code in case it fails.
 */
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, const char*, optionName, const void*, value);

/**
 * @deprecated Applications should not directly invoke this function.  They should use httpapiex.h instead.
 *
 * @brief    Clones the option named @p optionName bearing the value @p value
 *             into the pointer @p savedValue.
 *
 * @param    optionName    A @c NULL terminated string representing the name of
 *                         the option
 * @param    value          A pointer to the value of the option.
 * @param    savedValue    This pointer receives the copy of the value of the
 *                         option. The copy needs to be free-able.
 *
 * @return    @c HTTPAPI_OK if initialization is successful or an error
 *             code in case it fails.
 */
MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue);

#ifdef __cplusplus
}
#endif

#endif /* HTTPAPI_H */