Xin Zhang / azure-iot-c-sdk-f767zi

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   samplemqtt

c-utility/inc/azure_c_shared_utility/httpheaders.h@0:f7f1f0d76dd6, 2018-08-23 (annotated)

Committer:
XinZhangMS
Date:
Thu Aug 23 06:52:14 2018 +0000
Revision:
0:f7f1f0d76dd6
azure-c-sdk for mbed os supporting NUCLEO_F767ZI

Who changed what in which revision?

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