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 */
|
---|