1 #ifndef DB_H
    2 #define DB_H
    3 
    4 /*
    5  * WARNING: automatically generated by kwebapp 0.6.0.
    6  * DO NOT EDIT!
    7  */
    8 
    9 #define KWBP_VERSION "0.6.0"
   10 #define KWBP_VSTAMP 10701
   11 
   12 /*
   13  * Birthsex of individual
   14  */
   15 enum	sex {
   16 	/* Male */
   17 	SEX_male = 0,
   18 	/* Female */
   19 	SEX_female = 1,
   20 	/* Other */
   21 	SEX_other = 2
   22 };
   23 
   24 /*
   25  * Controlling organisation.
   26  */
   27 struct	company {
   28 	/* Name of the organisation. */
   29 	char	*name;
   30 	int64_t	 id;
   31 	/* Simply a check for null values. */
   32 	int64_t	 somenum;
   33 	/* Non-zero if "somenum" field is null/unset. */
   34 	int has_somenum;
   35 	TAILQ_ENTRY(company) _entries;
   36 };
   37 
   38 /*
   39  * Queue of company for listings.
   40  */
   41 TAILQ_HEAD(company_q, company);
   42 
   43 /*
   44  * A regular user.
   45  */
   46 struct	user {
   47 	/*
   48 	 * This struct will be filled in from an inner join
   49 	 * on the "cid" variable.
   50 	 */
   51 	struct company company;
   52 	/* A foreign key reference. */
   53 	int64_t	 cid;
   54 	/* User's birth sex. */
   55 	enum sex sex;
   56 	/*
   57 	 * Password hash.
   58 	 * This is passed to inserts and updates as a password,
   59 	 * then hashed within the implementation and extracted
   60 	 * (in listings and searches) as the hash value.
   61 	 */
   62 	char	*hash;
   63 	/* Unique e-mail address. */
   64 	char	*email;
   65 	/* A PNG image or something. */
   66 	void	*image;
   67 	size_t	 image_sz;
   68 	/* User's full name. */
   69 	char	*name;
   70 	int64_t	 uid;
   71 	/* Non-zero if "image" field is null/unset. */
   72 	int has_image;
   73 };
   74 
   75 /*
   76  * Callback of user for iteration.
   77  * The arg parameter is the opaque pointer passed into the iterate 
   78  * function.
   79  */
   80 typedef void (*user_cb)(const struct user *v, void *arg);
   81 
   82 /*
   83  * Authenticated session.
   84  */
   85 struct	session {
   86 	struct user user;
   87 	/* Associated user. */
   88 	int64_t	 userid;
   89 	/* Random cookie. */
   90 	int64_t	 token;
   91 	time_t	 mtime;
   92 	int64_t	 id;
   93 };
   94 
   95 /*
   96  * Callback of session for iteration.
   97  * The arg parameter is the opaque pointer passed into the iterate 
   98  * function.
   99  */
  100 typedef void (*session_cb)(const struct session *v, void *arg);
  101 
  102 /*
  103  * Define our table columns.
  104  * Use these when creating your own SQL statements, combined with the 
  105  * db_xxxx_fill functions.
  106  * Each macro must be given a unique alias name.
  107  * This allows for doing multiple inner joins on the same table.
  108  */
  109 #define DB_SCHEMA_COMPANY(_x) \
  110 	#_x ".name" "," \
  111 	#_x ".id" "," \
  112 	#_x ".somenum"
  113 #define DB_SCHEMA_USER(_x) \
  114 	#_x ".cid" "," \
  115 	#_x ".sex" "," \
  116 	#_x ".hash" "," \
  117 	#_x ".email" "," \
  118 	#_x ".image" "," \
  119 	#_x ".name" "," \
  120 	#_x ".uid"
  121 #define DB_SCHEMA_SESSION(_x) \
  122 	#_x ".userid" "," \
  123 	#_x ".token" "," \
  124 	#_x ".mtime" "," \
  125 	#_x ".id"
  126 
  127 /*
  128  * All of the fields we validate.
  129  * These are as VALID_XXX_YYY, where XXX is the structure and YYY is the 
  130  * field.
  131  * Only native types are listed.
  132  */
  133 enum	valid_keys {
  134 	VALID_COMPANY_NAME,
  135 	VALID_COMPANY_ID,
  136 	VALID_COMPANY_SOMENUM,
  137 	VALID_USER_CID,
  138 	VALID_USER_SEX,
  139 	VALID_USER_HASH,
  140 	VALID_USER_EMAIL,
  141 	VALID_USER_IMAGE,
  142 	VALID_USER_NAME,
  143 	VALID_USER_UID,
  144 	VALID_SESSION_USERID,
  145 	VALID_SESSION_TOKEN,
  146 	VALID_SESSION_MTIME,
  147 	VALID_SESSION_ID,
  148 	VALID__MAX
  149 };
  150 
  151 /*
  152  * Validation fields.
  153  * Pass this directly into khttp_parse(3) to use them as-is.
  154  * The functions are "valid_xxx_yyy", where "xxx" is the struct and "yyy" 
  155  * the field, and can be used standalone.
  156  * The form inputs are named "xxx-yyy".
  157  */
  158 extern const struct kvalid valid_keys[VALID__MAX];
  159 
  160 __BEGIN_DECLS
  161 
  162 /*
  163  * Allocate and open the database in "file". This opens the database in 
  164  * "safe exit" mode (see ksql(3)).
  165  * Note: the database has been opened in a child process, so the 
  166  * application may be sandboxed liberally.
  167  * Returns a pointer to the database or NULL on memory exhaustion.
  168  * The returned pointer must be closed with db_close().
  169  */
  170 struct ksql *db_open(const char *file);
  171 
  172 /*
  173  * Open a transaction with identifier "id".
  174  * If "mode" is 0, the transaction is opened in "deferred" mode, meaning 
  175  * that the database is read-locked (no writes allowed) on the first read 
  176  * operation, and write-locked on the first write (only the current 
  177  * process can write).
  178  * If "mode" is >0, the transaction immediately starts a write-lock.
  179  * If "mode" is <0, the transaction starts in a write-pending, where no 
  180  * other locks can be held at the same time.
  181  */
  182 void db_trans_open(struct ksql *p, size_t id, int mode);
  183 
  184 /*
  185  * Roll-back an open transaction.
  186  */
  187 void db_trans_rollback(struct ksql *p, size_t id);
  188 
  189 /*
  190  * Commit an open transaction.
  191  */
  192 void db_trans_commit(struct ksql *p, size_t id);
  193 
  194 /*
  195  * Close the context opened by db_open().
  196  * Has no effect if "p" is NULL.
  197  */
  198 void db_close(struct ksql *p);
  199 
  200 /*
  201  * Unfill resources and free "p".
  202  * Has no effect if "p" is NULL.
  203  */
  204 void db_company_free(struct company *p);
  205 
  206 /*
  207  * Unfill and free all queue members.
  208  * Has no effect if "q" is NULL.
  209  */
  210 void db_company_freeq(struct company_q *q);
  211 
  212 /*
  213  * Fill in a company from an open statement "stmt".
  214  * This starts grabbing results from "pos", which may be NULL to start 
  215  * from zero.
  216  * This follows DB_SCHEMA_COMPANY's order for columns.
  217  */
  218 void db_company_fill(struct company *p, struct ksqlstmt *stmt, size_t *pos);
  219 
  220 /*
  221  * Free memory allocated by db_company_fill().
  222  * Has not effect if "p" is NULL.
  223  */
  224 void db_company_unfill(struct company *p);
  225 
  226 /*
  227  * Insert a new row into the database.
  228  * Only native (and non-rowid) fields may be set.
  229  * 	v1: name
  230  * 	v2: somenum
  231  * Returns the new row's identifier on success or <0 otherwise.
  232  */
  233 int64_t db_company_insert(struct ksql *db, const char *v1, int64_t *v2);
  234 
  235 /*
  236  * Search for a set of company.
  237  * Queries on the following fields in struct company:
  238  * 	somenum (not an argument: checked is null)
  239  * Always returns a queue pointer.
  240  * Free this with db_company_freeq().
  241  */
  242 struct company_q *db_company_list_by_somenum_isnull(struct ksql *db);
  243 
  244 /*
  245  * Unfill resources and free "p".
  246  * Has no effect if "p" is NULL.
  247  */
  248 void db_user_free(struct user *p);
  249 
  250 /*
  251  * Fill in a user from an open statement "stmt".
  252  * This starts grabbing results from "pos", which may be NULL to start 
  253  * from zero.
  254  * This follows DB_SCHEMA_USER's order for columns.
  255  */
  256 void db_user_fill(struct user *p, struct ksqlstmt *stmt, size_t *pos);
  257 
  258 /*
  259  * Free memory allocated by db_user_fill().
  260  * Has not effect if "p" is NULL.
  261  */
  262 void db_user_unfill(struct user *p);
  263 
  264 /*
  265  * Insert a new row into the database.
  266  * Only native (and non-rowid) fields may be set.
  267  * 	v1: cid
  268  * 	v2: sex
  269  * 	v3: hash (pre-hashed password)
  270  * 	v4: email
  271  * 	v5: image
  272  * 	v6: name
  273  * Returns the new row's identifier on success or <0 otherwise.
  274  */
  275 int64_t db_user_insert(struct ksql *db, int64_t v1, enum sex v2, const char *v3,
  276 	const char *v4, size_t v5_sz, const void **v5, const char *v6);
  277 
  278 /*
  279  * Create a function that searches for users by a given
  280  * name; and, when found, invokes a callback function
  281  * provided the user structure.
  282  * This callback function is called during an implicit transaction: thus, 
  283  * it should not invoke any database modifications or risk deadlock.
  284  * Queries on the following fields in struct user:
  285  * 	v1: name (equals)
  286  * Invokes the given callback with retrieved data.
  287  */
  288 void db_user_iterate_by_name_eq(struct ksql *db, user_cb cb, void *arg, const char *v1);
  289 
  290 /*
  291  * Search for a unique user with their e-mail and
  292  * password.
  293  * This is a quick way to verify that a user has entered
  294  * the correct password for logging in.
  295  * Queries on the following fields in struct user:
  296  * 	v1: email (equals)
  297  * 	v2: hash (pre-hashed password)
  298  * Returns a pointer or NULL on fail.
  299  * Free the pointer with db_user_free().
  300  */
  301 struct user *db_user_get_creds(struct ksql *db, const char *v1, const char *v2);
  302 
  303 /*
  304  * Lookup by unique identifier.
  305  * Queries on the following fields in struct user:
  306  * 	v1: uid (equals)
  307  * Returns a pointer or NULL on fail.
  308  * Free the pointer with db_user_free().
  309  */
  310 struct user *db_user_get_by_uid_eq(struct ksql *db, int64_t v1);
  311 
  312 /*
  313  * Updates the given fields in struct user:
  314  * 	v1: hash (password)
  315  * Constrains the updated records to:
  316  * 	v2: uid (equals)
  317  * Returns zero on failure, non-zero on constraint errors.
  318  */
  319 int db_user_update_hash_by_uid_eq(struct ksql *db, const char *v1, int64_t v2);
  320 
  321 /*
  322  * Updates the given fields in struct user:
  323  * 	v1: email
  324  * Constrains the updated records to:
  325  * 	v2: uid (equals)
  326  * Returns zero on failure, non-zero on constraint errors.
  327  */
  328 int db_user_update_email_by_uid_eq(struct ksql *db, const char *v1, int64_t v2);
  329 
  330 /*
  331  * Unfill resources and free "p".
  332  * Has no effect if "p" is NULL.
  333  */
  334 void db_session_free(struct session *p);
  335 
  336 /*
  337  * Fill in a session from an open statement "stmt".
  338  * This starts grabbing results from "pos", which may be NULL to start 
  339  * from zero.
  340  * This follows DB_SCHEMA_SESSION's order for columns.
  341  */
  342 void db_session_fill(struct session *p, struct ksqlstmt *stmt, size_t *pos);
  343 
  344 /*
  345  * Free memory allocated by db_session_fill().
  346  * Has not effect if "p" is NULL.
  347  */
  348 void db_session_unfill(struct session *p);
  349 
  350 /*
  351  * Insert a new row into the database.
  352  * Only native (and non-rowid) fields may be set.
  353  * 	v1: userid
  354  * 	v2: token
  355  * 	v3: mtime
  356  * Returns the new row's identifier on success or <0 otherwise.
  357  */
  358 int64_t db_session_insert(struct ksql *db, int64_t v1, int64_t v2, time_t v3);
  359 
  360 /*
  361  * Search for company's logged-in users.
  362  * This callback function is called during an implicit transaction: thus, 
  363  * it should not invoke any database modifications or risk deadlock.
  364  * Queries on the following fields in struct session:
  365  * 	v1: user.company.name (equals)
  366  * 	v2: mtime (equals)
  367  * Invokes the given callback with retrieved data.
  368  */
  369 void db_session_iterate_foo(struct ksql *db, session_cb cb, void *arg, const char *v1,
  370 	time_t v2);
  371 
  372 /*
  373  * Constrains the deleted records to:
  374  * 	v1: id (equals)
  375  * Returns zero on failure, non-zero on constraint errors.
  376  */
  377 int db_session_delete_by_id_eq(struct ksql *db, int64_t v1);
  378 
  379 /*
  380  * Print out the fields of a company in JSON including nested 
  381  * structures.
  382  * Omits any password entries or those marked "noexport".
  383  * See json_company_obj() for the full object.
  384  */
  385 void json_company_data(struct kjsonreq *r, const struct company *p);
  386 
  387 /*
  388  * Emit the JSON key-value pair for the object:
  389  * 	"company" : { [data]+ }
  390  * See json_company_data() for the data.
  391  */
  392 void json_company_obj(struct kjsonreq *r, const struct company *p);
  393 
  394 /*
  395  * Emit the JSON key-value pair for the array:
  396  * 	"company_q" : [ [{data}]+ ]
  397  * See json_company_data() for the data.
  398  */
  399 void json_company_array(struct kjsonreq *r, const struct company_q *q);
  400 
  401 /*
  402  * Print out the fields of a user in JSON including nested 
  403  * structures.
  404  * Omits any password entries or those marked "noexport".
  405  * See json_user_obj() for the full object.
  406  */
  407 void json_user_data(struct kjsonreq *r, const struct user *p);
  408 
  409 /*
  410  * Emit the JSON key-value pair for the object:
  411  * 	"user" : { [data]+ }
  412  * See json_user_data() for the data.
  413  */
  414 void json_user_obj(struct kjsonreq *r, const struct user *p);
  415 
  416 /*
  417  * Emit the object as a standalone part of (presumably) an array:
  418  * 	"{ data }
  419  * See json_user_data() for the data.
  420  * The "void" argument is taken to be a kjsonreq as if were invoked from 
  421  * an iterator.
  422  */
  423 void json_user_iterate(const struct user *p, void *arg);
  424 
  425 /*
  426  * Print out the fields of a session in JSON including nested 
  427  * structures.
  428  * Omits any password entries or those marked "noexport".
  429  * See json_session_obj() for the full object.
  430  */
  431 void json_session_data(struct kjsonreq *r, const struct session *p);
  432 
  433 /*
  434  * Emit the JSON key-value pair for the object:
  435  * 	"session" : { [data]+ }
  436  * See json_session_data() for the data.
  437  */
  438 void json_session_obj(struct kjsonreq *r, const struct session *p);
  439 
  440 /*
  441  * Emit the object as a standalone part of (presumably) an array:
  442  * 	"{ data }
  443  * See json_session_data() for the data.
  444  * The "void" argument is taken to be a kjsonreq as if were invoked from 
  445  * an iterator.
  446  */
  447 void json_session_iterate(const struct session *p, void *arg);
  448 
  449 /*
  450  * Validation routines for the name field in struct company.
  451  */
  452 int valid_company_name(struct kpair *p);
  453 
  454 /*
  455  * Validation routines for the id field in struct company.
  456  */
  457 int valid_company_id(struct kpair *p);
  458 
  459 /*
  460  * Validation routines for the somenum field in struct company.
  461  */
  462 int valid_company_somenum(struct kpair *p);
  463 
  464 /*
  465  * Validation routines for the company field in struct user.
  466  */
  467 int valid_user_company(struct kpair *p);
  468 
  469 /*
  470  * Validation routines for the cid field in struct user.
  471  */
  472 int valid_user_cid(struct kpair *p);
  473 
  474 /*
  475  * Validation routines for the sex field in struct user.
  476  */
  477 int valid_user_sex(struct kpair *p);
  478 
  479 /*
  480  * Validation routines for the hash field in struct user.
  481  */
  482 int valid_user_hash(struct kpair *p);
  483 
  484 /*
  485  * Validation routines for the email field in struct user.
  486  */
  487 int valid_user_email(struct kpair *p);
  488 
  489 /*
  490  * Validation routines for the image field in struct user.
  491  */
  492 int valid_user_image(struct kpair *p);
  493 
  494 /*
  495  * Validation routines for the name field in struct user.
  496  */
  497 int valid_user_name(struct kpair *p);
  498 
  499 /*
  500  * Validation routines for the uid field in struct user.
  501  */
  502 int valid_user_uid(struct kpair *p);
  503 
  504 /*
  505  * Validation routines for the user field in struct session.
  506  */
  507 int valid_session_user(struct kpair *p);
  508 
  509 /*
  510  * Validation routines for the userid field in struct session.
  511  */
  512 int valid_session_userid(struct kpair *p);
  513 
  514 /*
  515  * Validation routines for the token field in struct session.
  516  */
  517 int valid_session_token(struct kpair *p);
  518 
  519 /*
  520  * Validation routines for the mtime field in struct session.
  521  */
  522 int valid_session_mtime(struct kpair *p);
  523 
  524 /*
  525  * Validation routines for the id field in struct session.
  526  */
  527 int valid_session_id(struct kpair *p);
  528 
  529 __END_DECLS
  530 
  531 #endif