HTTP server functions. More...

Modules
Types
HTTP server data types.

Macros
HTTP server macros.

Functions
bool	gos_hs_is_running (void)
	Returns if the HTTP server is running. More...

char *	gos_hs_url_decode (char *buffer)
	Decode URL encoded string destructively (i.e. in-place) More...

gos_result_t	gos_hs_read_post_data (const gos_hs_request_t request, gos_buffer_t buffer, uint32_t timeout_ms)
	Read body of HTTP POST request. More...

gos_result_t	gos_hs_write_reply_header (const gos_hs_request_t request, const char mime_type, int32_t length, gos_hs_response_flag_t flags)
	Return HTTP response with a 200 status code. More...

gos_result_t	gos_hs_write_reply_header_with_config (const gos_hs_request_t request, const gos_hs_reply_config_t config)
	Return HTTP response with specified configuration. More...

gos_result_t	gos_hs_write_chunked_data (const gos_hs_request_t request, const void data, uint32_t data_len, bool flush_now)
	Write HTTP body with chunked encoding. More...

gos_result_t	gos_hs_write_data (const gos_hs_request_t request, const void data, uint32_t data_len, bool flush_now)
	Write HTTP body with non-chunked encoding. More...

bool	gos_hs_authorize_user (const gos_hs_request_t request, char processing_buffer, const char user, const char password)
	Authorize HTTP request user credentials. More...

gos_result_t	gos_hs_write_unauthorized_response (const gos_hs_request_t *request)
	Return Unauthorized HTTP response. More...

gos_result_t	gos_hs_write_not_found_response (const gos_hs_request_t *request)
	Return Not Found HTTP response. More...

gos_result_t	gos_hs_return_status_code (const gos_hs_request_t request, uint32_t code, const char msg)
	Return HTTP response with status code. More...

void	gos_hs_register_dynamic_page (const gos_hs_dynamic_page_t *page)
	Register dynamic URL callback. More...

void	gos_hs_register_header_callback (const gos_hs_custom_header_callback_t callback)
	Register custom header callback. More...

void	gos_hs_register_authorize_callback (const gos_hs_authorize_callback_t callback)
	Register unauthorized callback. More...

void	gos_hs_register_not_found_callback (const gos_hs_not_found_callback_t callback)
	Register page not found callback. More...

gos_hs_param_t *	gos_hs_request_get_param (const gos_hs_request_t request, const char key)
	Return GET parameter with specified key. More...

gos_hs_header_t *	gos_hs_request_get_header (const gos_hs_request_t request, const char key)
	Return request header with specified key. More...

gos_hs_method_t	gos_hs_request_get_method (const gos_hs_request_t *request)
	Return the method type of the HTTP request. More...

int32_t	gos_hs_request_get_content_length (const gos_hs_request_t *request)
	Return the number of bytes available from the HTTP request. More...

gos_result_t	gos_hs_get_tls_client_list ( gos_hs_tls_client_t **client_list_ptr)
	Return list of recently connected TLS clients. More...

void	gos_hs_destroy_tls_client_list ( gos_hs_tls_client_t *client_list)
	Release memory allocated by gos_hs_get_tls_client_list() More...

Detailed Description

HTTP server functions.

Function Documentation

◆ gos_hs_authorize_user()

bool gos_hs_authorize_user	(	const gos_hs_request_t *	`request,`
		char *	`processing_buffer,`
		const char *	`user,`
		const char *	`password`
	)

Authorize HTTP request user credentials.

This validates the provided Basic credentials in an HTTP request. More info here

This should be call immediately after a gos_hs_request_processor_t callback. Typically gos_hs_write_unauthorized_response() would be called if this function returns false.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`processing_buffer`	This is used for internal prcoessing, it should be at least 64 bytes
`user`	The user name to validate against, set to NULL to use the http.server.username setting
`password`	The password to validate against, set to NULL to use the http.server.password setting

Returns: gos_result_t result of api call

◆ gos_hs_destroy_tls_client_list()

void gos_hs_destroy_tls_client_list ( gos_hs_tls_client_t * client_list )

Release memory allocated by gos_hs_get_tls_client_list()

Parameters

client_list List returned by gos_hs_get_tls_client_list()

◆ gos_hs_get_tls_client_list()

gos_result_t gos_hs_get_tls_client_list ( gos_hs_tls_client_t ** client_list_ptr )

Return list of recently connected TLS clients.

Return list of recently connected clients. Up to 8 clients are logged. When the log contains 8 clients and a new client is added, the oldest client is removed. Requires http.server.tls_log_clients to be enabled.

gos_hs_destroy_tls_client_list() must be called to free the memory allocated by the returned list.

See Gecko OS Command API documentation: http.server.tls_client_log .

Parameters

[out] client_list_ptr Pointer to hold linked list of gos_hs_tls_client_t

◆ gos_hs_is_running()

bool gos_hs_is_running ( void )

Returns if the HTTP server is running.

Returns: true if the HTTP server is running, false else

◆ gos_hs_read_post_data()

