balde  master
A microframework for C based on GLib.
balde.h
Go to the documentation of this file.
1 /*
2  * balde: A microframework for C based on GLib.
3  * Copyright (C) 2013-2017 Rafael G. Martins <rafael@rafaelmartins.eng.br>
4  *
5  * This program can be distributed under the terms of the LGPL-2 License.
6  * See the file COPYING.
7  */
8 
9 #ifndef _BALDE_H
10 #define _BALDE_H
11 
12 #include <glib.h>
13 #include <gio/gio.h>
14 #ifdef WITH_UNIX_SOCKETS
15 #include <gio/gunixsocketaddress.h>
16 #endif
17 
18 
30 #define BALDE_LOG_DOMAIN "balde"
31 
32 #define balde_log_critical(...) \
33  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, __VA_ARGS__)
34 
35 #define balde_log_warning(...) \
36  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_WARNING, __VA_ARGS__)
37 
38 #define balde_log_message(...) \
39  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, __VA_ARGS__)
40 
41 #define balde_log_info(...) \
42  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_INFO, __VA_ARGS__)
43 
44 #define balde_log_debug(...) \
45  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, __VA_ARGS__)
46 
47 
56 typedef enum {
57  BALDE_HTTP_NONE = 0,
58  BALDE_HTTP_OPTIONS = 1 << 0,
59  BALDE_HTTP_GET = 1 << 1,
60  BALDE_HTTP_HEAD = 1 << 2,
61  BALDE_HTTP_POST = 1 << 3,
62  BALDE_HTTP_PUT = 1 << 4,
63  BALDE_HTTP_PATCH = 1 << 5,
64  BALDE_HTTP_DELETE = 1 << 6,
65  BALDE_HTTP_ANY = 0xFF,
67 
68 
77 typedef enum {
78  BALDE_HTTP_OK = 200,
79  BALDE_HTTP_MULTIPLE_CHOICES = 300,
80  BALDE_HTTP_MOVED_PERMANENTLY = 301,
81  BALDE_HTTP_FOUND = 302,
82  BALDE_HTTP_SEE_OTHER = 303,
83  BALDE_HTTP_NOT_MODIFIED = 304,
84  BALDE_HTTP_USE_PROXY = 305,
85  BALDE_HTTP_TEMPORARY_REDIRECT = 307,
86  BALDE_HTTP_BAD_REQUEST = 400,
87  BALDE_HTTP_UNAUTHORIZED = 401,
88  BALDE_HTTP_FORBIDDEN = 403,
89  BALDE_HTTP_NOT_FOUND = 404,
90  BALDE_HTTP_METHOD_NOT_ALLOWED = 405,
91  BALDE_HTTP_NOT_ACCEPTABLE = 406,
92  BALDE_HTTP_REQUEST_TIMEOUT = 408,
93  BALDE_HTTP_CONFLICT = 409,
94  BALDE_HTTP_GONE = 410,
95  BALDE_HTTP_LENGTH_REQUIRED = 411,
96  BALDE_HTTP_PRECONDITION_FAILED = 412,
97  BALDE_HTTP_REQUEST_ENTITY_TOO_LARGE = 413,
98  BALDE_HTTP_REQUEST_URI_TOO_LONG = 414,
99  BALDE_HTTP_UNSUPPORTED_MEDIA_TYPE = 415,
100  BALDE_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416,
101  BALDE_HTTP_EXPECTATION_FAILED = 417,
102  BALDE_HTTP_I_M_A_TEAPOT = 418,
103  BALDE_HTTP_UNPROCESSABLE_ENTITY = 422,
104  BALDE_HTTP_PRECONDITION_REQUIRED = 428,
105  BALDE_HTTP_TOO_MANY_REQUESTS = 429,
106  BALDE_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
107  BALDE_HTTP_INTERNAL_SERVER_ERROR = 500,
108  BALDE_HTTP_NOT_IMPLEMENTED = 501,
109  BALDE_HTTP_BAD_GATEWAY = 502,
110  BALDE_HTTP_SERVICE_UNAVAILABLE = 503,
112 
113 
122 typedef struct {
123 
128  GError *error;
129 
134  struct _balde_app_private_t *priv;
135 
140  gboolean copy;
141 
142 } balde_app_t;
143 
144 
154 typedef struct {
155 
160  const gchar* username;
161 
166  const gchar* password;
167 
168  // FIXME: Add HTTP digest support
169 
171 
172 
181 typedef struct {
182 
187  const gchar *name;
188 
193  const gchar *type;
194 
199  GString *content;
200 
201 } balde_file_t;
202 
203 
212 typedef struct {
213 
219 
224  const gchar *server_name;
225 
230  const gchar *script_name;
231 
236  const gchar *path;
237 
244 
249  gboolean https;
250 
255  struct _balde_request_private_t *priv;
256 
258 
259 
268 typedef struct {
269 
275 
280  struct _balde_response_private_t *priv;
281 
283 
284 
292 typedef balde_response_t* (*balde_view_func_t) (balde_app_t*, balde_request_t*);
293 
301 
309 
310 
317 void balde_app_set_config(balde_app_t *app, const gchar *name, const gchar *value);
318 
319 
330 void balde_app_set_config_from_envvar(balde_app_t *app, const gchar *name,
331  const gchar *env_name, gboolean silent);
332 
333 
340 const gchar* balde_app_get_config(balde_app_t *app, const gchar *name);
341 
342 
353 void balde_app_set_user_data(balde_app_t *app, gpointer user_data);
354 
355 
360 gpointer balde_app_get_user_data(balde_app_t *app);
361 
362 
371  GDestroyNotify destroy_func);
372 
373 
382 
383 
390 void balde_app_free(balde_app_t *app);
391 
392 
399 void balde_app_add_url_rule(balde_app_t *app, const gchar *endpoint,
400  const gchar *rule, const balde_http_method_t method,
401  balde_view_func_t view_func);
402 
403 
409  balde_before_request_func_t hook_func);
410 
411 
422 gchar* balde_app_url_for(balde_app_t *app, balde_request_t *request,
423  const gchar *endpoint, gboolean external, ...);
424 
425 
433 void balde_app_run(balde_app_t *app, gint argc, gchar **argv);
434 
435 
442 void balde_response_set_header(balde_response_t *response, const gchar *name,
443  const gchar *value);
444 
452  gboolean weak);
453 
459  balde_response_t *response);
460 
466  const gchar *content);
467 
468 
474  const gchar *content, const gssize len);
475 
476 
482 
483 
492 balde_response_t* balde_make_response(const gchar *content);
493 
494 
503 balde_response_t* balde_make_response_len(const gchar *content, const gssize len);
504 
505 
512 void balde_response_set_tmpl_var(balde_response_t *response, const gchar* name,
513  const gchar* value);
514 
515 
522 const gchar* balde_response_get_tmpl_var(balde_response_t *response,
523  const gchar* name);
524 
525 
533  const gchar *name);
534 
535 
548 void balde_response_set_cookie(balde_response_t *response, const gchar *name,
549  const gchar *value, const gint max_age, const gint64 expires,
550  const gchar *path, const gchar *domain, const gboolean secure,
551  const gboolean http_only);
552 
553 
561 void balde_response_delete_cookie(balde_response_t *response, const gchar *name,
562  const gchar *path, const gchar *domain);
563 
564 
571 const gchar* balde_request_get_header(balde_request_t *request,
572  const gchar *name);
573 
574 
581 const gchar* balde_request_get_arg(balde_request_t *request, const gchar *name);
582 
583 
591 const gchar* balde_request_get_form(balde_request_t *request, const gchar *name);
592 
593 
601 const balde_file_t* balde_request_get_file(balde_request_t *request, const gchar *name);
602 
603 
610 const gchar* balde_request_get_view_arg(balde_request_t *request,
611  const gchar *name);
612 
613 
620 const gchar* balde_request_get_cookie(balde_request_t *request, const gchar *name);
621 
622 
629 const GString* balde_request_get_body(balde_request_t *request);
630 
631 
642 gchar* balde_file_save_to_disk(const balde_file_t *file, const gchar *destdir,
643  const gchar *name);
644 
645 
654  const balde_http_exception_code_t code);
655 
656 
665  const balde_http_exception_code_t code, const gchar* description);
666 
667 
675  const balde_http_exception_code_t code);
676 
677 
686  const balde_http_exception_code_t code, const gchar *description);
687 
688 
693 void balde_session_open(balde_app_t *app, balde_request_t *request);
694 
695 
700 void balde_session_save(balde_request_t *request, balde_response_t *response);
701 
702 
707 const gchar* balde_session_get(balde_request_t *request, const gchar *key);
708 
709 
714 void balde_session_set(balde_request_t *request, const gchar *key, const gchar *value);
715 
716 
721 void balde_session_delete(balde_request_t *request, const gchar *key);
722 
723 
730 void balde_resources_load(balde_app_t *app, GResource *resources);
731 
732 
743 gchar* balde_tmpl_url_for(balde_app_t *app, balde_request_t *request,
744  const gchar *endpoint, gboolean external, ...);
745 
746 #endif /* _BALDE_H */
balde_request_get_header
const gchar * balde_request_get_header(balde_request_t *request, const gchar *name)
Gets a request header.
balde_app_set_user_data_destroy_func
void balde_app_set_user_data_destroy_func(balde_app_t *app, GDestroyNotify destroy_func)
Sets user data destroy function.
balde_session_delete
void balde_session_delete(balde_request_t *request, const gchar *key)
Deletes a value from an HTTP session context.
balde_response_truncate_body
void balde_response_truncate_body(balde_response_t *response)
Truncate response's body.
balde_app_add_url_rule
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.
balde_abort_set_error_with_description
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.
balde_response_delete_cookie
void balde_response_delete_cookie(balde_response_t *response, const gchar *name, const gchar *path, const gchar *domain)
Deletes a cookie from client.
balde_app_free_user_data
void balde_app_free_user_data(balde_app_t *app)
Free memory allocated for user data.
balde_session_save
void balde_session_save(balde_request_t *request, balde_response_t *response)
Saves an HTTP session context and attaches it to a response context.
balde_app_get_user_data
gpointer balde_app_get_user_data(balde_app_t *app)
Gets user data.
balde_request_get_file
const balde_file_t * balde_request_get_file(balde_request_t *request, const gchar *name)
Gets a file uploaded.
balde_app_t::priv
struct _balde_app_private_t * priv
Private structure.
Definition: balde.h:134
balde_response_set_cookie
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.
balde_abort
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.
balde_file_t::content
GString * content
File content.
Definition: balde.h:199
balde_session_open
void balde_session_open(balde_app_t *app, balde_request_t *request)
Initializes an HTTP session context.
balde_request_get_body
const GString * balde_request_get_body(balde_request_t *request)
Gets the request body.
balde_request_t
balde HTTP request context
Definition: balde.h:212
balde_app_set_config_from_envvar
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.
balde_http_method_t
balde_http_method_t
Supported HTTP methods.
Definition: balde.h:56
balde_http_exception_code_t
balde_http_exception_code_t
Supported HTTP status codes.
Definition: balde.h:77
balde_app_set_config
void balde_app_set_config(balde_app_t *app, const gchar *name, const gchar *value)
Sets a configuration parameter.
balde_file_save_to_disk
gchar * balde_file_save_to_disk(const balde_file_t *file, const gchar *destdir, const gchar *name)
Saves a file to disk.
balde_file_t::type
const gchar * type
File type.
Definition: balde.h:193
balde_request_get_form
const gchar * balde_request_get_form(balde_request_t *request, const gchar *name)
Gets a form input value.
balde_response_get_tmpl_var_or_empty
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.
balde_response_t::priv
struct _balde_response_private_t * priv
Private structure.
Definition: balde.h:280
balde_request_get_view_arg
const gchar * balde_request_get_view_arg(balde_request_t *request, const gchar *name)
Gets a view argument.
balde_before_request_func_t
void(* balde_before_request_func_t)(balde_app_t *, balde_request_t *)
"Before request" hook type definition
Definition: balde.h:300
balde_view_func_t
balde_response_t *(* balde_view_func_t)(balde_app_t *, balde_request_t *)
View type definition.
Definition: balde.h:292
balde_request_t::script_name
const gchar * script_name
Request script name.
Definition: balde.h:230
balde_request_get_arg
const gchar * balde_request_get_arg(balde_request_t *request, const gchar *name)
Gets a query string argument.
balde_response_t
balde HTTP response context
Definition: balde.h:268
balde_file_t::name
const gchar * name
File name.
Definition: balde.h:187
balde_session_set
void balde_session_set(balde_request_t *request, const gchar *key, const gchar *value)
Sets a value into an HTTP session context.
balde_app_add_before_request
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.
balde_response_set_etag_header
void balde_response_set_etag_header(balde_response_t *response, gboolean weak)
Sets a response ETag header for the current content of the response.
balde_response_set_tmpl_var
void balde_response_set_tmpl_var(balde_response_t *response, const gchar *name, const gchar *value)
Sets a template variable.
balde_abort_set_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.
balde_app_t::error
GError * error
Application error context.
Definition: balde.h:128
balde_app_t::copy
gboolean copy
Private field.
Definition: balde.h:140
balde_app_free
void balde_app_free(balde_app_t *app)
Free application context memory.
balde_authorization_t::username
const gchar * username
User name.
Definition: balde.h:160
balde_make_response_len
balde_response_t * balde_make_response_len(const gchar *content, const gssize len)
Initialize a response context with specific length.
balde_request_get_cookie
const gchar * balde_request_get_cookie(balde_request_t *request, const gchar *name)
Gets a cookie.
balde_app_url_for
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.
balde_authorization_t
balde HTTP authorization context.
Definition: balde.h:154
balde_response_append_body_len
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.
balde_file_t
balde file representation.
Definition: balde.h:181
balde_app_run
void balde_app_run(balde_app_t *app, gint argc, gchar **argv)
Application main loop.
balde_resources_load
void balde_resources_load(balde_app_t *app, GResource *resources)
Load static resources.
balde_authorization_t::password
const gchar * password
User password.
Definition: balde.h:166
balde_tmpl_url_for
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.
balde_app_get_config
const gchar * balde_app_get_config(balde_app_t *app, const gchar *name)
Gets a configuration parameter.
balde_request_t::priv
struct _balde_request_private_t * priv
Private structure.
Definition: balde.h:255
balde_response_append_body
void balde_response_append_body(balde_response_t *response, const gchar *content)
Appends a nul-terminated string to the response body.
balde_request_t::path
const gchar * path
Request path.
Definition: balde.h:236
balde_app_set_user_data
void balde_app_set_user_data(balde_app_t *app, gpointer user_data)
Sets user data.
balde_response_set_header
void balde_response_set_header(balde_response_t *response, const gchar *name, const gchar *value)
Sets a response header.
balde_request_t::method
balde_http_method_t method
Request HTTP method.
Definition: balde.h:243
balde_response_t::status_code
balde_http_exception_code_t status_code
HTTP response status code.
Definition: balde.h:274
balde_abort_with_description
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.
balde_app_init
balde_app_t * balde_app_init(void)
Initializes the application context.
balde_response_etag_matching
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...
balde_request_t::server_name
const gchar * server_name
Request server name.
Definition: balde.h:224
balde_response_get_tmpl_var
const gchar * balde_response_get_tmpl_var(balde_response_t *response, const gchar *name)
Gets a template variable.
balde_make_response
balde_response_t * balde_make_response(const gchar *content)
Initialize a response context.
balde_request_t::authorization
balde_authorization_t * authorization
A structure that stores the authorization data received from the client.
Definition: balde.h:218
balde_app_t
balde application context
Definition: balde.h:122
balde_session_get
const gchar * balde_session_get(balde_request_t *request, const gchar *key)
Gets a value from an HTTP session context.
balde_request_t::https
gboolean https
Request using encrypted connection.
Definition: balde.h:249