API
API
C++
API reference (WebServer) — Alpha (1.14.2)

Defold Learn logo


Webserver

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
FUNCTIONS
Result AddHandler (HServer server, const char* prefix, HandlerParams handler_params) Add a new handler without OpenAPI metadata
Result AddHandler (HServer server, const char* prefix, HandlerParams handler_params, const char* openapi_json) Add a new handler with optional OpenAPI metadata
Result AddHandler (HServer server, const char* prefix, HandlerParams handler_params, const char* openapi_json, uint32_t flags) Add a new handler with optional OpenAPI metadata and routing constraints
const char* GetHeader (Request* request, const char* name) Get http header value for key, ignoring ASCII case in the header name
Result Receive (Request* request, void* buffer, uint32_t buffer_size, uint32_t* received_bytes) Receive data
Result RemoveHandler (HServer server, const char* prefix) Remove handle
Result Send (Request request, void* data, uint32_t data_length) Send response data
Result SendAttribute (Request* request, const char* key, const char* value) Sends a header attribute
Result SetStatusCode (Request* request, int status_code) Set response status code.

Functions

AddHandler

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

AddHandler

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

AddHandler

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

GetHeader

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

Receive

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

RemoveHandler

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

Send

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

SendAttribute

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

SetStatusCode

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

Structs

HandlerParams

TYPE

struct HandlerParams

handler parameters

MEMBERS

void* m_UserData The user data
Handler m_Handler The callback


Request

TYPE

struct Request

web 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


Constants

WEBSERVER_CONTEXT_NAME

Name used when registering the web server with the engine context registry.


Types

Handler

void Handler(void* user_data, Request* request)

Web request handler callback

PARAMETERS

void* user_data User data
Request* request Request

RETURNS

void


HServer

void HServer()

web server handle

PARAMETERS



Enums

HandlerFlags

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

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