gos_result_t gos_hs_read_post_data	(	const gos_hs_request_t *	`request,`
		gos_buffer_t *	`buffer,`
		uint32_t	`timeout_ms`
	)

Read body of HTTP POST request.

This should be used in a gos_hs_request_processor_t callback.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`buffer`	Pointer to the gos_buffer_t to be filled with the HTTP post body and number of bytes read
`timeout_ms`	Stream read timeout in milliseconds

Returns: gos_result_t result of api call

Examples:: network/http_server/requests/json_parser.c .

◆ gos_hs_register_authorize_callback()

void gos_hs_register_authorize_callback ( const gos_hs_authorize_callback_t callback )

Register unauthorized callback.

Register callback to be called to authorized username/password of HTTP request. The callback executes in the HTTP server thread.

Parameters

callback Callback to be called before processing HTTP request, see gos_hs_authorize_callback_t

Returns: gos_result_t result of api call

◆ gos_hs_register_dynamic_page()

void gos_hs_register_dynamic_page ( const gos_hs_dynamic_page_t * page )

Register dynamic URL callback.

The callback will be called when the specified URL is requested. The callback executes in the HTTP server thread context.

Parameters

page URL/callback to register, see gos_hs_dynamic_page_t

Returns: gos_result_t result of api call

◆ gos_hs_register_header_callback()

void gos_hs_register_header_callback ( const gos_hs_custom_header_callback_t callback )

Register custom header callback.

Register callback to be called for each HTTP request header. This allows for storing custom HTTP headers in the HTTP request object.

The custom headers are retrieved from the gos_hs_request_t with gos_hs_request_get_header() The callback executes in the HTTP server thread BEFORE the gos_hs_request_processor_t is called.

Parameters

callback Callback to be called for each HTTP header, see gos_hs_custom_header_callback_t

Returns: gos_result_t result of api call

◆ gos_hs_register_not_found_callback()

void gos_hs_register_not_found_callback ( const gos_hs_not_found_callback_t callback )

Register page not found callback.

Register callback to be called if requested URL is not found. The callback executes in the HTTP server thread.

Parameters

callback Callback to be called if request URL is not found, see gos_hs_not_found_callback_t

Returns: gos_result_t result of api call

◆ gos_hs_request_get_content_length()

int32_t gos_hs_request_get_content_length ( const gos_hs_request_t * request )

Return the number of bytes available from the HTTP request.

If the request is chunked encoded then this returns the number of remaining bytes in the current chunk, otherwise this returns the number of bytes in the request body.

Note: This should be used in a gos_hs_request_processor_t callback.

Parameters

request Internal HTTP request pointer, provided by gos_hs_request_processor_t callback

Returns: Number of bytes available to be read

◆ gos_hs_request_get_header()

gos_hs_header_t * gos_hs_request_get_header	(	const gos_hs_request_t *	`request,`
		const char *	`key`
	)

Return request header with specified key.

This allows for returning a HTTP header with the given key. Note that only gos_hs_request_header_t are returned with a HTTP request by default. To return custom headers, use gos_hs_register_header_callback() This should be used in a gos_hs_request_processor_t callback.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`key`	The HTTP header's key value

Returns: gos_hs_header_t if header with key found, NULL else

◆ gos_hs_request_get_method()

gos_hs_method_t gos_hs_request_get_method ( const gos_hs_request_t * request )

Return the method type of the HTTP request.

This should be used in a gos_hs_request_processor_t callback.

Parameters

request Internal HTTP request pointer, provided by gos_hs_request_processor_t callback

Returns: The gos_hs_method_t of the current HTTP request

Examples:: network/http_server/requests/json_parser.c .

◆ gos_hs_request_get_param()

gos_hs_param_t * gos_hs_request_get_param	(	const gos_hs_request_t *	`request,`
		const char *	`key`
	)

Return GET parameter with specified key.

Returns a GET parameter's value.

A GET request contains parameters of the form:

http: //mydevice.com/my_dynamic_webpage?param1=123&param2=abc

The get the request's param1, the following code would be used:

gos_hs_param_t *param1 = gos_hs_request_get_param (request, "param1" );

This should be used in a gos_hs_request_processor_t callback.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`key`	The parameter's key value

Returns: gos_hs_param_t if key found, NULL else

Examples:: network/http_server/requests/get_params.c .

◆ gos_hs_return_status_code()

gos_result_t gos_hs_return_status_code	(	const gos_hs_request_t *	`request,`
		uint32_t	`code,`
		const char *	`msg`
	)

Return HTTP response with status code.

Return a HTTP status code with optional message. The message is printed in the body of the response.

More info about HTTP status codes: here

This should be used in a gos_hs_request_processor_t callback.

Note: The HTTP client request is closed after the response is sent.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`code`	The http status code.
`msg`	Optional message to print in body of response

Returns: gos_result_t result of api call

Examples:: network/http_server/requests/get_params.c , network/http_server/requests/json_parser.c , and network/http_server/requests/set_light.c .

◆ gos_hs_url_decode()

char* gos_hs_url_decode ( char * buffer )

Decode URL encoded string destructively (i.e. in-place)

