balde public API. More...

#include <glib.h>
#include <gio/gio.h>

Data Structures
struct	balde_app_t
	balde application context More...

struct	balde_authorization_t
	balde HTTP authorization context. More...

struct	balde_file_t
	balde file representation. More...

struct	balde_request_t
	balde HTTP request context More...

struct	balde_response_t
	balde HTTP response context More...

Macros
#define	BALDE_LOG_DOMAIN "balde"

#define	balde_log_critical(...) g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, __VA_ARGS__)

#define	balde_log_warning(...) g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_WARNING, __VA_ARGS__)

#define	balde_log_message(...) g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, __VA_ARGS__)

#define	balde_log_info(...) g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_INFO, __VA_ARGS__)

#define	balde_log_debug(...) g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, __VA_ARGS__)

Typedefs
typedef balde_response_t (	balde_view_func_t) (balde_app_t , balde_request_t )
	View type definition. More...

typedef void(*	balde_before_request_func_t) (balde_app_t , balde_request_t )
	"Before request" hook type definition More...

Enumerations
enum	balde_http_method_t { BALDE_HTTP_NONE = 0, BALDE_HTTP_OPTIONS = 1 << 0, BALDE_HTTP_GET = 1 << 1, BALDE_HTTP_HEAD = 1 << 2, BALDE_HTTP_POST = 1 << 3, BALDE_HTTP_PUT = 1 << 4, BALDE_HTTP_PATCH = 1 << 5, BALDE_HTTP_DELETE = 1 << 6, BALDE_HTTP_ANY = 0xFF }
	Supported HTTP methods. More...

enum	balde_http_exception_code_t { BALDE_HTTP_OK = 200, BALDE_HTTP_MULTIPLE_CHOICES = 300, BALDE_HTTP_MOVED_PERMANENTLY = 301, BALDE_HTTP_FOUND = 302, BALDE_HTTP_SEE_OTHER = 303, BALDE_HTTP_NOT_MODIFIED = 304, BALDE_HTTP_USE_PROXY = 305, BALDE_HTTP_TEMPORARY_REDIRECT = 307, BALDE_HTTP_BAD_REQUEST = 400, BALDE_HTTP_UNAUTHORIZED = 401, BALDE_HTTP_FORBIDDEN = 403, BALDE_HTTP_NOT_FOUND = 404, BALDE_HTTP_METHOD_NOT_ALLOWED = 405, BALDE_HTTP_NOT_ACCEPTABLE = 406, BALDE_HTTP_REQUEST_TIMEOUT = 408, BALDE_HTTP_CONFLICT = 409, BALDE_HTTP_GONE = 410, BALDE_HTTP_LENGTH_REQUIRED = 411, BALDE_HTTP_PRECONDITION_FAILED = 412, BALDE_HTTP_REQUEST_ENTITY_TOO_LARGE = 413, BALDE_HTTP_REQUEST_URI_TOO_LONG = 414, BALDE_HTTP_UNSUPPORTED_MEDIA_TYPE = 415, BALDE_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416, BALDE_HTTP_EXPECTATION_FAILED = 417, BALDE_HTTP_I_M_A_TEAPOT = 418, BALDE_HTTP_UNPROCESSABLE_ENTITY = 422, BALDE_HTTP_PRECONDITION_REQUIRED = 428, BALDE_HTTP_TOO_MANY_REQUESTS = 429, BALDE_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431, BALDE_HTTP_INTERNAL_SERVER_ERROR = 500, BALDE_HTTP_NOT_IMPLEMENTED = 501, BALDE_HTTP_BAD_GATEWAY = 502, BALDE_HTTP_SERVICE_UNAVAILABLE = 503 }
	Supported HTTP status codes. More...

Functions
balde_app_t *	balde_app_init (void)
	Initializes the application context. More...

void	balde_app_set_config (balde_app_t app, const gchar name, const gchar *value)
	Sets a configuration parameter. More...

