Http

Simple HTTP server used for serving up the REST API. More...

Collaboration diagram for Http:

Classes
struct	ecs_http_connection_t
	A connection manages communication with the remote host. More...
struct	ecs_http_key_value_t
	Helper type used for headers and URL query parameters. More...
struct	ecs_http_request_t
	An HTTP request. More...
struct	ecs_http_reply_t
	An HTTP reply. More...
struct	ecs_http_server_desc_t
	Used with ecs_http_server_init(). More...

Macros
#define	FLECS_HTTP_H
#define	ECS_HTTP_HEADER_COUNT_MAX   (32)
	Maximum number of headers in a request.
#define	ECS_HTTP_QUERY_PARAM_COUNT_MAX   (32)
	Maximum number of query parameters in a request.
#define	ECS_HTTP_REPLY_INIT   (ecs_http_reply_t){200, ECS_STRBUF_INIT, "OK", "application/json", ECS_STRBUF_INIT}
	Default initializer for ecs_http_reply_t.

Typedefs
typedef struct ecs_http_server_t	ecs_http_server_t
	HTTP server.
typedef bool(*	ecs_http_reply_action_t) (const ecs_http_request_t *request, ecs_http_reply_t *reply, void *ctx)
	Request callback.

Enumerations
enum	ecs_http_method_t {   EcsHttpGet , EcsHttpPost , EcsHttpPut , EcsHttpDelete ,   EcsHttpOptions , EcsHttpMethodUnsupported }
	Supported request methods. More...

Functions
FLECS_API ecs_http_server_t *	ecs_http_server_init (const ecs_http_server_desc_t *desc)
	Create a server.
FLECS_API void	ecs_http_server_fini (ecs_http_server_t *server)
	Destroy a server.
FLECS_API int	ecs_http_server_start (ecs_http_server_t *server)
	Start a server.
FLECS_API void	ecs_http_server_dequeue (ecs_http_server_t *server, ecs_ftime_t delta_time)
	Process server requests.
FLECS_API void	ecs_http_server_stop (ecs_http_server_t *server)
	Stop a server.
FLECS_API int	ecs_http_server_http_request (ecs_http_server_t *srv, const char *req, ecs_size_t len, ecs_http_reply_t *reply_out)
	Emulate a request.
FLECS_API int	ecs_http_server_request (ecs_http_server_t *srv, const char *method, const char *req, const char *body, ecs_http_reply_t *reply_out)
	Convenience wrapper around ecs_http_server_http_request().
FLECS_API void *	ecs_http_server_ctx (ecs_http_server_t *srv)
	Get context provided in ecs_http_server_desc_t.
FLECS_API const char *	ecs_http_get_header (const ecs_http_request_t *req, const char *name)
	Find a header in a request.
FLECS_API const char *	ecs_http_get_param (const ecs_http_request_t *req, const char *name)
	Find a query parameter in a request.

Variables
int64_t	ecs_http_request_received_count
	Global HTTP statistics.
int64_t	ecs_http_request_invalid_count
	Total number of invalid HTTP requests.
int64_t	ecs_http_request_handled_ok_count
	Total number of successful HTTP requests.
int64_t	ecs_http_request_handled_error_count
	Total number of HTTP requests with errors.
int64_t	ecs_http_request_not_handled_count
	Total number of HTTP requests with an unknown endpoint.
int64_t	ecs_http_request_preflight_count
	Total number of preflight HTTP requests received.
int64_t	ecs_http_send_ok_count
	Total number of HTTP replies successfully sent.
int64_t	ecs_http_send_error_count
	Total number of HTTP replies that failed to send.
int64_t	ecs_http_busy_count
	Total number of HTTP busy replies.

Detailed Description

Simple HTTP server used for serving up the REST API.

Macro Definition Documentation

ECS_HTTP_HEADER_COUNT_MAX

#define ECS_HTTP_HEADER_COUNT_MAX   (32)

Maximum number of headers in a request.

Definition at line 38 of file http.h.

ECS_HTTP_QUERY_PARAM_COUNT_MAX

#define ECS_HTTP_QUERY_PARAM_COUNT_MAX   (32)

Maximum number of query parameters in a request.

Definition at line 41 of file http.h.

ECS_HTTP_REPLY_INIT