Parameters

buffer Pointer to url encoded string

Returns: Same pointer as buffer, with contents url decoded

◆ gos_hs_write_chunked_data()

gos_result_t gos_hs_write_chunked_data	(	const gos_hs_request_t *	`request,`
		const void *	`data,`
		uint32_t	`data_len,`
		bool	`flush_now`
	)

Write HTTP body with chunked encoding.

Write the body of a HTTP request using 'Transfer-Encoding: chunked'.

gos_hs_write_reply_header() must be called first with its 'length' parameter set to -1.

This should be used in a gos_hs_request_processor_t callback.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`data`	Data to write to response
`data_len`	Amount of data to write
`flush_now`	Set to false if there is more data to write, true if this is the last write (which will complete the response)

Returns: gos_result_t result of api call

Examples:: network/http_server/requests/json_generator.c .

◆ gos_hs_write_data()

gos_result_t gos_hs_write_data	(	const gos_hs_request_t *	`request,`
		const void *	`data,`
		uint32_t	`data_len,`
		bool	`flush_now`
	)

Write HTTP body with non-chunked encoding.

Write the body of the HTTP request using 'Content-Legnth: xxx'

gos_hs_write_reply_header() must be called first with its 'length' parameter > 0.

This should be used in a gos_hs_request_processor_t callback.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`data`	Data to write to response
`data_len`	Amount of data to write
`flush_now`	Set to false if there is more data to write, true if this is the last write (which will complete the response)

Returns: gos_result_t result of api call

Examples:: network/http_server/requests/get_params.c , network/http_server/requests/json_parser.c , network/http_server/requests/root_page.c , network/http_server/requests/set_light.c , and network/http_server/requests/toggle_light.c .

◆ gos_hs_write_not_found_response()

gos_result_t gos_hs_write_not_found_response ( const gos_hs_request_t * request )

Return Not Found HTTP response.

Return a 404 Not Found HTTP response

This should be used in a gos_hs_request_processor_t callback.

Parameters

request Internal HTTP request pointer, provided by gos_hs_request_processor_t callback

Returns: gos_result_t result of api call

◆ gos_hs_write_reply_header()

gos_result_t gos_hs_write_reply_header	(	const gos_hs_request_t *	`request,`
		const char *	`mime_type,`
		int32_t	`length,`
		gos_hs_response_flag_t	`flags`
	)

Return HTTP response with a 200 status code.

Completes a HTTP request with a 200 status code.

This should be used in a gos_hs_request_processor_t callback.

Note: To return a non-200 code, see gos_hs_return_status_code()

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`mime_type`	The response 'Content-Type', set NULL if unused
`length`	The 'Content-Length' if > 0, set to -1 for 'Transfer-Encoding: chunked'
`flags`	Optionals flags to add to the response headers, gos_hs_response_flag_t

Returns: gos_result_t result of api call

Examples:: network/http_server/requests/get_params.c , network/http_server/requests/json_generator.c , network/http_server/requests/json_parser.c , network/http_server/requests/root_page.c , network/http_server/requests/set_light.c , and network/http_server/requests/toggle_light.c .

◆ gos_hs_write_reply_header_with_config()

gos_result_t gos_hs_write_reply_header_with_config	(	const gos_hs_request_t *	`request,`
		const gos_hs_reply_config_t *	`config`
	)

Return HTTP response with specified configuration.

Completes a HTTP request with the specified configuration

This should be used in a gos_hs_request_processor_t callback.

Parameters

`request`	Internal HTTP request pointer, provided by gos_hs_request_processor_t callback
`config`	The reply configuration, see gos_hs_reply_config_t

Returns: gos_result_t result of api call

◆ gos_hs_write_unauthorized_response()

gos_result_t gos_hs_write_unauthorized_response ( const gos_hs_request_t * request )

Return Unauthorized HTTP response.

Return a 403 Unauthorized HTTP response

This should be used in a gos_hs_request_processor_t callback.

Parameters

request Internal HTTP request pointer, provided by gos_hs_request_processor_t callback

Returns: gos_result_t result of api call

HTTP Server Protocols

Modules

Functions

Detailed Description

Function Documentation

◆ gos_hs_authorize_user()

◆ gos_hs_destroy_tls_client_list()

◆ gos_hs_get_tls_client_list()

◆ gos_hs_is_running()

◆ gos_hs_read_post_data()

◆ gos_hs_register_authorize_callback()

◆ gos_hs_register_dynamic_page()

◆ gos_hs_register_header_callback()

◆ gos_hs_register_not_found_callback()

◆ gos_hs_request_get_content_length()

◆ gos_hs_request_get_header()

◆ gos_hs_request_get_method()

◆ gos_hs_request_get_param()

◆ gos_hs_return_status_code()

◆ gos_hs_url_decode()

◆ gos_hs_write_chunked_data()

◆ gos_hs_write_data()

◆ gos_hs_write_not_found_response()

◆ gos_hs_write_reply_header()

◆ gos_hs_write_reply_header_with_config()

◆ gos_hs_write_unauthorized_response()

HTTP Server
Protocols