8000 Add class descriptions · comod/esp32_https_server@cfbe927 · GitHub
[go: up one dir, main page]
Skip to content

Commit cfbe927

Browse files
fhesselfhessel
committed
Add class descriptions
1 parent c7c04ad commit cfbe927

20 files changed

+163
-5
lines changed

‎src/ConnectionContext.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ namespace httpsserver {
1111

1212
class WebsocketHandler;
1313

14+
/**
15+
* \brief Internal class to handle the state of a connection
16+
*/
1417
class ConnectionContext {
1518
public:
1619
ConnectionContext();

‎src/HTTPConnection.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@
3131

3232
namespace httpsserver {
3333

34+
/**
35+
* \brief Represents a single open connection for the plain HTTPServer, without TLS
36+
*/
3437
class HTTPConnection : private ConnectionContext {
3538
public:
3639
HTTPConnection(ResourceResolver * resResolver);

‎src/HTTPHeader.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66

77
namespace httpsserver {
88

9+
/**
10+
* \brief Represents a single name/value pair of an HTTP header
11+
*/
912
class HTTPHeader {
1013
public:
1114
HTTPHeader(const std::string &name, const std::string &value);

‎src/HTTPHeaders.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212

1313
namespace httpsserver {
1414

15+
/**
16+
* \brief Groups and manages a set of HTTPHeader instances
17+
*/
1518
class HTTPHeaders {
1619
public:
1720
HTTPHeaders();

‎src/HTTPMiddlewareFunction.hpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
namespace httpsserver {
1111
class HTTPRequest;
1212
/**
13-
* A middleware function that can be registered at the server.
13+
* \brief A middleware function that can be registered at the server.
1414
*
1515
* It will be called before an incoming request is passed to any HTTPSCallbackFunction and may perform
1616
* operations like redirects or authentication.

‎src/HTTPNode.hpp

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ enum HTTPNodeType {
1717
WEBSOCKET
1818
};
1919

20+
/**
21+
* \brief Base class for a URL/route-handler in the server.
22+
*
23+
* Use ResourceNode for requests that access dynamic or static resources or HttpNode for routes that
24+
* create Websockets.
25+
*/
2026
class HTTPNode {
2127
public:
2228
HTTPNode(const std::string &path, const HTTPNodeType nodeType, const std::string &tag = "");

‎src/HTTPRequest.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515

1616
namespace httpsserver {
1717

18+
/**
19+
* \brief Represents the request stream for an HTTP request
20+
*/
1821
class HTTPRequest {
1922
public:
2023
HTTPRequest(ConnectionContext * con, HTTPHeaders * headers, HTTPNode * resolvedNode, std::string method, ResourceParameters * params, std::string requestString);

‎src/HTTPResponse.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919

2020
namespace httpsserver {
2121

22+
/**
23+
* \brief Represents the response stream of an HTTP request
24+
*/
2225
class HTTPResponse : public Print {
2326
public:
2427
HTTPResponse(ConnectionContext * con);

‎src/HTTPSCallbackFunction.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
#include "HTTPResponse.hpp"
66

77
namespace httpsserver {
8+
/**
9+
* \brief A callback function that will be called by the server to handle a request
10+
*/
811
typedef void (HTTPSCallbackFunction)(HTTPRequest * req, HTTPResponse * res);
912
}
1013

‎src/HTTPSConnection.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@
2626

2727
namespace httpsserver {
2828

29+
/**
30+
* \brief Connection class for an open TLS-enabled connection to an HTTPSServer
31+
*/
2932
class HTTPSConnection : public HTTPConnection {
3033
public:
3134
HTTPSConnection(ResourceResolver * resResolver);

‎src/HTTPSServer.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424

2525
namespace httpsserver {
2626

27+
/**
28+
* \brief Main implementation of the HTTP Server with TLS support. Use HTTPServer for plain HTTP
29+
*/
2730
class HTTPSServer : public HTTPServer {
2831
public:
2932
HTTPSServer(SSLCert * cert, const uint16_t portHTTPS = 443, const uint8_t maxConnections = 4, const in_addr_t bindAddress = 0);

‎src/HTTPServer.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424

2525
namespace httpsserver {
2626

27+
/**
28+
* \brief Main implementation for the plain HTTP server. Use HTTPSServer for TLS support
29+
*/
2730
class HTTPServer : public ResourceResolver {
2831
public:
2932
HTTPServer(const uint16_t portHTTPS = 80, const uint8_t maxConnections = 8, const in_addr_t bindAddress = 0);

‎src/HTTPValidator.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ namespace httpsserver {
77

88
typedef bool (HTTPValidationFunction)(std::string);
99

10+
/**
11+
* \brief Internal representation of a validator function
12+
*/
1013
class HTTPValidator {
1114
public:
1215
HTTPValidator(const uint8_t idx, const HTTPValidationFunction * validatorFunction);

‎src/ResolvedResource.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66

77
namespace httpsserver {
88

9+
/**
10+
* \brief This class represents a resolved resource, meaning the result of mapping a string URL to an HTTPNode
11+
*/
912
class ResolvedResource {
1013
public:
1114
ResolvedResource();

‎src/ResourceNode.hpp

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@
88

99
namespace httpsserver {
1010

11+
/**
12+
* \brief This HTTPNode represents a route that maps to a regular HTTP request for a resource (static or dynamic)
13+
*
14+
* It therefore contrasts to the WebsocketNode, which handles requests for Websockets.
15+
*/
1116
class ResourceNode : public HTTPNode {
1217
public:
1318
ResourceNode(const std::string &path, const std::string &method, const HTTPSCallbackFunction * callback, const std::string &tag = "");

‎src/ResourceParameters.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ namespace httpsserver {
1616

1717
struct requestparam_t {std::string name; std::string value;};
1818

19+
/**
20+
* \brief Class used to handle access to the URL parameters
21+
*/
1922
class ResourceParameters {
2023
public:
2124
ResourceParameters();

‎src/ResourceResolver.hpp

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@
1616

1717
namespace httpsserver {
1818

19+
/**
20+
* \brief This class is used internally to resolve a string URL to the corresponding HTTPNode
21+
*/
1922
class ResourceResolver {
2023
public:
2124
ResourceResolver();

‎src/SSLCert.hpp

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,46 @@
3232

3333
namespace httpsserver {
3434

35+
/**
36+
* \brief Certificate and private key that can be passed to the HTTPSServer.
37+
*
38+
* **Converting PEM to DER Files**
39+
*
40+
* Certificate:
41+
* ```bash
42+
* openssl x509 -inform PEM -outform DER -in myCert.crt -out cert.der
43+
* ```
44+
*
45+
* Private Key:
46+
* ```bash
47+
* openssl rsa -inform PEM -outform DER -in myCert.key -out key.der
48+
* ```
49+
*
50+
* **Converting DER File to C Header**
51+
*
52+
* ```bash
53+
* echo "#ifndef KEY_H_" > ./key.h
54+
* echo "#define KEY_H_" >> ./key.h
55+
* xxd -i key.der >> ./key.h
56+
* echo "#endif" >> ./key.h
57+
* ```
58+
*/
3559
class SSLCert {
3660
public:
61+
/**
62+
* \brief Creates a new SSLCert.
63+
*
64+
* The certificate and key data may be NULL (default values) if the certificate is meant
65+
* to be passed to createSelfSignedCert().
66+
*
67+
* Otherwise, the data must reside in a memory location that is not deleted until the server
68+
* using the certificate is stopped.
69+
*
70+
* \param[in] certData The certificate data to use (DER format)
71+
* \param[in] certLength The length of the certificate data
72+
* \param[in] pkData The private key data to use (DER format)
73+
* \param[in] pkLength The length of the private key
74+
*/
3775
SSLCert(
3876
unsigned char * certData = NULL,
3977
uint16_t certLength = 0,
@@ -42,15 +80,55 @@ class SSLCert {
4280
);
4381
virtual ~SSLCert();
4482

83+
/**
84+
* \brief Returns the length of the certificate in byte
85+
*/
4586
uint16_t getCertLength();
87+
88+
/**
89+
* \brief Returns the length of the private key in byte
90+
*/
4691
uint16_t getPKLength();
92+
93+
/**
94+
* \brief Returns the certificate data
95+
*/
4796
unsigned char * getCertData();
97+
98+
/**
99+
* \brief Returns the private key data
100+
*/
48101
unsigned char * getPKData();
49102

103+
/**
104+
* \brief Sets the private key in DER format
105+
*
106+
* The data has to reside in a place in memory that is not deleted as long as the
107+
* server is running.
108+
*
109+
* See SSLCert() for some information on how to generate DER data.
110+
*
111+
* \param[in] _pkData The data of the private key
112+
* \param[in] length The length of the private key
113+
*/
50114
void setPK(unsigned char * _pkData, uint16_t length);
115+
116+
/**
117+
* \brief Sets the certificate data in DER format
118+
*
119+
* The data has to reside in a place in memory that is not deleted as long as the
120+
* server is running.
121+
*
122+
* See SSLCert for some information on how to generate DER data.
123+
*
124+
* \param[in] _certData The data of the certificate
125+
* \param[in] length The length of the certificate
126+
*/
51127
void setCert(unsigned char * _certData, uint16_t length);
52128

53-
/** Clears the key buffers and delets them. */
129+
/**
130+
* \brief Clears the key buffers and deletes them.
131+
*/
54132
void clear();
55133

56134
private:
@@ -63,13 +141,23 @@ class SSLCert {
63141

64142
#ifndef HTTPS_DISABLE_SELFSIGNING
65143

144+
/**
145+
* \brief Defines the key size for key generation
146+
*
147+
* Not available if the `HTTPS_DISABLE_SELFSIGNING` compiler flag is set
148+
*/
66149
enum SSLKeySize {
150+
/** \brief RSA key with 1024 bit */
67151
KEYSIZE_1024 = 1024,
152+
/** \brief RSA key with 2048 bit */
68153
KEYSIZE_2048 = 2048,
154+
/** \brief RSA key with 4096 bit */
69155
KEYSIZE_4096 = 4096
70156
};
71157

72158
/**
159+
* \brief Creates a self-signed certificate on the ESP32
160+
*
73161
* This function creates a new self-signed certificate for the given hostname on the heap.
74162
* Make sure to clear() it before you delete it.
75163
*
@@ -82,6 +170,8 @@ enum SSLKeySize {
82170
*
83171
* This will take some time, so you should probably write the certificate data to non-volatile
84172
* storage when you are done.
173+
*
174+
* Setting the `HTTPS_DISABLE_SELFSIGNING` compiler flag will remove this function from the library
85175
*/
86176
int createSelfSignedCert(SSLCert &certCtx, SSLKeySize keySize, std::string dn, std::string validFrom = "20190101000000", std::string validUntil = "20300101000000");
87177

‎src/ValidatorFunctions.hpp

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,19 @@
1919

2020
namespace httpsserver {
2121

22-
/** Checks that a string is not empty. */
22+
/**
23+
* \brief **Built-in validator function**: Checks that a string is not empty.
24+
*/
2325
bool validateNotEmpty(std::string s);
2426

2527
/**
28+
* \brief **Built-in validator function**: Checks that a value is a positive int
29+
*
2630
* Checks that the value is a positive integer (combine it with newValidateUnsignedIntegerMax if
27-
* you have constraints regarding the size of that number
31+
* you have constraints regarding the size of that number)
2832
*/
2933
bool validateUnsignedInteger(std::string s);
3034

3135
}
3236

33-
#endif
37+
#endif

‎src/util.hpp

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,21 @@
88

99
namespace httpsserver {
1010

11+
/**
12+
* \brief **Utility function**: Parse an unsigned integer from a string
13+
*
14+
* The second parameter can be used to define the maximum value that is acceptable
15+
*/
1116
uint32_t parseUInt(std::string const &s, uint32_t max = 0xffffffff);
1217

18+
/**
19+
* \brief **Utility function**: Parse a signed integer from a string
20+
*/
1321
int32_t parseInt(std::string const &s);
1422

23+
/**
24+
* \brief **Utility function**: Transform an int to a std::string
25+
*/
1526
std::string intToString(int i);
1627

1728
}

0 commit comments

Comments
 (0)
0