HttpHeaderFields.h
Go to the documentation of this file.
1 /****
2  * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
3  * Created 2015 by Skurydin Alexey
4  * http://github.com/SmingHub/Sming
5  * All files of the Sming Core are provided under the LGPL v3 license.
6  *
7  * HttpHeaderFields.h - Standard HTTP header field definitions
8  *
9  * @author: 2018 - Mikee47 <mike@sillyhouse.net>
10  *
11  ****/
12 
13 #pragma once
14 
15 #include "Data/CStringArray.h"
16 #include "WString.h"
17 #include <Data/BitSet.h>
18 
19 /*
20  * Common HTTP header field names. Enumerating these simplifies matching
21  * and generating headers. The strings themselves are stored in flash to
22  * save RAM.
23  *
24  * According to RFC 2616: 4.2, field names are case-insensitive.
25  *
26  * A brief description of each header field is given for information purposes.
27  * For details see https://www.iana.org/assignments/message-headers/message-headers.xhtml
28  *
29  * Entries are formatted thus: XX(tag, str, flags, comment)
30  * tag: Identifier used in code (without HTTP_HEADER_ prefix)
31  * str: String used in HTTP protocol
32  * flags: Additional flags (see HttpHeaderFields::Flag)
33  * comment: Further details
34  */
35 #define HTTP_HEADER_FIELDNAME_MAP(XX) \
36  XX(ACCEPT, "Accept", 0, "Limit acceptable response types") \
37  XX(ACCEPT_ENCODING, "Accept-Encoding", 0, "Limit acceptable content encoding types") \
38  XX(ACCESS_CONTROL_ALLOW_ORIGIN, "Access-Control-Allow-Origin", 0, "") \
39  XX(AUTHORIZATION, "Authorization", 0, "Basic user agent authentication") \
40  XX(CC, "Cc", 0, "email field") \
41  XX(CONNECTION, "Connection", 0, "Indicates sender's desired control options") \
42  XX(CONTENT_DISPOSITION, "Content-Disposition", 0, "Additional information about how to process response payload") \
43  XX(CONTENT_ENCODING, "Content-Encoding", 0, "Applied encodings in addition to content type") \
44  XX(CONTENT_LENGTH, "Content-Length", 0, "Anticipated size for payload when not using transfer encoding") \
45  XX(CONTENT_TYPE, "Content-Type", 0, \
46  "Payload media type indicating both data format and intended manner of processing by recipient") \
47  XX(CONTENT_TRANSFER_ENCODING, "Content-Transfer-Encoding", 0, "Coding method used in a MIME message body part") \
48  XX(CACHE_CONTROL, "Cache-Control", 0, "Directives for caches along the request/response chain") \
49  XX(DATE, "Date", 0, "Message originating date/time") \
50  XX(EXPECT, "Expect", 0, "Behaviours to be supported by the server in order to properly handle this request.") \
51  XX(ETAG, "ETag", 0, \
52  "Validates resource, such as a file, so recipient can confirm whether it has changed - generally more " \
53  "reliable than Date") \
54  XX(FROM, "From", 0, "email address of human user who controls the requesting user agent") \
55  XX(HOST, "Host", 0, \
56  "Request host and port information for target URI; allows server to service requests for multiple hosts on a " \
57  "single IP address") \
58  XX(IF_MATCH, "If-Match", 0, \
59  "Precondition check using ETag to avoid accidental overwrites when servicing multiple user requests. Ensures " \
60  "resource entity tag matches before proceeding.") \
61  XX(IF_MODIFIED_SINCE, "If-Modified-Since", 0, "Precondition check using Date") \
62  XX(LAST_MODIFIED, "Last-Modified", 0, "Server timestamp indicating date and time resource was last modified") \
63  XX(LOCATION, "Location", 0, "Used in redirect responses, amongst other places") \
64  XX(SEC_WEBSOCKET_ACCEPT, "Sec-WebSocket-Accept", 0, "Server response to opening Websocket handshake") \
65  XX(SEC_WEBSOCKET_VERSION, "Sec-WebSocket-Version", 0, \
66  "Websocket opening request indicates acceptable protocol version. Can appear more than once.") \
67  XX(SEC_WEBSOCKET_KEY, "Sec-WebSocket-Key", 0, "Websocket opening request validation key") \
68  XX(SEC_WEBSOCKET_PROTOCOL, "Sec-WebSocket-Protocol", 0, \
69  "Websocket opening request indicates supported protocol(s), response contains negotiated protocol(s)") \
70  XX(SERVER, "Server", 0, "Identifies software handling requests") \
71  XX(SET_COOKIE, "Set-Cookie", Flag::Multi, \
72  "Server may pass name/value pairs and associated metadata to user agent (client)") \
73  XX(SUBJECT, "Subject", 0, "email subject line") \
74  XX(TO, "To", 0, "email intended recipient address") \
75  XX(TRANSFER_ENCODING, "Transfer-Encoding", 0, "e.g. Chunked, compress, deflate, gzip") \
76  XX(UPGRADE, "Upgrade", 0, \
77  "Used to transition from HTTP to some other protocol on the same connection. e.g. Websocket") \
78  XX(USER_AGENT, "User-Agent", 0, "Information about the user agent originating the request") \
79  XX(WWW_AUTHENTICATE, "WWW-Authenticate", Flag::Multi, \
80  "Indicates HTTP authentication scheme(s) and applicable parameters") \
81  XX(PROXY_AUTHENTICATE, "Proxy-Authenticate", Flag::Multi, \
82  "Indicates proxy authentication scheme(s) and applicable parameters")
83 
84 enum class HttpHeaderFieldName : uint8_t {
85  UNKNOWN = 0,
86 #define XX(tag, str, flags, comment) tag,
88 #undef XX
89  CUSTOM // First custom header tag value
90 };
91 
92 #define XX(tag, str, flags, comment) constexpr HttpHeaderFieldName HTTP_HEADER_##tag = HttpHeaderFieldName::tag;
93 XX(UNKNOWN, "", 0, "")
95 XX(CUSTOM, "", 0, "")
96 #undef XX
97 
99 {
100 public:
104  enum class Flag {
105  Multi,
106  };
108 
114 
116 
122  static String toString(const String& name, const String& value);
123 
124  String toString(HttpHeaderFieldName name, const String& value) const;
125 
132 
139  {
140  auto field = fromString(name);
141  if(field == HTTP_HEADER_UNKNOWN) {
142  field = static_cast<HttpHeaderFieldName>(unsigned(HTTP_HEADER_CUSTOM) + customFieldNames.count());
143  customFieldNames.add(name);
144  }
145  return field;
146  }
147 
148  void clear()
149  {
150  customFieldNames.clear();
151  }
152 
153 private:
158  HttpHeaderFieldName findCustomFieldName(const String& name) const;
159 
160  CStringArray customFieldNames;
161 };
#define XX(tag, str, flags, comment)
Definition: HttpHeaderFields.h:92
#define HTTP_HEADER_FIELDNAME_MAP(XX)
Definition: HttpHeaderFields.h:35
HttpHeaderFieldName
Definition: HttpHeaderFields.h:84
XX(tag, str, flags, comment)
Class to manage a double null-terminated list of strings, such as "one\0two\0three\0".
Definition: CStringArray.h:22
bool add(const char *str, int length=-1)
Append a new string (or array of strings) to the end of the array.
unsigned count() const
Get quantity of strings in array.
void clear()
Empty the array.
Definition: CStringArray.h:238
Definition: HttpHeaderFields.h:99
void clear()
Definition: HttpHeaderFields.h:148
HttpHeaderFieldName fromString(const String &name) const
Find the enumerated value for the given field name string.
Flag
Flag values providing additional information about header fields.
Definition: HttpHeaderFields.h:104
@ Multi
Field may have multiple values.
String toString(HttpHeaderFieldName name, const String &value) const
static String toString(const String &name, const String &value)
Produce a string for output in the HTTP header, with line ending.
HttpHeaderFieldName findOrCreate(const String &name)
Find the enumerated value for the given field name string, create a custom entry if not found.
Definition: HttpHeaderFields.h:138
Flags getFlags(HttpHeaderFieldName name) const
Get flags (if any) for given header field.
String toString(HttpHeaderFieldName name) const
The String class.
Definition: WString.h:137