Simple high-level single-threaded Web server based on dmHttpServer The web-server has a handler concept similar to servlets in Java
| Namespace: | dmWebServer |
| Include: | #include <dmsdk/dlib/webserver.h> |
| TYPES | |
|---|---|
| Handler | Web request handler callback |
| HServer | web server handle |
| CONSTANTS | |
|---|---|
| WEBSERVER_CONTEXT_NAME | Web server extension context name |
| ENUMS | |
|---|---|
| HandlerFlags | optional handler constraints |
| Result | result codes |
| STRUCTS | |
|---|---|
| struct HandlerParams | handler parameters |
| struct Request | web server request |
Result AddHandler(HServer server, const char* prefix, HandlerParams handler_params)
Requests use the handler with the longest matching prefix, regardless of registration order. A handler registered at "/" serves as a fallback. Equivalent to calling the four-argument overload with openapi_json set to 0.
PARAMETERS
HServer |
server |
Server handle |
const char* |
prefix |
Location prefix for which locations this handler should handle |
HandlerParams |
handler_params |
Handler parameters |
RETURNS
Result |
RESULT_OK on success |
Result AddHandler(HServer server, const char* prefix, HandlerParams handler_params, const char* openapi_json)
Requests use the handler with the longest matching prefix, regardless of registration order. A handler registered at "/" serves as a fallback. Pass 0 to register without documenting the handler. Otherwise, the OpenAPI JSON is a non-empty Paths Object describing the paths and methods served by this handler. Each path must start with the handler's prefix and must not already be documented by another handler. Schemas should be inline or use references to paths in the resulting document. The server retains the JSON pointer without copying it. Keep the string unchanged and valid until the handler is removed or the server is deleted; a static const char array is recommended. Equivalent to calling the five-argument overload with flags set to 0.
PARAMETERS
HServer |
server |
Server handle |
const char* |
prefix |
Location prefix for which locations this handler should handle |
HandlerParams |
handler_params |
Handler parameters |
const char* |
openapi_json |
OpenAPI 3.0.3 Paths Object encoded as a JSON string, or 0 to omit metadata |
RETURNS
Result |
RESULT_OK on success, RESULT_ERROR_INVAL for invalid or conflicting metadata |
Result AddHandler(HServer server, const char* prefix, HandlerParams handler_params, const char* openapi_json, uint32_t flags)
Flags are a bitwise combination of HandlerFlags; 0 preserves prefix matching and leaves method and body handling to the callback. Among matching handlers, the longest prefix wins. Method and body constraints are then checked before invoking its callback; rejected requests do not fall back to another handler. Body rejection takes precedence over method rejection. These errors use application/json with an error object containing code and message fields. Rejected requests with a body close the connection without waiting for the upload. OpenAPI metadata has the same format and lifetime as in the four-argument overload.
PARAMETERS
HServer |
server |
Server handle |
const char* |
prefix |
Location prefix, or exact path with MATCH_EXACT_PATH |
HandlerParams |
handler_params |
Handler parameters |
const char* |
openapi_json |
OpenAPI 3.0.3 Paths Object encoded as a JSON string, or 0 to omit metadata |
uint32_t |
flags |
Bitwise combination of HandlerFlags |
RETURNS
Result |
RESULT_OK on success, RESULT_ERROR_INVAL for invalid or conflicting metadata |
const char* GetHeader(Request* request, const char* name)
Get http header value for key, ignoring ASCII case in the header name
PARAMETERS
Request* |
request |
Request |
const char* |
name |
Header key |
RETURNS
const char* |
Header value. NULL if the key doesn't exists |
Result Receive(Request* request, void* buffer, uint32_t buffer_size, uint32_t* received_bytes)
Receive data
PARAMETERS
Request* |
request |
Request |
void* |
buffer |
Data buffer to receive to |
uint32_t |
buffer_size |
Buffer size |
uint32_t* |
received_bytes |
Number of bytes received |
RETURNS
Result |
RESULT_OK on success |
Result RemoveHandler(HServer server, const char* prefix)
Remove handle
PARAMETERS
HServer |
server |
Server handle |
const char* |
prefix |
Prefix for handle to remove |
RETURNS
Result |
RESULT_OK on success |
Result Send(Request request, void* data, uint32_t data_length)
Copies data into an owned response sent asynchronously after the handler returns. Socket errors are handled by the server; RESULT_OK means the data was queued.
PARAMETERS
Request |
request |
Request handle |
void* |
data |
Data to send |
uint32_t |
data_length |
Data-lenght to send |
RETURNS
Result |
RESULT_OK on success |
Result SendAttribute(Request* request, const char* key, const char* value)
Sends a header attribute
PARAMETERS
Request* |
request |
Request |
const char* |
key |
the header name |
const char* |
value |
the header value |
RETURNS
Result |
RESULT_OK on success |
Result SetStatusCode(Request* request, int status_code)
Set response status code.
PARAMETERS
Request* |
request |
Request |
int |
status_code |
Status code to set |
RETURNS
Result |
RESULT_OK on success |
TYPE
struct HandlerParamshandler parameters
MEMBERS
void* |
m_UserData |
The user data |
Handler |
m_Handler |
The callback |
TYPE
struct Requestweb server request
MEMBERS
const char* |
m_Method |
Request method |
const char* |
m_Method |
Request resource |
const char* |
m_Method |
Content-Length header |
const char* |
m_Method |
Internal data |
void Handler(void* user_data, Request* request)
Web request handler callback
PARAMETERS
void* |
user_data |
User data |
Request* |
request |
Request |
RETURNS
void |
void HServer()
web server handle
PARAMETERS
optional handler constraints
MATCH_EXACT_PATH |
Match the entire path, ignoring the query string. The request resource retains the query string. |
GET_ONLY |
Reject methods other than GET with status 405 and Allow: GET. |
NO_REQUEST_BODY |
Reject non-empty request bodies with status 400 and close the connection without waiting for the upload. |
result codes
RESULT_OK |
|
RESULT_SOCKET_ERROR |
|
RESULT_INVALID_REQUEST |
|
RESULT_ERROR_INVAL |
|
RESULT_HANDLER_ALREADY_REGISTRED |
|
RESULT_HANDLER_NOT_REGISTRED |
|
RESULT_TRY_AGAIN |
|
RESULT_INTERNAL_ERROR |
|
RESULT_UNKNOWN |