httpapi.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 httpapi.h
00005  *    @brief     This module implements the standard HTTP API used by the C IoT client
00006  *             library.
00007  *
00008  *    @details For example, on the Windows platform the HTTP API code uses
00009  *             WinHTTP and for Linux it uses curl and so forth. HTTPAPI must support
00010  *             HTTPs (HTTP+SSL).
00011  */
00012 
00013 #ifndef HTTPAPI_H
00014 #define HTTPAPI_H
00015 
00016 #include "azure_c_shared_utility/httpheaders.h"
00017 #include "azure_c_shared_utility/macro_utils.h"
00018 #include "azure_c_shared_utility/buffer_.h"
00019 #include "azure_c_shared_utility/umock_c_prod.h"
00020 
00021 #ifdef __cplusplus
00022 #include <cstddef>
00023 extern "C" {
00024 #else
00025 #include <stddef.h>
00026 #endif
00027 
00028 typedef struct HTTP_HANDLE_DATA_TAG* HTTP_HANDLE;
00029 
00030 #define AMBIGUOUS_STATUS_CODE           (300)
00031 
00032 #define HTTPAPI_RESULT_VALUES                \
00033 HTTPAPI_OK,                                  \
00034 HTTPAPI_INVALID_ARG,                         \
00035 HTTPAPI_ERROR,                               \
00036 HTTPAPI_OPEN_REQUEST_FAILED,                 \
00037 HTTPAPI_SET_OPTION_FAILED,                   \
00038 HTTPAPI_SEND_REQUEST_FAILED,                 \
00039 HTTPAPI_RECEIVE_RESPONSE_FAILED,             \
00040 HTTPAPI_QUERY_HEADERS_FAILED,                \
00041 HTTPAPI_QUERY_DATA_AVAILABLE_FAILED,         \
00042 HTTPAPI_READ_DATA_FAILED,                    \
00043 HTTPAPI_ALREADY_INIT,                        \
00044 HTTPAPI_NOT_INIT,                            \
00045 HTTPAPI_HTTP_HEADERS_FAILED,                 \
00046 HTTPAPI_STRING_PROCESSING_ERROR,             \
00047 HTTPAPI_ALLOC_FAILED,                        \
00048 HTTPAPI_INIT_FAILED,                         \
00049 HTTPAPI_INSUFFICIENT_RESPONSE_BUFFER,        \
00050 HTTPAPI_SET_X509_FAILURE,                    \
00051 HTTPAPI_SET_TIMEOUTS_FAILED                  \
00052 
00053 /** @brief Enumeration specifying the possible return values for the APIs in
00054  *           this module.
00055  */
00056 DEFINE_ENUM(HTTPAPI_RESULT, HTTPAPI_RESULT_VALUES);
00057 
00058 #define HTTPAPI_REQUEST_TYPE_VALUES\
00059     HTTPAPI_REQUEST_GET,            \
00060     HTTPAPI_REQUEST_POST,           \
00061     HTTPAPI_REQUEST_PUT,            \
00062     HTTPAPI_REQUEST_DELETE,         \
00063     HTTPAPI_REQUEST_PATCH,          \
00064     HTTPAPI_REQUEST_HEAD            \
00065 
00066 
00067 /** @brief Enumeration specifying the HTTP request verbs accepted by
00068  *    the HTTPAPI module.
00069  */
00070 DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES);
00071 
00072 #define MAX_HOSTNAME_LEN        65
00073 #define MAX_USERNAME_LEN        65
00074 #define MAX_PASSWORD_LEN        65
00075 
00076 /**
00077  * @brief    Global initialization for the HTTP API component.
00078  *
00079  *            Platform specific implementations are expected to initialize
00080  *            the underlying HTTP API stacks.
00081  *
00082  * @return    @c HTTPAPI_OK if initialization is successful or an error
00083  *             code in case it fails.
00084  */
00085 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_Init);
00086 
00087 /** @brief    Free resources allocated in ::HTTPAPI_Init. */
00088 MOCKABLE_FUNCTION(, void, HTTPAPI_Deinit);
00089 
00090 /**
00091  * @brief    Creates an HTTPS connection to the host specified by the @p
00092  *             hostName parameter.
00093  *
00094  * @param    hostName    Name of the host.
00095  *
00096  *            This function returns a handle to the newly created connection.
00097  *            You can use the handle in subsequent calls to execute specific
00098  *            HTTP calls using ::HTTPAPI_ExecuteRequest.
00099  *
00100  * @return    A @c HTTP_HANDLE to the newly created connection or @c NULL in
00101  *             case an error occurs.
00102  */
00103 MOCKABLE_FUNCTION(, HTTP_HANDLE, HTTPAPI_CreateConnection, const char*, hostName);
00104 
00105 /**
00106  * @brief    Closes a connection created with ::HTTPAPI_CreateConnection.
00107  *
00108  * @param    handle    The handle to the HTTP connection created via ::HTTPAPI_CreateConnection.
00109  *
00110  *             All resources allocated by ::HTTPAPI_CreateConnection should be
00111  *             freed in ::HTTPAPI_CloseConnection.
00112  */
00113 MOCKABLE_FUNCTION(, void, HTTPAPI_CloseConnection, HTTP_HANDLE, handle);
00114 
00115 /**
00116  * @brief    Sends the HTTP request to the host and handles the response for
00117  *             the HTTP call.
00118  *
00119  * @param    handle                     The handle to the HTTP connection created
00120  *                                     via ::HTTPAPI_CreateConnection.
00121  * @param    requestType                 Specifies which HTTP method is used (GET,
00122  *                                     POST, DELETE, PUT, PATCH).
00123  * @param    relativePath             Specifies the relative path of the URL
00124  *                                     excluding the host name.
00125  * @param    httpHeadersHandle         Specifies a set of HTTP headers (name-value
00126  *                                     pairs) to be added to the
00127  *                                     HTTP request. The @p httpHeadersHandle
00128  *                                     handle can be created and setup with
00129  *                                     the proper name-value pairs by using the
00130  *                                     HTTPHeaders APIs available in @c
00131  *                                     HTTPHeaders.h.
00132  * @param    content                     Specifies a pointer to the request body.
00133  *                                     This value is optional and can be @c NULL.
00134  * @param    contentLength             Specifies the request body size (this is
00135  *                                     typically added into the HTTP headers as
00136  *                                     the Content-Length header). This value is
00137  *                                     optional and can be 0.
00138  * @param   statusCode               This is an out parameter, where
00139  *                                     ::HTTPAPI_ExecuteRequest returns the status
00140  *                                     code from the HTTP response (200, 201, 400,
00141  *                                     401, etc.)
00142  * @param    responseHeadersHandle    This is an HTTP headers handle to which
00143  *                                     ::HTTPAPI_ExecuteRequest must add all the
00144  *                                     HTTP response headers so that the caller of
00145  *                                     ::HTTPAPI_ExecuteRequest can inspect them.
00146  *                                     You can manipulate @p responseHeadersHandle
00147  *                                     by using the HTTPHeaders APIs available in
00148  *                                     @c HTTPHeaders.h
00149  * @param    responseContent             This is a buffer that must be filled by
00150  *                                     ::HTTPAPI_ExecuteRequest with the contents
00151  *                                     of the HTTP response body. The buffer size
00152  *                                     must be increased by the
00153  *                                     ::HTTPAPI_ExecuteRequest implementation in
00154  *                                     order to fit the response body.
00155  *                                     ::HTTPAPI_ExecuteRequest must also handle
00156  *                                     chunked transfer encoding for HTTP responses.
00157  *                                     To manipulate the @p responseContent buffer,
00158  *                                     use the APIs available in @c Strings.h.
00159  *
00160  * @return    @c HTTPAPI_OK if the API call is successful or an error
00161  *             code in case it fails.
00162  */
00163 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_ExecuteRequest, HTTP_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath,
00164                                              HTTP_HEADERS_HANDLE, httpHeadersHandle, const unsigned char*, content,
00165                                              size_t, contentLength, unsigned int*, statusCode,
00166                                              HTTP_HEADERS_HANDLE, responseHeadersHandle, BUFFER_HANDLE, responseContent);
00167 
00168 /**
00169  * @brief    Sets the option named @p optionName bearing the value
00170  *             @p value for the HTTP_HANDLE @p handle.
00171  *
00172  * @param    handle          The handle to the HTTP connection created via
00173  *                         ::HTTPAPI_CreateConnection.
00174  * @param    optionName    A @c NULL terminated string representing the name
00175  *                         of the option.
00176  * @param    value          A pointer to the value for the option.
00177  *
00178  * @return    @c HTTPAPI_OK if initialization is successful or an error
00179  *             code in case it fails.
00180  */
00181 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, const char*, optionName, const void*, value);
00182 
00183 /**
00184  * @brief    Clones the option named @p optionName bearing the value @p value
00185  *             into the pointer @p savedValue.
00186  *
00187  * @param    optionName    A @c NULL terminated string representing the name of
00188  *                         the option
00189  * @param    value          A pointer to the value of the option.
00190  * @param    savedValue    This pointer receives the copy of the value of the
00191  *                         option. The copy needs to be free-able.
00192  *
00193  * @return    @c HTTPAPI_OK if initialization is successful or an error
00194  *             code in case it fails.
00195  */
00196 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue);
00197 
00198 #ifdef __cplusplus
00199 }
00200 #endif
00201 
00202 #endif /* HTTPAPI_H */