API reference (WebServer) | Defold 1.14.1 (Alpha)

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
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
const char* GetHeader (Request* request, const char* name)	Get http header value for key
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.

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

GetHeader

const char* GetHeader(Request* request, const char* name)

Get http header value for key

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)

Send response data

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

Result

result codes

`RESULT_OK`
`RESULT_SOCKET_ERROR`
`RESULT_INVALID_REQUEST`
`RESULT_ERROR_INVAL`
`RESULT_HANDLER_ALREADY_REGISTRED`
`RESULT_HANDLER_NOT_REGISTRED`
`RESULT_INTERNAL_ERROR`
`RESULT_UNKNOWN`