void	balde_app_set_config_from_envvar (balde_app_t app, const gchar name, const gchar *env_name, gboolean silent)
	Sets a configuration parameter with the value of an environment variable. More...

const gchar *	balde_app_get_config (balde_app_t app, const gchar name)
	Gets a configuration parameter. More...

void	balde_app_set_user_data (balde_app_t *app, gpointer user_data)
	Sets user data. More...

gpointer	balde_app_get_user_data (balde_app_t *app)
	Gets user data.

void	balde_app_set_user_data_destroy_func (balde_app_t *app, GDestroyNotify destroy_func)
	Sets user data destroy function. More...

void	balde_app_free_user_data (balde_app_t *app)
	Free memory allocated for user data. More...

void	balde_app_free (balde_app_t *app)
	Free application context memory. More...

void	balde_app_add_url_rule (balde_app_t app, const gchar endpoint, const gchar *rule, const balde_http_method_t method, balde_view_func_t view_func)
	Adds a view to the balde application. More...

void	balde_app_add_before_request (balde_app_t *app, balde_before_request_func_t hook_func)
	Adds a "before request" hook to the balde application. More...

gchar *	balde_app_url_for (balde_app_t app, balde_request_t request, const gchar *endpoint, gboolean external,...)
	Helper function to get the URL for a given endpoint. More...

void	balde_app_run (balde_app_t app, gint argc, gchar *argv)
	Application main loop. More...

void	balde_response_set_header (balde_response_t response, const gchar name, const gchar *value)
	Sets a response header. More...

void	balde_response_set_etag_header (balde_response_t *response, gboolean weak)
	Sets a response ETag header for the current content of the response. More...

void	balde_response_etag_matching (balde_request_t request, balde_response_t response)
	Check if response matches a sent etag header and change response to be blank and change response code to 304 Not Modified.

void	balde_response_append_body (balde_response_t response, const gchar content)
	Appends a nul-terminated string to the response body.

void	balde_response_append_body_len (balde_response_t response, const gchar content, const gssize len)
	Appends a string to the response body, with specific length.

void	balde_response_truncate_body (balde_response_t *response)
	Truncate response's body.

balde_response_t *	balde_make_response (const gchar *content)
	Initialize a response context. More...

balde_response_t *	balde_make_response_len (const gchar *content, const gssize len)
	Initialize a response context with specific length. More...

void	balde_response_set_tmpl_var (balde_response_t response, const gchar name, const gchar *value)
	Sets a template variable. More...

const gchar *	balde_response_get_tmpl_var (balde_response_t response, const gchar name)
	Gets a template variable. More...

const gchar *	balde_response_get_tmpl_var_or_empty (balde_response_t response, const gchar name)
	Gets a template variable and returns an empty string, if not found. More...

void	balde_response_set_cookie (balde_response_t response, const gchar name, const gchar value, const gint max_age, const gint64 expires, const gchar path, const gchar *domain, const gboolean secure, const gboolean http_only)
	Sets a cookie. More...

void	balde_response_delete_cookie (balde_response_t response, const gchar name, const gchar path, const gchar domain)
	Deletes a cookie from client. More...

const gchar *	balde_request_get_header (balde_request_t request, const gchar name)
	Gets a request header. More...

const gchar *	balde_request_get_arg (balde_request_t request, const gchar name)
	Gets a query string argument. More...

const gchar *	balde_request_get_form (balde_request_t request, const gchar name)
	Gets a form input value. More...

const balde_file_t *	balde_request_get_file (balde_request_t request, const gchar name)
	Gets a file uploaded. More...

const gchar *	balde_request_get_view_arg (balde_request_t request, const gchar name)
	Gets a view argument. More...

const gchar *	balde_request_get_cookie (balde_request_t request, const gchar name)
	Gets a cookie. More...

const GString *	balde_request_get_body (balde_request_t *request)
	Gets the request body. More...

gchar *	balde_file_save_to_disk (const balde_file_t file, const gchar destdir, const gchar *name)
	Saves a file to disk. More...

