[457] | 1 | // Copyright (c) Microsoft. All rights reserved.
|
---|
| 2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information.
|
---|
| 3 |
|
---|
| 4 | /** @file httpheaders.h
|
---|
| 5 | * @brief This is a utility module that handles HTTP message-headers.
|
---|
| 6 | *
|
---|
| 7 | * @details An application would use ::HTTPHeaders_Alloc to create a new set of HTTP headers.
|
---|
| 8 | * After getting the handle, the application would build in several headers by
|
---|
| 9 | * consecutive calls to ::HTTPHeaders_AddHeaderNameValuePair. When the headers are
|
---|
| 10 | * constructed, the application can retrieve the stored data by calling one of the
|
---|
| 11 | * following functions:
|
---|
| 12 | * - ::HTTPHeaders_FindHeaderValue - when the name of the header is known and it
|
---|
| 13 | * wants to know the value of that header
|
---|
| 14 | * - ::HTTPHeaders_GetHeaderCount - when the application needs to know the count
|
---|
| 15 | * of all the headers
|
---|
| 16 | * - ::HTTPHeaders_GetHeader - when the application needs to retrieve the
|
---|
| 17 | * <code>name + ": " + value</code> string based on an index.
|
---|
| 18 | */
|
---|
| 19 |
|
---|
| 20 | #ifndef HTTPHEADERS_H
|
---|
| 21 | #define HTTPHEADERS_H
|
---|
| 22 |
|
---|
| 23 | #ifdef __cplusplus
|
---|
| 24 | #include <cstddef>
|
---|
| 25 | #else
|
---|
| 26 | #include <stddef.h>
|
---|
| 27 | #endif
|
---|
| 28 |
|
---|
| 29 | #include "azure_macro_utils/macro_utils.h"
|
---|
| 30 | #include "umock_c/umock_c_prod.h"
|
---|
| 31 |
|
---|
| 32 | #ifdef __cplusplus
|
---|
| 33 | extern "C" {
|
---|
| 34 | #endif
|
---|
| 35 |
|
---|
| 36 | /*Codes_SRS_HTTP_HEADERS_99_001:[ HttpHeaders shall have the following interface]*/
|
---|
| 37 |
|
---|
| 38 | #define HTTP_HEADERS_RESULT_VALUES \
|
---|
| 39 | HTTP_HEADERS_OK, \
|
---|
| 40 | HTTP_HEADERS_INVALID_ARG, \
|
---|
| 41 | HTTP_HEADERS_ALLOC_FAILED, \
|
---|
| 42 | HTTP_HEADERS_INSUFFICIENT_BUFFER, \
|
---|
| 43 | HTTP_HEADERS_ERROR \
|
---|
| 44 |
|
---|
| 45 | /** @brief Enumeration specifying the status of calls to various APIs in this module.
|
---|
| 46 | */
|
---|
| 47 | MU_DEFINE_ENUM(HTTP_HEADERS_RESULT, HTTP_HEADERS_RESULT_VALUES);
|
---|
| 48 | typedef struct HTTP_HEADERS_HANDLE_DATA_TAG* HTTP_HEADERS_HANDLE;
|
---|
| 49 |
|
---|
| 50 | /**
|
---|
| 51 | * @brief Produces a @c HTTP_HANDLE that can later be used in subsequent calls to the module.
|
---|
| 52 | *
|
---|
| 53 | * This function returns @c NULL in case an error occurs. After successful execution
|
---|
| 54 | * ::HTTPHeaders_GetHeaderCount will report @c 0 existing headers.
|
---|
| 55 | *
|
---|
| 56 | * @return A HTTP_HEADERS_HANDLE representing the newly created collection of HTTP headers.
|
---|
| 57 | */
|
---|
| 58 | MOCKABLE_FUNCTION(, HTTP_HEADERS_HANDLE, HTTPHeaders_Alloc);
|
---|
| 59 |
|
---|
| 60 | /**
|
---|
| 61 | * @brief De-allocates the data structures allocated by previous API calls to the same handle.
|
---|
| 62 | *
|
---|
| 63 | * @param httpHeadersHandle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 64 | */
|
---|
| 65 | MOCKABLE_FUNCTION(, void, HTTPHeaders_Free, HTTP_HEADERS_HANDLE, httpHeadersHandle);
|
---|
| 66 |
|
---|
| 67 | /**
|
---|
| 68 | * @brief Adds a header record from the @p name and @p value parameters.
|
---|
| 69 | *
|
---|
| 70 | * @param httpHeadersHandle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 71 | * @param name The name of the HTTP header to add. It is invalid for
|
---|
| 72 | * the name to include the ':' character or character codes
|
---|
| 73 | * outside the range 33-126.
|
---|
| 74 | * @param value The value to be assigned to the header.
|
---|
| 75 | *
|
---|
| 76 | * The function stores the @c name:value pair in such a way that when later
|
---|
| 77 | * retrieved by a call to ::HTTPHeaders_GetHeader it will return a string
|
---|
| 78 | * that is @c strcmp equal to @c name+": "+value. If the name already exists
|
---|
| 79 | * in the collection of headers, the function concatenates the new value
|
---|
| 80 | * after the existing value, separated by a comma and a space as in:
|
---|
| 81 | * <code>old-value+", "+new-value</code>.
|
---|
| 82 | *
|
---|
| 83 | * @return Returns @c HTTP_HEADERS_OK when execution is successful or an error code from
|
---|
| 84 | * the ::HTTPAPIEX_RESULT enum.
|
---|
| 85 | */
|
---|
| 86 | MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_AddHeaderNameValuePair, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char*, name, const char*, value);
|
---|
| 87 |
|
---|
| 88 | /**
|
---|
| 89 | * @brief This API performs exactly the same as ::HTTPHeaders_AddHeaderNameValuePair
|
---|
| 90 | * except that if the header name already exists then the already existing value
|
---|
| 91 | * will be replaced as opposed to being concatenated to.
|
---|
| 92 | *
|
---|
| 93 | * @param httpHeadersHandle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 94 | * @param name The name of the HTTP header to add/replace. It is invalid for
|
---|
| 95 | * the name to include the ':' character or character codes
|
---|
| 96 | * outside the range 33-126.
|
---|
| 97 | * @param value The value to be assigned to the header.
|
---|
| 98 | *
|
---|
| 99 | * @return Returns @c HTTP_HEADERS_OK when execution is successful or an error code from
|
---|
| 100 | * the ::HTTPAPIEX_RESULT enum.
|
---|
| 101 | */
|
---|
| 102 | MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_ReplaceHeaderNameValuePair, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char*, name, const char*, value);
|
---|
| 103 |
|
---|
| 104 | /**
|
---|
| 105 | * @brief Retrieves the value for a previously stored name.
|
---|
| 106 | *
|
---|
| 107 | * @param httpHeadersHandle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 108 | * @param name The name of the HTTP header to find.
|
---|
| 109 | *
|
---|
| 110 | * @return The return value points to a string that shall be @c strcmp equal
|
---|
| 111 | * to the original stored string.
|
---|
| 112 | */
|
---|
| 113 | MOCKABLE_FUNCTION(, const char*, HTTPHeaders_FindHeaderValue, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char*, name);
|
---|
| 114 |
|
---|
| 115 | /**
|
---|
| 116 | * @brief This API retrieves the number of stored headers.
|
---|
| 117 | *
|
---|
| 118 | * @param httpHeadersHandle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 119 | * @param headersCount If non-null, the API writes the number of
|
---|
| 120 | * into the memory pointed at by this parameter.
|
---|
| 121 | *
|
---|
| 122 | * @return Returns @c HTTP_HEADERS_OK when execution is successful or
|
---|
| 123 | * @c HTTP_HEADERS_ERROR when an error occurs.
|
---|
| 124 | */
|
---|
| 125 | MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_GetHeaderCount, HTTP_HEADERS_HANDLE, httpHeadersHandle, size_t*, headersCount);
|
---|
| 126 |
|
---|
| 127 | /**
|
---|
| 128 | * @brief This API retrieves the string name+": "+value for the header
|
---|
| 129 | * element at the given @p index.
|
---|
| 130 | *
|
---|
| 131 | * @param handle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 132 | * @param index Zero-based index of the item in the
|
---|
| 133 | * headers collection.
|
---|
| 134 | * @param destination If non-null, the header value is written into a
|
---|
| 135 | * new string a pointer to which is written into this
|
---|
| 136 | * parameters. It is the caller's responsibility to free
|
---|
| 137 | * this memory.
|
---|
| 138 | *
|
---|
| 139 | * @return Returns @c HTTP_HEADERS_OK when execution is successful or
|
---|
| 140 | * @c HTTP_HEADERS_ERROR when an error occurs.
|
---|
| 141 | */
|
---|
| 142 | MOCKABLE_FUNCTION(, HTTP_HEADERS_RESULT, HTTPHeaders_GetHeader, HTTP_HEADERS_HANDLE, handle, size_t, index, char**, destination);
|
---|
| 143 |
|
---|
| 144 | /**
|
---|
| 145 | * @brief This API produces a clone of the @p handle parameter.
|
---|
| 146 | *
|
---|
| 147 | * @param handle A valid @c HTTP_HEADERS_HANDLE value.
|
---|
| 148 | *
|
---|
| 149 | * If @p handle is not @c NULL this function clones the content
|
---|
| 150 | * of the handle to a new handle and returns it.
|
---|
| 151 | *
|
---|
| 152 | * @return A @c HTTP_HEADERS_HANDLE containing a cloned copy of the
|
---|
| 153 | * contents of @p handle.
|
---|
| 154 | */
|
---|
| 155 | MOCKABLE_FUNCTION(, HTTP_HEADERS_HANDLE, HTTPHeaders_Clone, HTTP_HEADERS_HANDLE, handle);
|
---|
| 156 |
|
---|
| 157 | #ifdef __cplusplus
|
---|
| 158 | }
|
---|
| 159 | #endif
|
---|
| 160 |
|
---|
| 161 | #endif /* HTTPHEADERS_H */
|
---|