Azure IoT / azure_c_shared_utility

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:   STM32F746_iothub_client_sample_mqtt f767zi_mqtt iothub_client_sample_amqp iothub_client_sample_http ... more

azure_c_shared_utility/httpheaders.h@0:fa2de1b79154, 2016-04-08 (annotated)

Committer:
Azure.IoT Build
Date:
Fri Apr 08 12:01:36 2016 -0700
Revision:
0:fa2de1b79154
Child:
2:20b88da3e604
1.0.4

Who changed what in which revision?

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