balde  0.1.2.350-aca7
A microframework for C based on GLib and bad intentions.
balde.h File Reference

balde public API. More...

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

Go to the source code of this file.

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_tbalde_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_tbalde_make_response (const gchar *content)
 Initialize a response context. More...
 
balde_response_tbalde_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_tbalde_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_tbalde_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_tbalde_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

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.

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.