WPILibC++ 2024.3.2
HttpParser.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#ifndef WPINET_HTTPPARSER_H_
6#define WPINET_HTTPPARSER_H_
7
8#include <stdint.h>
9
10#include <string_view>
11
12#include <wpi/Signal.h>
13#include <wpi/SmallString.h>
14
15#include "wpinet/http_parser.h"
16
17namespace wpi {
18
19/**
20 * HTTP protocol parser. Performs incremental parsing with callbacks for each
21 * part of the HTTP protocol. As this is incremental, it's suitable for use
22 * with event based frameworks that provide arbitrary chunks of data.
23 */
25 public:
26 enum Type {
30 };
31
32 /**
33 * Returns the library version. Bits 16-23 contain the major version number,
34 * bits 8-15 the minor version number and bits 0-7 the patch level.
35 */
36 static uint32_t GetParserVersion();
37
38 /**
39 * Constructor.
40 * @param type Type of parser (request or response or both)
41 */
42 explicit HttpParser(Type type);
43
44 /**
45 * Reset the parser to initial state.
46 * This allows reusing the same parser object from request to request.
47 * @param type Type of parser (request or response or both)
48 */
50
51 /**
52 * Set the maximum accepted length for URLs, field names, and field values.
53 * The default is 1024.
54 * @param len maximum length
55 */
56 void SetMaxLength(size_t len) { m_maxLength = len; }
57
58 /**
59 * Executes the parser. An empty input is treated as EOF.
60 * @param in input data
61 * @return Trailing input data after the parse.
62 */
64 in.remove_prefix(
65 http_parser_execute(&m_parser, &m_settings, in.data(), in.size()));
66 return in;
67 }
68
69 /**
70 * Get HTTP major version.
71 */
72 unsigned int GetMajor() const { return m_parser.http_major; }
73
74 /**
75 * Get HTTP minor version.
76 */
77 unsigned int GetMinor() const { return m_parser.http_minor; }
78
79 /**
80 * Get HTTP status code. Valid only on responses. Valid in and after
81 * the OnStatus() callback has been called.
82 */
83 unsigned int GetStatusCode() const { return m_parser.status_code; }
84
85 /**
86 * Get HTTP method. Valid only on requests.
87 */
89 return static_cast<http_method>(m_parser.method);
90 }
91
92 /**
93 * Determine if an error occurred.
94 * @return False if no error.
95 */
96 bool HasError() const { return m_parser.http_errno != HPE_OK; }
97
98 /**
99 * Get error number.
100 */
102 return static_cast<http_errno>(m_parser.http_errno);
103 }
104
105 /**
106 * Abort the parse. Call this from a callback handler to indicate an error.
107 * This will result in GetError() returning one of the callback-related
108 * errors (e.g. HPE_CB_message_begin).
109 */
110 void Abort() { m_aborted = true; }
111
112 /**
113 * Determine if an upgrade header was present and the parser has exited
114 * because of that. Should be checked when Execute() returns in addition to
115 * checking GetError().
116 * @return True if upgrade header, false otherwise.
117 */
118 bool IsUpgrade() const { return m_parser.upgrade; }
119
120 /**
121 * If this returns false in the headersComplete or messageComplete
122 * callback, then this should be the last message on the connection.
123 * If you are the server, respond with the "Connection: close" header.
124 * If you are the client, close the connection.
125 */
126 bool ShouldKeepAlive() const { return http_should_keep_alive(&m_parser); }
127
128 /**
129 * Pause the parser.
130 * @param paused True to pause, false to unpause.
131 */
132 void Pause(bool paused) { http_parser_pause(&m_parser, paused); }
133
134 /**
135 * Checks if this is the final chunk of the body.
136 */
137 bool IsBodyFinal() const { return http_body_is_final(&m_parser); }
138
139 /**
140 * Get URL. Valid in and after the url callback has been called.
141 */
142 std::string_view GetUrl() const { return m_urlBuf.str(); }
143
144 /**
145 * Message begin callback.
146 */
148
149 /**
150 * URL callback.
151 *
152 * The parameter to the callback is the complete URL string.
153 */
155
156 /**
157 * Status callback.
158 *
159 * The parameter to the callback is the complete status string.
160 * GetStatusCode() can be used to get the numeric status code.
161 */
163
164 /**
165 * Header field callback.
166 *
167 * The parameters to the callback are the field name and field value.
168 */
170
171 /**
172 * Headers complete callback.
173 *
174 * The parameter to the callback is whether the connection should be kept
175 * alive. If this is false, then this should be the last message on the
176 * connection. If you are the server, respond with the "Connection: close"
177 * header. If you are the client, close the connection.
178 */
180
181 /**
182 * Body data callback.
183 *
184 * The parameters to the callback is the data chunk and whether this is the
185 * final chunk of data in the message. Note this callback will be called
186 * multiple times arbitrarily (e.g. it's possible that it may be called with
187 * just a few characters at a time).
188 */
190
191 /**
192 * Headers complete callback.
193 *
194 * The parameter to the callback is whether the connection should be kept
195 * alive. If this is false, then this should be the last message on the
196 * connection. If you are the server, respond with the "Connection: close"
197 * header. If you are the client, close the connection.
198 */
200
201 /**
202 * Chunk header callback.
203 *
204 * The parameter to the callback is the chunk size.
205 */
207
208 /**
209 * Chunk complete callback.
210 */
212
213 private:
214 http_parser m_parser;
215 http_parser_settings m_settings;
216
217 size_t m_maxLength = 1024;
218 enum { kStart, kUrl, kStatus, kField, kValue } m_state = kStart;
219 SmallString<128> m_urlBuf;
220 SmallString<32> m_fieldBuf;
221 SmallString<128> m_valueBuf;
222
223 bool m_aborted = false;
224};
225
226} // namespace wpi
227
228#endif // WPINET_HTTPPARSER_H_
This file defines the SmallString class.
HTTP protocol parser.
Definition: HttpParser.h:24
bool IsUpgrade() const
Determine if an upgrade header was present and the parser has exited because of that.
Definition: HttpParser.h:118
sig::Signal< std::string_view, bool > body
Body data callback.
Definition: HttpParser.h:189
void SetMaxLength(size_t len)
Set the maximum accepted length for URLs, field names, and field values.
Definition: HttpParser.h:56
static uint32_t GetParserVersion()
Returns the library version.
sig::Signal< std::string_view > url
URL callback.
Definition: HttpParser.h:154
http_method GetMethod() const
Get HTTP method.
Definition: HttpParser.h:88
HttpParser(Type type)
Constructor.
bool HasError() const
Determine if an error occurred.
Definition: HttpParser.h:96
Type
Definition: HttpParser.h:26
@ kRequest
Definition: HttpParser.h:27
@ kResponse
Definition: HttpParser.h:28
@ kBoth
Definition: HttpParser.h:29
std::string_view Execute(std::string_view in)
Executes the parser.
Definition: HttpParser.h:63
sig::Signal< std::string_view > status
Status callback.
Definition: HttpParser.h:162
void Reset(Type type)
Reset the parser to initial state.
sig::Signal< bool > messageComplete
Headers complete callback.
Definition: HttpParser.h:199
http_errno GetError() const
Get error number.
Definition: HttpParser.h:101
unsigned int GetMajor() const
Get HTTP major version.
Definition: HttpParser.h:72
void Abort()
Abort the parse.
Definition: HttpParser.h:110
sig::Signal< std::string_view, std::string_view > header
Header field callback.
Definition: HttpParser.h:169
std::string_view GetUrl() const
Get URL.
Definition: HttpParser.h:142
sig::Signal chunkComplete
Chunk complete callback.
Definition: HttpParser.h:211
unsigned int GetMinor() const
Get HTTP minor version.
Definition: HttpParser.h:77
sig::Signal messageBegin
Message begin callback.
Definition: HttpParser.h:147
sig::Signal< uint64_t > chunkHeader
Chunk header callback.
Definition: HttpParser.h:206
sig::Signal< bool > headersComplete
Headers complete callback.
Definition: HttpParser.h:179
unsigned int GetStatusCode() const
Get HTTP status code.
Definition: HttpParser.h:83
bool ShouldKeepAlive() const
If this returns false in the headersComplete or messageComplete callback, then this should be the las...
Definition: HttpParser.h:126
bool IsBodyFinal() const
Checks if this is the final chunk of the body.
Definition: HttpParser.h:137
void Pause(bool paused)
Pause the parser.
Definition: HttpParser.h:132
std::string_view str() const
Explicit conversion to std::string_view.
Definition: SmallString.h:181
SignalBase is an implementation of the observer pattern, through the use of an emitting object and sl...
Definition: Signal.h:495
basic_string_view< char > string_view
Definition: core.h:501
constexpr auto in(type t, int set) -> bool
Definition: core.h:611
type
Definition: core.h:556
Definition: ntcore_cpp.h:26
size_t http_parser_execute(http_parser *parser, const http_parser_settings *settings, const char *data, size_t len)
int http_body_is_final(const http_parser *parser)
int http_should_keep_alive(const http_parser *parser)
void http_parser_pause(http_parser *parser, int paused)
Definition: http_parser.h:310
Definition: http_parser.h:279
unsigned int http_errno
Definition: http_parser.h:296
unsigned int method
Definition: http_parser.h:295
unsigned int upgrade
Definition: http_parser.h:303
unsigned short http_major
READ-ONLY.
Definition: http_parser.h:292
unsigned short http_minor
Definition: http_parser.h:293
unsigned int status_code
Definition: http_parser.h:294
http_errno
Definition: http_parser.h:269
http_method
Definition: http_parser.h:194
@ HTTP_BOTH
Definition: http_parser.h:201
@ HTTP_REQUEST
Definition: http_parser.h:201
@ HTTP_RESPONSE
Definition: http_parser.h:201