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 
00065 /** @brief Enumeration specifying the HTTP request verbs accepted by
00066  *  the HTTPAPI module.
00067  */
00068 DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES);
00069 
00070 #define MAX_HOSTNAME_LEN        65
00071 
00072 /**
00073  * @brief   Global initialization for the HTTP API component.
00074  *
00075  *          Platform specific implementations are expected to initialize
00076  *          the underlying HTTP API stacks.
00077  * 
00078  * @return  @c HTTPAPI_OK if initialization is successful or an error
00079  *          code in case it fails.
00080  */
00081 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_Init);
00082 
00083 /** @brief  Free resources allocated in ::HTTPAPI_Init. */
00084 MOCKABLE_FUNCTION(, void, HTTPAPI_Deinit);
00085 
00086 /**
00087  * @brief   Creates an HTTPS connection to the host specified by the @p
00088  *          hostName parameter.
00089  *
00090  * @param   hostName    Name of the host.
00091  *
00092  *          This function returns a handle to the newly created connection.
00093  *          You can use the handle in subsequent calls to execute specific
00094  *          HTTP calls using ::HTTPAPI_ExecuteRequest.
00095  * 
00096  * @return  A @c HTTP_HANDLE to the newly created connection or @c NULL in
00097  *          case an error occurs.
00098  */
00099 MOCKABLE_FUNCTION(, HTTP_HANDLE, HTTPAPI_CreateConnection, const char*, hostName);
00100 
00101 /**
00102  * @brief   Closes a connection created with ::HTTPAPI_CreateConnection.
00103  *
00104  * @param   handle  The handle to the HTTP connection created via ::HTTPAPI_CreateConnection.
00105  *                  
00106  *          All resources allocated by ::HTTPAPI_CreateConnection should be
00107  *          freed in ::HTTPAPI_CloseConnection.
00108  */
00109 MOCKABLE_FUNCTION(, void, HTTPAPI_CloseConnection, HTTP_HANDLE, handle);
00110 
00111 /**
00112  * @brief   Sends the HTTP request to the host and handles the response for
00113  *          the HTTP call.
00114  *
00115  * @param   handle                  The handle to the HTTP connection created
00116  *                                  via ::HTTPAPI_CreateConnection.
00117  * @param   requestType             Specifies which HTTP method is used (GET,
00118  *                                  POST, DELETE, PUT, PATCH).
00119  * @param   relativePath            Specifies the relative path of the URL
00120  *                                  excluding the host name.
00121  * @param   httpHeadersHandle       Specifies a set of HTTP headers (name-value
00122  *                                  pairs) to be added to the
00123  *                                  HTTP request. The @p httpHeadersHandle
00124  *                                  handle can be created and setup with
00125  *                                  the proper name-value pairs by using the
00126  *                                  HTTPHeaders APIs available in @c
00127  *                                  HTTPHeaders.h.
00128  * @param   content                 Specifies a pointer to the request body.
00129  *                                  This value is optional and can be @c NULL.
00130  * @param   contentLength           Specifies the request body size (this is
00131  *                                  typically added into the HTTP headers as
00132  *                                  the Content-Length header). This value is
00133  *                                  optional and can be 0.
00134  * @param   statusCode              This is an out parameter, where
00135  *                                  ::HTTPAPI_ExecuteRequest returns the status
00136  *                                  code from the HTTP response (200, 201, 400,
00137  *                                  401, etc.)
00138  * @param   responseHeadersHandle   This is an HTTP headers handle to which
00139  *                                  ::HTTPAPI_ExecuteRequest must add all the
00140  *                                  HTTP response headers so that the caller of
00141  *                                  ::HTTPAPI_ExecuteRequest can inspect them.
00142  *                                  You can manipulate @p responseHeadersHandle
00143  *                                  by using the HTTPHeaders APIs available in
00144  *                                  @c HTTPHeaders.h
00145  * @param   responseContent         This is a buffer that must be filled by
00146  *                                  ::HTTPAPI_ExecuteRequest with the contents
00147  *                                  of the HTTP response body. The buffer size
00148  *                                  must be increased by the
00149  *                                  ::HTTPAPI_ExecuteRequest implementation in
00150  *                                  order to fit the response body.
00151  *                                  ::HTTPAPI_ExecuteRequest must also handle
00152  *                                  chunked transfer encoding for HTTP responses.
00153  *                                  To manipulate the @p responseContent buffer,
00154  *                                  use the APIs available in @c Strings.h.
00155  *
00156  * @return  @c HTTPAPI_OK if the API call is successful or an error
00157  *          code in case it fails.
00158  */
00159 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_ExecuteRequest, HTTP_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath,
00160                                              HTTP_HEADERS_HANDLE, httpHeadersHandle, const unsigned char*, content,
00161                                              size_t, contentLength, unsigned int*, statusCode,
00162                                              HTTP_HEADERS_HANDLE, responseHeadersHandle, BUFFER_HANDLE, responseContent);
00163 
00164 /**
00165  * @brief   Sets the option named @p optionName bearing the value
00166  *          @p value for the HTTP_HANDLE @p handle.
00167  *
00168  * @param   handle      The handle to the HTTP connection created via
00169  *                      ::HTTPAPI_CreateConnection.
00170  * @param   optionName  A @c NULL terminated string representing the name
00171  *                      of the option.
00172  * @param   value       A pointer to the value for the option.
00173  *
00174  * @return  @c HTTPAPI_OK if initialization is successful or an error
00175  *          code in case it fails.
00176  */
00177 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, const char*, optionName, const void*, value);
00178 
00179 /**
00180  * @brief   Clones the option named @p optionName bearing the value @p value
00181  *          into the pointer @p savedValue.
00182  *
00183  * @param   optionName  A @c NULL terminated string representing the name of
00184  *                      the option
00185  * @param   value       A pointer to the value of the option.
00186  * @param   savedValue  This pointer receives the copy of the value of the
00187  *                      option. The copy needs to be free-able.
00188  *
00189  * @return  @c HTTPAPI_OK if initialization is successful or an error
00190  *          code in case it fails.
00191  */
00192 MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue);
00193 
00194 #ifdef __cplusplus
00195 }
00196 #endif
00197 
00198 #endif /* HTTPAPI_H */