#define ECS_HTTP_REPLY_INIT   (ecs_http_reply_t){200, ECS_STRBUF_INIT, "OK", "application/json", ECS_STRBUF_INIT}

Default initializer for ecs_http_reply_t.

Definition at line 100 of file http.h.

FLECS_HTTP_H

#define FLECS_HTTP_H

Definition at line 35 of file http.h.

Typedef Documentation

ecs_http_reply_action_t

typedef bool(* ecs_http_reply_action_t) (const ecs_http_request_t *request, ecs_http_reply_t *reply, void *ctx)

Request callback.

Invoked for each valid request. The function should populate the reply and return true. When the function returns false, the server will reply with a 404 (Not found) code.

Definition at line 118 of file http.h.

ecs_http_server_t

typedef struct ecs_http_server_t ecs_http_server_t

HTTP server.

Definition at line 48 of file http.h.

Enumeration Type Documentation

ecs_http_method_t

enum ecs_http_method_t

Supported request methods.

Definition at line 66 of file http.h.

Function Documentation

ecs_http_get_header()

FLECS_API const char * ecs_http_get_header	(	const ecs_http_request_t *	req,
		const char *	name )

Find a header in a request.

Parameters

req	The request.
name	Name of the header to find.

Returns

The header value, or NULL if not found.

ecs_http_get_param()

FLECS_API const char * ecs_http_get_param	(	const ecs_http_request_t *	req,
		const char *	name )

Find a query parameter in a request.

Parameters

req	The request.
name	The parameter name.

Returns

The decoded parameter value, or NULL if not found.

ecs_http_server_ctx()

FLECS_API void * ecs_http_server_ctx

(

ecs_http_server_t *

srv

)

Get context provided in ecs_http_server_desc_t.

Parameters

srv	The server.

Returns

The context.

ecs_http_server_dequeue()

FLECS_API void ecs_http_server_dequeue	(	ecs_http_server_t *	server,
		ecs_ftime_t	delta_time )

Process server requests.

This operation invokes the reply callback for each received request. No new requests will be enqueued while processing requests.

Parameters

server	The server for which to process requests.
delta_time	The time passed since the last call to dequeue.

ecs_http_server_fini()

FLECS_API void ecs_http_server_fini

(

ecs_http_server_t *

server

)

Destroy a server.

This operation will stop the server if it was still running.

Parameters

server

The server to destroy.

ecs_http_server_http_request()

FLECS_API int ecs_http_server_http_request	(	ecs_http_server_t *	srv,
		const char *	req,
		ecs_size_t	len,
		ecs_http_reply_t *	reply_out )

Emulate a request.

The request string must be a valid HTTP request. A minimal example:

GET /entity/flecs/core/World?label=true HTTP/1.1

Parameters

srv	The server.
req	The request.
len	The length of the request (optional).
reply_out	The reply (out parameter).

Returns

Zero if success, non-zero if failed.

ecs_http_server_init()

FLECS_API ecs_http_server_t * ecs_http_server_init

(

const ecs_http_server_desc_t *

desc

)

Create a server.

Use ecs_http_server_start() to start receiving requests.

Parameters

desc	Server configuration parameters.

Returns

The new server, or NULL if creation failed.

ecs_http_server_request()

FLECS_API int ecs_http_server_request	(	ecs_http_server_t *	srv,
		const char *	method,
		const char *	req,
		const char *	body,
		ecs_http_reply_t *	reply_out )

Convenience wrapper around ecs_http_server_http_request().

Parameters

srv	The server.
method	The HTTP method (e.g., "GET").
req	The request path.
body	The request body (optional).
reply_out	The reply (out parameter).

Returns

Zero if success, non-zero if failed.

ecs_http_server_start()

FLECS_API int ecs_http_server_start

(

ecs_http_server_t *

server

)

Start a server.

After this operation, the server will be able to accept requests.

Parameters

server

The server to start.

Returns

Zero if successful, non-zero if failed.

ecs_http_server_stop()

FLECS_API void ecs_http_server_stop

(

ecs_http_server_t *

server

)

Stop a server.

After this operation, no new requests can be received.

Parameters

server

The server.

Variable Documentation

ecs_http_request_received_count

int64_t ecs_http_request_received_count

extern

Global HTTP statistics.

Total number of HTTP requests received.