source: azure_iot_hub_f767zi/trunk/azure_iot_sdk/c-utility/inc/azure_c_shared_utility/httpheaders.h@ 457

Last change on this file since 457 was 457, checked in by coas-nagasima, 4 years ago

ファイルを追加
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/x-chdr;charset=UTF-8
File size: 7.1 KB
Line 
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
33extern "C" {
34#endif
35
36/*Codes_SRS_HTTP_HEADERS_99_001:[ HttpHeaders shall have the following interface]*/
37
38#define HTTP_HEADERS_RESULT_VALUES \
39HTTP_HEADERS_OK, \
40HTTP_HEADERS_INVALID_ARG, \
41HTTP_HEADERS_ALLOC_FAILED, \
42HTTP_HEADERS_INSUFFICIENT_BUFFER, \
43HTTP_HEADERS_ERROR \
44
45/** @brief Enumeration specifying the status of calls to various APIs in this module.
46*/
47MU_DEFINE_ENUM(HTTP_HEADERS_RESULT, HTTP_HEADERS_RESULT_VALUES);
48typedef 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 */
58MOCKABLE_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 */
65MOCKABLE_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 */
86MOCKABLE_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 */
102MOCKABLE_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 */
113MOCKABLE_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 */
125MOCKABLE_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 */
142MOCKABLE_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 */
155MOCKABLE_FUNCTION(, HTTP_HEADERS_HANDLE, HTTPHeaders_Clone, HTTP_HEADERS_HANDLE, handle);
156
157#ifdef __cplusplus
158}
159#endif
160
161#endif /* HTTPHEADERS_H */
Note: See TracBrowser for help on using the repository browser.