balde  master
A microframework for C based on GLib and bad intentions.
balde.h
Go to the documentation of this file.
1 /*
2  * balde: A microframework for C based on GLib and bad intentions.
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 
15 
27 #define BALDE_LOG_DOMAIN "balde"
28 
29 #define balde_log_critical(...) \
30  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, __VA_ARGS__)
31 
32 #define balde_log_warning(...) \
33  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_WARNING, __VA_ARGS__)
34 
35 #define balde_log_message(...) \
36  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, __VA_ARGS__)
37 
38 #define balde_log_info(...) \
39  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_INFO, __VA_ARGS__)
40 
41 #define balde_log_debug(...) \
42  g_log(BALDE_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, __VA_ARGS__)
43 
44 
53 typedef enum {
54  BALDE_HTTP_NONE = 0,
55  BALDE_HTTP_OPTIONS = 1 << 0,
56  BALDE_HTTP_GET = 1 << 1,
57  BALDE_HTTP_HEAD = 1 << 2,
58  BALDE_HTTP_POST = 1 << 3,
59  BALDE_HTTP_PUT = 1 << 4,
60  BALDE_HTTP_PATCH = 1 << 5,
61  BALDE_HTTP_DELETE = 1 << 6,
62  BALDE_HTTP_ANY = 0xFF,
64 
65 
74 typedef enum {
75  BALDE_HTTP_OK = 200,
76  BALDE_HTTP_MULTIPLE_CHOICES = 300,
77  BALDE_HTTP_MOVED_PERMANENTLY = 301,
78  BALDE_HTTP_FOUND = 302,
79  BALDE_HTTP_SEE_OTHER = 303,
80  BALDE_HTTP_NOT_MODIFIED = 304,
81  BALDE_HTTP_USE_PROXY = 305,
82  BALDE_HTTP_TEMPORARY_REDIRECT = 307,
83  BALDE_HTTP_BAD_REQUEST = 400,
84  BALDE_HTTP_UNAUTHORIZED = 401,
85  BALDE_HTTP_FORBIDDEN = 403,
86  BALDE_HTTP_NOT_FOUND = 404,
87  BALDE_HTTP_METHOD_NOT_ALLOWED = 405,
88  BALDE_HTTP_NOT_ACCEPTABLE = 406,
89  BALDE_HTTP_REQUEST_TIMEOUT = 408,
90  BALDE_HTTP_CONFLICT = 409,
91  BALDE_HTTP_GONE = 410,
92  BALDE_HTTP_LENGTH_REQUIRED = 411,
93  BALDE_HTTP_PRECONDITION_FAILED = 412,
94  BALDE_HTTP_REQUEST_ENTITY_TOO_LARGE = 413,
95  BALDE_HTTP_REQUEST_URI_TOO_LONG = 414,
96  BALDE_HTTP_UNSUPPORTED_MEDIA_TYPE = 415,
97  BALDE_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416,
98  BALDE_HTTP_EXPECTATION_FAILED = 417,
99  BALDE_HTTP_I_M_A_TEAPOT = 418,
100  BALDE_HTTP_UNPROCESSABLE_ENTITY = 422,
101  BALDE_HTTP_PRECONDITION_REQUIRED = 428,
102  BALDE_HTTP_TOO_MANY_REQUESTS = 429,
103  BALDE_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
104  BALDE_HTTP_INTERNAL_SERVER_ERROR = 500,
105  BALDE_HTTP_NOT_IMPLEMENTED = 501,
106  BALDE_HTTP_BAD_GATEWAY = 502,
107  BALDE_HTTP_SERVICE_UNAVAILABLE = 503,
109 
110 
119 typedef struct {
120 
125  GError *error;
126 
131  struct _balde_app_private_t *priv;
132 
137  gboolean copy;
138 
139 } balde_app_t;
140 
141 
151 typedef struct {
152 
157  const gchar* username;
158 
163  const gchar* password;
164 
165  // FIXME: Add HTTP digest support
166 
168 
169 
178 typedef struct {
179 
184  const gchar *name;
185 
190  const gchar *type;
191 
196  GString *content;
197 
198 } balde_file_t;
199 
200 
209 typedef struct {
210 
216 
221  const gchar *server_name;
222 
227  const gchar *script_name;
228 
233  const gchar *path;
234 
241 
246  gboolean https;
247 
252  struct _balde_request_private_t *priv;
253 
255 
256 
265 typedef struct {
266 
272 
277  struct _balde_response_private_t *priv;
278 
280 
281 
289 typedef balde_response_t* (*balde_view_func_t) (balde_app_t*, balde_request_t*);
290 
298 
306 
307 
314 void balde_app_set_config(balde_app_t *app, const gchar *name, const gchar *value);
315 
316 
327 void balde_app_set_config_from_envvar(balde_app_t *app, const gchar *name,
328  const gchar *env_name, gboolean silent);
329 
330 
337 const gchar* balde_app_get_config(balde_app_t *app, const gchar *name);
338 
339 
350 void balde_app_set_user_data(balde_app_t *app, gpointer user_data);
351 
352 
357 gpointer balde_app_get_user_data(balde_app_t *app);
358 
359 
368  GDestroyNotify destroy_func);
369 
370 
379 
380 
387 void balde_app_free(balde_app_t *app);
388 
389 
396 void balde_app_add_url_rule(balde_app_t *app, const gchar *endpoint,
397  const gchar *rule, const balde_http_method_t method,
398  balde_view_func_t view_func);
399 
400 
406  balde_before_request_func_t hook_func);
407 
408 
419 gchar* balde_app_url_for(balde_app_t *app, balde_request_t *request,
420  const gchar *endpoint, gboolean external, ...);
421 
422 
430 void balde_app_run(balde_app_t *app, gint argc, gchar **argv);
431 
432 
439 void balde_response_set_header(balde_response_t *response, const gchar *name,
440  const gchar *value);
441 
449  gboolean weak);
450 
456  balde_response_t *response);
457 
463  const gchar *content);
464 
465 
471  const gchar *content, const gssize len);
472 
473 
479 
480 
489 balde_response_t* balde_make_response(const gchar *content);
490 
491 
500 balde_response_t* balde_make_response_len(const gchar *content, const gssize len);
501 
502 
509 void balde_response_set_tmpl_var(balde_response_t *response, const gchar* name,
510  const gchar* value);
511 
512 
519 const gchar* balde_response_get_tmpl_var(balde_response_t *response,
520  const gchar* name);
521 
522 
530  const gchar *name);
531 
532 
545 void balde_response_set_cookie(balde_response_t *response, const gchar *name,
546  const gchar *value, const gint max_age, const gint64 expires,
547  const gchar *path, const gchar *domain, const gboolean secure,
548  const gboolean http_only);
549 
550 
558 void balde_response_delete_cookie(balde_response_t *response, const gchar *name,
559  const gchar *path, const gchar *domain);
560 
561 
568 const gchar* balde_request_get_header(balde_request_t *request,
569  const gchar *name);
570 
571 
578 const gchar* balde_request_get_arg(balde_request_t *request, const gchar *name);
579 
580 
588 const gchar* balde_request_get_form(balde_request_t *request, const gchar *name);
589 
590 
598 const balde_file_t* balde_request_get_file(balde_request_t *request, const gchar *name);
599 
600 
607 const gchar* balde_request_get_view_arg(balde_request_t *request,
608  const gchar *name);
609 
610 
617 const gchar* balde_request_get_cookie(balde_request_t *request, const gchar *name);
618 
619 
626 const GString* balde_request_get_body(balde_request_t *request);
627 
628 
639 gchar* balde_file_save_to_disk(const balde_file_t *file, const gchar *destdir,
640  const gchar *name);
641 
642 
651  const balde_http_exception_code_t code);
652 
653 
662  const balde_http_exception_code_t code, const gchar* description);
663 
664 
672  const balde_http_exception_code_t code);
673 
674 
683  const balde_http_exception_code_t code, const gchar *description);
684 
685 
690 void balde_session_open(balde_app_t *app, balde_request_t *request);
691 
692 
697 void balde_session_save(balde_request_t *request, balde_response_t *response);
698 
699 
704 const gchar* balde_session_get(balde_request_t *request, const gchar *key);
705 
706 
711 void balde_session_set(balde_request_t *request, const gchar *key, const gchar *value);
712 
713 
718 void balde_session_delete(balde_request_t *request, const gchar *key);
719 
720 
727 void balde_resources_load(balde_app_t *app, GResource *resources);
728 
729 
740 gchar* balde_tmpl_url_for(balde_app_t *app, balde_request_t *request,
741  const gchar *endpoint, gboolean external, ...);
742 
743 #endif /* _BALDE_H */
void balde_session_delete(balde_request_t *request, const gchar *key)
Deletes a value from an HTTP session context.
const gchar * balde_request_get_arg(balde_request_t *request, const gchar *name)
Gets a query string argument.
balde_http_exception_code_t status_code
HTTP response status code.
Definition: balde.h:271
void balde_abort_set_error(balde_app_t *app, const balde_http_exception_code_t code)
Sets application error with an HTTP status code.
void balde_response_etag_matching(balde_request_t *request, balde_response_t *response)
Check if response matches a sent etag header and change reponse to be blank and change response code ...
const gchar * balde_request_get_header(balde_request_t *request, const gchar *name)
Gets a request header.
GString * content
File content.
Definition: balde.h:196
void balde_session_open(balde_app_t *app, balde_request_t *request)
Initializes an HTTP session context.
void balde_app_set_user_data_destroy_func(balde_app_t *app, GDestroyNotify destroy_func)
Sets user data destroy function.
const gchar * username
User name.
Definition: balde.h:157
void balde_app_set_config(balde_app_t *app, const gchar *name, const gchar *value)
Sets a configuration parameter.
struct _balde_app_private_t * priv
Private structure.
Definition: balde.h:131
const gchar * balde_response_get_tmpl_var(balde_response_t *response, const gchar *name)
Gets a template variable.
gchar * balde_file_save_to_disk(const balde_file_t *file, const gchar *destdir, const gchar *name)
Saves a file to disk.
balde_response_t * balde_make_response(const gchar *content)
Initialize a response context.
void balde_app_free(balde_app_t *app)
Free application context memory.
const gchar * balde_request_get_cookie(balde_request_t *request, const gchar *name)
Gets a 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.
const gchar * balde_app_get_config(balde_app_t *app, const gchar *name)
Gets a configuration parameter.
void balde_response_delete_cookie(balde_response_t *response, const gchar *name, const gchar *path, const gchar *domain)
Deletes a cookie from client.
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.
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.
void balde_resources_load(balde_app_t *app, GResource *resources)
Load static resources.
const gchar * server_name
Request server name.
Definition: balde.h:221
balde_app_t * balde_app_init(void)
Initializes the application context.
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_before_request_func_t)(balde_app_t *, balde_request_t *)
"Before request" hook type definition
Definition: balde.h:297
struct _balde_request_private_t * priv
Private structure.
Definition: balde.h:252
GError * error
Application error context.
Definition: balde.h:125
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.
void balde_response_set_tmpl_var(balde_response_t *response, const gchar *name, const gchar *value)
Sets a template variable.
const gchar * type
File type.
Definition: balde.h:190
const GString * balde_request_get_body(balde_request_t *request)
Gets the request body.
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_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.
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 HTTP authorization context.
Definition: balde.h:151
const gchar * balde_request_get_form(balde_request_t *request, const gchar *name)
Gets a form input value.
void balde_app_run(balde_app_t *app, gint argc, gchar **argv)
Application main loop.
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 *(* balde_view_func_t)(balde_app_t *, balde_request_t *)
View type definition.
Definition: balde.h:289
const gchar * name
File name.
Definition: balde.h:184
balde_http_exception_code_t
Supported HTTP status codes.
Definition: balde.h:74
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 HTTP request context
Definition: balde.h:209
balde HTTP response context
Definition: balde.h:265
void balde_app_free_user_data(balde_app_t *app)
Free memory allocated for user data.
void balde_response_append_body(balde_response_t *response, const gchar *content)
Appends a nul-terminated string to the response body.
void balde_session_set(balde_request_t *request, const gchar *key, const gchar *value)
Sets a value into an HTTP session context.
const gchar * script_name
Request script name.
Definition: balde.h:227
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 representation.
Definition: balde.h:178
gboolean https
Request using encrypted connection.
Definition: balde.h:246
balde_response_t * balde_make_response_len(const gchar *content, const gssize len)
Initialize a response context with specific length.
void balde_response_truncate_body(balde_response_t *response)
Truncate response&#39;s body.
void balde_response_set_header(balde_response_t *response, const gchar *name, const gchar *value)
Sets a response header.
balde_authorization_t * authorization
A structure that stores the authorization data received from the client.
Definition: balde.h:215
void balde_app_set_user_data(balde_app_t *app, gpointer user_data)
Sets user data.
const gchar * path
Request path.
Definition: balde.h:233
const gchar * balde_request_get_view_arg(balde_request_t *request, const gchar *name)
Gets a view argument.
balde_http_method_t method
Request HTTP method.
Definition: balde.h:240
struct _balde_response_private_t * priv
Private structure.
Definition: balde.h:277
const balde_file_t * balde_request_get_file(balde_request_t *request, const gchar *name)
Gets a file uploaded.
gpointer balde_app_get_user_data(balde_app_t *app)
Gets user data.
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.
gboolean copy
Private field.
Definition: balde.h:137
void balde_session_save(balde_request_t *request, balde_response_t *response)
Saves an HTTP session context and attaches it to a response context.
const gchar * balde_session_get(balde_request_t *request, const gchar *key)
Gets a value from an HTTP session context.
balde_http_method_t
Supported HTTP methods.
Definition: balde.h:53
const gchar * password
User password.
Definition: balde.h:163
balde application context
Definition: balde.h:119