1 #ifndef DB_H
    2 #define DB_H
    3 
    4 /*
    5  * WARNING: automatically generated by kwebapp 0.4.12.
    6  * DO NOT EDIT!
    7  */
    8 
    9 #define KWBP_VERSION "0.4.12"
   10 #define KWBP_VSTAMP 10513
   11 
   12 /*
   13  * Our roles for access control.
   14  * When the database is first opened, the system is set to 
   15  * ROLE_default.
   16  * Roles may then be set using the kwbp_role() function.
   17  */
   18 enum	kwbp_role {
   19 	/* Role that isn't allowed to do anything. */
   20 	ROLE_none,
   21 	/*
   22 	 * The default role.
   23 	 * This is assigned when db_open() is called.
   24 	 * It should be limited only to those functions required to narrow 
   25 	 * the role.
   26 	 */
   27 	ROLE_default,
   28 	ROLE_user,
   29 	ROLE_admin
   30 };
   31 
   32 struct	user {
   33 	char	*email;
   34 	char	*hash;
   35 	int64_t	 id;
   36 	/* Private data used for role analysis. */
   37 	struct kwbp_store *priv_store;
   38 };
   39 
   40 struct	session {
   41 	struct user user;
   42 	/* User associated with session. */
   43 	int64_t	 userid;
   44 	int64_t	 id;
   45 	/* Private data used for role analysis. */
   46 	struct kwbp_store *priv_store;
   47 };
   48 
   49 /*
   50  * All of the fields we validate.
   51  * These are as VALID_XXX_YYY, where XXX is the structure and YYY is the 
   52  * field.
   53  * Only native types are listed.
   54  */
   55 enum	valid_keys {
   56 	VALID_USER_EMAIL,
   57 	VALID_USER_HASH,
   58 	VALID_USER_ID,
   59 	VALID_SESSION_USERID,
   60 	VALID_SESSION_ID,
   61 	VALID__MAX
   62 };
   63 
   64 /*
   65  * Validation fields.
   66  * Pass this directly into khttp_parse(3) to use them as-is.
   67  * The functions are "valid_xxx_yyy", where "xxx" is the struct and "yyy" 
   68  * the field, and can be used standalone.
   69  * The form inputs are named "xxx-yyy".
   70  */
   71 extern const struct kvalid valid_keys[VALID__MAX];
   72 
   73 __BEGIN_DECLS
   74 
   75 /*
   76  * Allocate and open the database in "file". This opens the database in 
   77  * "safe exit" mode (see ksql(3)).
   78  * Note: if you're using a sandbox, you must accommodate for the SQLite 
   79  * database within process memory.
   80  * Returns an opaque pointer or NULL on memory exhaustion.
   81  * The returned pointer must be closed with db_close().
   82  */
   83 struct kwbp *db_open(const char *file);
   84 
   85 /*
   86  * Open a transaction with identifier "id".
   87  * If "mode" is 0, the transaction is opened in "deferred" mode, meaning 
   88  * that the database is read-locked (no writes allowed) on the first read 
   89  * operation, and write-locked on the first write (only the current 
   90  * process can write).
   91  * If "mode" is >0, the transaction immediately starts a write-lock.
   92  * If "mode" is <0, the transaction starts in a write-pending, where no 
   93  * other locks can be held at the same time.
   94  */
   95 void db_trans_open(struct kwbp *p, size_t id, int mode);
   96 
   97 /*
   98  * Roll-back an open transaction.
   99  */
  100 void db_trans_rollback(struct kwbp *p, size_t id);
  101 
  102 /*
  103  * Commit an open transaction.
  104  */
  105 void db_trans_commit(struct kwbp *p, size_t id);
  106 
  107 /*
  108  * Close the context opened by db_open().
  109  * Has no effect if "p" is NULL.
  110  */
  111 void db_close(struct kwbp *p);
  112 
  113 /*
  114  * Drop into a new role.
  115  * If the role is the same as the current one, this is a noop.
  116  * We can only refine roles (i.e., descend the role tree), not ascend or 
  117  * move laterally.
  118  * Attempting to do so causes abort(2) to be called.
  119  * The only exceptions are when leaving ROLE_default or when entering 
  120  * ROLE_none.
  121  */
  122 void db_role(struct kwbp *ctx, enum kwbp_role r);
  123 
  124 /*
  125  * Get the current role.
  126  */
  127 enum kwbp_role db_role_current(struct kwbp *ctx);
  128 
  129 /*
  130  * Get the role stored into "s".
  131  * This role is set when the object containing the stored role is 
  132  * created, such as when a "search" query function is called.
  133  */
  134 enum kwbp_role db_role_stored(struct kwbp_store *s);
  135 
  136 /*
  137  * Unfill resources and free "p".
  138  * Has no effect if "p" is NULL.
  139  */
  140 void db_user_free(struct user *p);
  141 
  142 /*
  143  * Lookup by credentials.
  144  * Queries on the following fields in struct user:
  145  * 	v1: email (equals)
  146  * 	v2: hash (pre-hashed password)
  147  * Returns a pointer or NULL on fail.
  148  * Free the pointer with db_user_free().
  149  */
  150 struct user *db_user_get_creds(struct kwbp *ctx, const char *v1, const char *v2);
  151 
  152 /*
  153  * Unfill resources and free "p".
  154  * Has no effect if "p" is NULL.
  155  */
  156 void db_session_free(struct session *p);
  157 
  158 /*
  159  * Insert a new row into the database.
  160  * Only native (and non-rowid) fields may be set.
  161  * 	v1: userid
  162  * Returns the new row's identifier on success or <0 otherwise.
  163  */
  164 int64_t db_session_insert(struct kwbp *ctx, int64_t v1);
  165 
  166 /*
  167  * Lookup by unique identifier.
  168  * Queries on the following fields in struct session:
  169  * 	v1: id (equals)
  170  * Returns a pointer or NULL on fail.
  171  * Free the pointer with db_session_free().
  172  */
  173 struct session *db_session_get_id(struct kwbp *ctx, int64_t v1);
  174 
  175 /*
  176  * Constrains the deleted records to:
  177  * 	v1: id (equals)
  178  * Returns zero on failure, non-zero on constraint errors.
  179  */
  180 int db_session_delete_by_id_eq(struct kwbp *ctx, int64_t v1);
  181 
  182 /*
  183  * Print out the fields of a user in JSON including nested 
  184  * structures.
  185  * Omits any password entries or those marked "noexport".
  186  * See json_user_obj() for the full object.
  187  */
  188 void json_user_data(struct kjsonreq *r, const struct user *p);
  189 
  190 /*
  191  * Emit the JSON key-value pair for the object:
  192  * 	"user" : { [data]+ }
  193  * See json_user_data() for the data.
  194  */
  195 void json_user_obj(struct kjsonreq *r, const struct user *p);
  196 
  197 /*
  198  * Print out the fields of a session in JSON including nested 
  199  * structures.
  200  * Omits any password entries or those marked "noexport".
  201  * See json_session_obj() for the full object.
  202  */
  203 void json_session_data(struct kjsonreq *r, const struct session *p);
  204 
  205 /*
  206  * Emit the JSON key-value pair for the object:
  207  * 	"session" : { [data]+ }
  208  * See json_session_data() for the data.
  209  */
  210 void json_session_obj(struct kjsonreq *r, const struct session *p);
  211 
  212 /*
  213  * Validation routines for the email field in struct user.
  214  */
  215 int valid_user_email(struct kpair *p);
  216 
  217 /*
  218  * Validation routines for the hash field in struct user.
  219  */
  220 int valid_user_hash(struct kpair *p);
  221 
  222 /*
  223  * Validation routines for the id field in struct user.
  224  */
  225 int valid_user_id(struct kpair *p);
  226 
  227 /*
  228  * Validation routines for the user field in struct session.
  229  */
  230 int valid_session_user(struct kpair *p);
  231 
  232 /*
  233  * Validation routines for the userid field in struct session.
  234  */
  235 int valid_session_userid(struct kpair *p);
  236 
  237 /*
  238  * Validation routines for the id field in struct session.
  239  */
  240 int valid_session_id(struct kpair *p);
  241 
  242 __END_DECLS
  243 
  244 #endif