void	balde_abort_set_error (balde_app_t *app, const balde_http_exception_code_t code)
	Sets application error with an HTTP status code. More...

void	balde_abort_set_error_with_description (balde_app_t app, const balde_http_exception_code_t code, const gchar description)
	Sets application error with an HTTP status code and custom description. More...

balde_response_t *	balde_abort (balde_app_t *app, const balde_http_exception_code_t code)
	Returns a response context that represents an HTTP status code. More...

balde_response_t *	balde_abort_with_description (balde_app_t app, const balde_http_exception_code_t code, const gchar description)
	Returns a response context that represents an HTTP status code with custom description. More...

void	balde_session_open (balde_app_t app, balde_request_t request)
	Initializes an HTTP session context. More...

void	balde_session_save (balde_request_t request, balde_response_t response)
	Saves an HTTP session context and attaches it to a response context. More...

const gchar *	balde_session_get (balde_request_t request, const gchar key)
	Gets a value from an HTTP session context. More...

void	balde_session_set (balde_request_t request, const gchar key, const gchar *value)
	Sets a value into an HTTP session context. More...

void	balde_session_delete (balde_request_t request, const gchar key)
	Deletes a value from an HTTP session context. More...

void	balde_resources_load (balde_app_t app, GResource resources)
	Load static resources. More...

gchar *	balde_tmpl_url_for (balde_app_t app, balde_request_t request, const gchar *endpoint, gboolean external,...)
	Template helper to get the URL for a given endpoint. More...

Detailed Description

balde public API.

This document describes the public API exposed by balde, to be used by applications.

Typedef Documentation

typedef void(* balde_before_request_func_t) (balde_app_t *, balde_request_t *)

"Before request" hook type definition

Each hook should accept the application context and the request context.

typedef balde_response_t*(* balde_view_func_t) (balde_app_t *, balde_request_t *)

View type definition.

Each view should accept the application context and the request context, and return a response context.

Enumeration Type Documentation

enum balde_http_exception_code_t

Supported HTTP status codes.

These are the HTTP status codes that are supported by the balde_abort_* functions. To support any other methods, they must be added to the source code.

enum balde_http_method_t

Supported HTTP methods.

BALDE_HTTP_NONE and BALDE_HTTP_ANY are special methods, that will set the view to do not accept any request method or to accept any request method, respectively.

Function Documentation

balde_response_t* balde_abort	(	balde_app_t *	app,
		const balde_http_exception_code_t	code
	)

Returns a response context that represents an HTTP status code.

This function returns the response, but does not sets the GLib error.

void balde_abort_set_error	(	balde_app_t *	app,
		const balde_http_exception_code_t	code
	)

Sets application error with an HTTP status code.

It is called "error" to be consistent with GLib naming standards, but it works like an exception.

void balde_abort_set_error_with_description	(	balde_app_t *	app,
		const balde_http_exception_code_t	code,
		const gchar *	description
	)

Sets application error with an HTTP status code and custom description.

It is called "error" to be consistent with GLib naming standards, but it works like an exception.

balde_response_t* balde_abort_with_description	(	balde_app_t *	app,
		const balde_http_exception_code_t	code,
		const gchar *	description
	)

Returns a response context that represents an HTTP status code with custom description.

This function returns the response, but does not sets the GLib error.

void balde_app_add_before_request	(	balde_app_t *	app,
		balde_before_request_func_t	hook_func
	)

Adds a "before request" hook to the balde application.

void balde_app_add_url_rule	(	balde_app_t *	app,
		const gchar *	endpoint,
		const gchar *	rule,
		const balde_http_method_t	method,
		balde_view_func_t	view_func
	)

Adds a view to the balde application.

The endpoint should be unique, and multiple methods can be provided with pipes.

Examples:: hello-with-cookies.c, hello-with-form.c, hello-with-template.c, hello-with-url_for.c, and hello.c.

void balde_app_free ( balde_app_t * app )

Free application context memory.

This function will clean and free all memory used by the application context.

