httpheaders.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 httpheaders.h    
00005 *   @brief This is a utility module that handles HTTP message-headers.
00006 *
00007 *   @details An application would use ::HTTPHeaders_Alloc to create a new set of HTTP headers.
00008 *            After getting the handle, the application would build in several headers by
00009 *            consecutive calls to ::HTTPHeaders_AddHeaderNameValuePair. When the headers are
00010 *            constructed, the application can retrieve the stored data by calling one of the
00011 *            following functions:
00012 *               - ::HTTPHeaders_FindHeaderValue - when the name of the header is known and it  
00013 *                 wants to know the value of that header  
00014 *               - ::HTTPHeaders_GetHeaderCount - when the application needs to know the count  
00015 *                 of all the headers  
00016 *               - ::HTTPHeaders_GetHeader - when the application needs to retrieve the
00017 *                 <code>name + ": " + value</code> string based on an index.
00018 */
00019 
00020 #ifndef HTTPHEADERS_H
00021 #define HTTPHEADERS_H
00022 
00023 #include "azure_c_shared_utility/macro_utils.h"
00024 #include "azure_c_shared_utility/umock_c_prod.h"
00025 
00026 #ifdef __cplusplus
00027 #include <cstddef>
00028 extern "C" {
00029 #else
00030 #include <stddef.h>
00031 #endif
00032 
00033 /*Codes_SRS_HTTP_HEADERS_99_001:[ HttpHeaders shall have the following interface]*/
00034 
00035 #define HTTP_HEADERS_RESULT_VALUES \
00036 HTTP_HEADERS_OK,                  \
00037 HTTP_HEADERS_INVALID_ARG,         \
00038 HTTP_HEADERS_ALLOC_FAILED,        \
00039 HTTP_HEADERS_INSUFFICIENT_BUFFER, \
00040 HTTP_HEADERS_ERROR                \
00041 
00042 /** @brief Enumeration specifying the status of calls to various APIs in this module.
00043 */
00044 DEFINE_ENUM(HTTP_HEADERS_RESULT, HTTP_HEADERS_RESULT_VALUES);
00045 typedef struct HTTP_HEADERS_HANDLE_DATA_TAG* HTTP_HEADERS_HANDLE;
00046 
00047 /**
00048  * @brief   Produces a @c HTTP_HANDLE that can later be used in subsequent calls to the module.
00049  *          
00050  *          This function returns @c NULL in case an error occurs. After successful execution
00051  *          ::HTTPHeaders_GetHeaderCount will report @c 0 existing headers.
00052  *
00053  * @return  A HTTP_HEADERS_HANDLE representing the newly created collection of HTTP headers.
00054  */
00055 MOCKABLE_FUNCTION(, HTTP_HEADERS_HANDLE, HTTPHeaders_Alloc);
00056 
00057 /**
00058  * @brief   De-allocates the data structures allocated by previous API calls to the same handle.
00059  *
00060  * @param   httpHeadersHandle   A valid @c HTTP_HEADERS_HANDLE value.
00061  */
00062 MOCKABLE_FUNCTION(, void, HTTPHeaders_Free, HTTP_HEADERS_HANDLE, httpHeadersHandle);
00063 
00064 /**
00065  * @brief   Adds a header record from the @p name and @p value parameters.
00066  *
00067  * @param   httpHeadersHandle   A valid @c HTTP_HEADERS_HANDLE value.
00068  * @param   name                The name of the HTTP header to add. It is invalid for
00069  *                              the name to include the ':' character or character codes
00070  *                              outside the range 33-126.
00071  * @param   value               The value to be assigned to the header.
00072  *
00073  *          The function stores the @c name:value pair in such a way that when later
00074  *          retrieved by a call to ::HTTPHeaders_GetHeader it will return a string
00075  *          that is @c strcmp equal to @c name+": "+value. If the name already exists
00076  *          in the collection of headers, the function concatenates the new value
00077  *          after the existing value, separated by a comma and a space as in:
00078  *          <code>old-value+", "+new-value</code>.
00079  * 
00080  * @return  Returns @c HTTP_HEADERS_OK when execution is successful or an error code from
00081  *          the ::HTTPAPIEX_RESULT enum.
00082  */
00083 MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_AddHeaderNameValuePair, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char*, name, const char*, value);
00084 
00085 /**
00086  * @brief   This API performs exactly the same as ::HTTPHeaders_AddHeaderNameValuePair
00087  *          except that if the header name already exists then the already existing value
00088  *          will be replaced as opposed to being concatenated to.
00089  *
00090  * @param   httpHeadersHandle   A valid @c HTTP_HEADERS_HANDLE value.
00091  * @param   name                The name of the HTTP header to add/replace. It is invalid for
00092  *                              the name to include the ':' character or character codes
00093  *                              outside the range 33-126.
00094  * @param   value               The value to be assigned to the header.
00095  *
00096  * @return  Returns @c HTTP_HEADERS_OK when execution is successful or an error code from
00097  *          the ::HTTPAPIEX_RESULT enum.
00098  */
00099 MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_ReplaceHeaderNameValuePair, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char*, name, const char*, value);
00100 
00101 /**
00102  * @brief   Retrieves the value for a previously stored name.
00103  *
00104  * @param   httpHeadersHandle   A valid @c HTTP_HEADERS_HANDLE value.
00105  * @param   name                The name of the HTTP header to find.
00106  *
00107  * @return  The return value points to a string that shall be @c strcmp equal
00108  *          to the original stored string.
00109  */
00110 MOCKABLE_FUNCTION(, const char*, HTTPHeaders_FindHeaderValue, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char*, name);
00111 
00112 /**
00113  * @brief   This API retrieves the number of stored headers.
00114  *
00115  * @param   httpHeadersHandle   A valid @c HTTP_HEADERS_HANDLE value.
00116  * @param   headersCount        If non-null, the API writes the number of
00117  *                              into the memory pointed at by this parameter.
00118  *
00119  * @return  Returns @c HTTP_HEADERS_OK when execution is successful or
00120  *          @c HTTP_HEADERS_ERROR when an error occurs.
00121  */
00122 MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_GetHeaderCount, HTTP_HEADERS_HANDLE, httpHeadersHandle, size_t*, headersCount);
00123 
00124 /**
00125  * @brief   This API retrieves the string name+": "+value for the header
00126  *          element at the given @p index.
00127  *
00128  * @param   handle          A valid @c HTTP_HEADERS_HANDLE value.
00129  * @param   index           Zero-based index of the item in the
00130  *                          headers collection.
00131  * @param   destination     If non-null, the header value is written into a
00132  *                          new string a pointer to which is written into this
00133  *                          parameters. It is the caller's responsibility to free
00134  *                          this memory.
00135  *
00136  * @return  Returns @c HTTP_HEADERS_OK when execution is successful or
00137  *          @c HTTP_HEADERS_ERROR when an error occurs.
00138  */
00139 MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_GetHeader, HTTP_HEADERS_HANDLE, handle, size_t, index, char**, destination);
00140 
00141 /**
00142  * @brief   This API produces a clone of the @p handle parameter.
00143  *
00144  * @param   handle  A valid @c HTTP_HEADERS_HANDLE value.
00145  *
00146  *          If @p handle is not @c NULL this function clones the content
00147  *          of the handle to a new handle and returns it.
00148  *          
00149  * @return  A @c HTTP_HEADERS_HANDLE containing a cloned copy of the
00150  *          contents of @p handle.
00151  */
00152 MOCKABLE_FUNCTION(, HTTP_HEADERS_HANDLE, HTTPHeaders_Clone, HTTP_HEADERS_HANDLE, handle);
00153 
00154 #ifdef __cplusplus
00155 }
00156 #endif 
00157 
00158 #endif /* HTTPHEADERS_H */