Examples:: hello-with-cookies.c, hello-with-form.c, hello-with-static.c, hello-with-template.c, hello-with-url_for.c, and hello.c.

void balde_app_free_user_data ( balde_app_t * app )

Free memory allocated for user data.

This function depends on a destroy function being provided through balde_app_set_user_data_destroy_func() function.

const gchar* balde_app_get_config	(	balde_app_t *	app,
		const gchar *	name
	)

Gets a configuration parameter.

The parameter name is case-insensitive.

balde_app_t* balde_app_init ( void )

Initializes the application context.

This function allocates memory for the application context.

Examples:: hello-with-cookies.c, hello-with-form.c, hello-with-static.c, hello-with-template.c, hello-with-url_for.c, and hello.c.

void balde_app_run	(	balde_app_t *	app,
		gint	argc,
		gchar **	argv
	)

Application main loop.

This function does everything needed to run the registered views and dispatch requests.

Examples:: hello-with-cookies.c, hello-with-form.c, hello-with-static.c, hello-with-template.c, hello-with-url_for.c, and hello.c.

void balde_app_set_config	(	balde_app_t *	app,
		const gchar *	name,
		const gchar *	value
	)

Sets a configuration parameter.

The parameter name is case-insensitive.

void balde_app_set_config_from_envvar	(	balde_app_t *	app,
		const gchar *	name,
		const gchar *	env_name,
		gboolean	silent
	)

Sets a configuration parameter with the value of an environment variable.

The parameter name is case-insensitive, but the parameter env_name is case sensitive.

If the parameter silent is false, this function will raise an error if the environment variable isn't found or is NULL.

void balde_app_set_user_data	(	balde_app_t *	app,
		gpointer	user_data
	)

Sets user data.

The memory needed by the user provided data should be allocated previously, and free'd afterwards, unless you provide a destroy function with balde_app_set_user_data_destroy_func(). If you do not provides a destroy function and call this function twice, it will probably results in a memory leak.

void balde_app_set_user_data_destroy_func	(	balde_app_t *	app,
		GDestroyNotify	destroy_func
	)

Sets user data destroy function.

This function sets the destroy function that will be used by balde to free memory allocated for user data when freeing/setting new values for it.

gchar* balde_app_url_for	(	balde_app_t *	app,
		balde_request_t *	request,
		const gchar *	endpoint,
		gboolean	external,
			...
	)

Helper function to get the URL for a given endpoint.

You should pass the exact number of parameters expected by the view's URL rule.

The 'external' parameter isn't implemented yet, but is planned on the API. If set to TRUE, the function will return an absolute URL.

gchar* balde_file_save_to_disk	(	const balde_file_t *	file,
		const gchar *	destdir,
		const gchar *	name
	)

Saves a file to disk.

destdir is the path of the destination directory, that must exists before this function call. if name is NULL, the default name element of the file structure will be used.

Returns the path of the file saved on disk or NULL on errors.

balde_response_t* balde_make_response ( const gchar * content )

Initialize a response context.

The nul-terminated string passed as argument is used to initialize the response body. Please use an empty string if the response doesn't have body, instead of NULL.

Examples:: hello-with-cookies.c, hello-with-form.c, hello-with-template.c, hello-with-url_for.c, and hello.c.

balde_response_t* balde_make_response_len	(	const gchar *	content,
		const gssize	len
	)

Initialize a response context with specific length.

The string passed as argument is used to initialize the response body. The string size must be passed as the second argument. The string need not to be nul-terminated.

const gchar* balde_request_get_arg	(	balde_request_t *	request,
		const gchar *	name
	)

Gets a query string argument.

The argument name IS case-sensitive.

Examples:: hello-with-template.c.

const GString* balde_request_get_body ( balde_request_t * request )

Gets the request body.

It returns NULL if no body was processed, and a GString otherwise.

const gchar* balde_request_get_cookie	(	balde_request_t *	request,
		const gchar *	name
	)

Gets a cookie.

The argument name IS case-sensitive.

Examples:: hello-with-cookies.c.

const balde_file_t* balde_request_get_file	(	balde_request_t *	request,
		const gchar *	name
	)

Gets a file uploaded.

The form input name name IS case-sensitive, and the function will always return NULL for HTTP methods that does not accepts request body.

const gchar* balde_request_get_form	(	balde_request_t *	request,
		const gchar *	name
	)

Gets a form input value.

The form input name IS case-sensitive, and the function will always return NULL for HTTP methods that does not accepts request body.

Examples:: hello-with-form.c.

const gchar* balde_request_get_header	(	balde_request_t *	request,
		const gchar *	name
	)

Gets a request header.

The header name is case-insensitive.

const gchar* balde_request_get_view_arg	(	balde_request_t *	request,
		const gchar *	name
	)

Gets a view argument.

The argument name IS case-sensitive.

Examples:: hello-with-url_for.c.

void balde_resources_load	(	balde_app_t *	app,
		GResource *	resources
	)

Load static resources.

This function loads all the resources found in a GResource object into the application context.

Examples:: hello-with-static.c.

void balde_response_delete_cookie	(	balde_response_t *	response,
		const gchar *	name,
		const gchar *	path,
		const gchar *	domain
	)

Deletes a cookie from client.

The same arguments provided when setting the cookie should be provided when deleted (if required).

const gchar* balde_response_get_tmpl_var	(	balde_response_t *	response,
		const gchar *	name
	)

Gets a template variable.

The template variable name IS case-sensitive.

const gchar* balde_response_get_tmpl_var_or_empty	(	balde_response_t *	response,
		const gchar *	name
	)

Gets a template variable and returns an empty string, if not found.

The template variable name IS case-sensitive.

void balde_response_set_cookie	(	balde_response_t *	response,
		const gchar *	name,
		const gchar *	value,
		const gint	max_age,
		const gint64	expires,
		const gchar *	path,
		const gchar *	domain,
		const gboolean	secure,
		const gboolean	http_only
	)

Sets a cookie.

Integer arguments should be set to -1 to be ignored. String arguments (excluding name and value) should be set to NULL to be ignored.

If the 'expires' argument is less than 0 and 'max_age' is provided, it will be evaluated automatically for you.

Changed in 0.2: added HttpOnly support.

Examples:: hello-with-cookies.c.

void balde_response_set_etag_header	(	balde_response_t *	response,
		gboolean	weak
	)

Sets a response ETag header for the current content of the response.

This function should be only used when the response content is ready to be sent to the client, as it can't be overridden later.

void balde_response_set_header	(	balde_response_t *	response,
		const gchar *	name,
		const gchar *	value
	)

Sets a response header.

The header name is case-insensitive.

void balde_response_set_tmpl_var	(	balde_response_t *	response,
		const gchar *	name,
		const gchar *	value
	)

Sets a template variable.

The template variable name IS case-sensitive.

Examples:: hello-with-form.c, and hello-with-template.c.

void balde_session_delete	(	balde_request_t *	request,
		const gchar *	key
	)

Deletes a value from an HTTP session context.

const gchar* balde_session_get	(	balde_request_t *	request,
		const gchar *	key
	)

Gets a value from an HTTP session context.

void balde_session_open	(	balde_app_t *	app,
		balde_request_t *	request
	)

Initializes an HTTP session context.

void balde_session_save	(	balde_request_t *	request,
		balde_response_t *	response
	)

Saves an HTTP session context and attaches it to a response context.

void balde_session_set	(	balde_request_t *	request,
		const gchar *	key,
		const gchar *	value
	)

Sets a value into an HTTP session context.

gchar* balde_tmpl_url_for	(	balde_app_t *	app,
		balde_request_t *	request,
		const gchar *	endpoint,
		gboolean	external,
			...
	)

Template helper to get the URL for a given endpoint.

You should pass the exact number of parameters expected by the view's URL rule.

The 'external' parameter isn't implemented yet, but is planned on the API. If set to TRUE, the function will return an absolute URL.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation