1 #ifndef DB_H
    2 #define DB_H
    3 
    4 /*
    5  * WARNING: automatically generated by ort-c-header 0.8.5.
    6  * DO NOT EDIT!
    7  */
    8 
    9 #ifndef KWBP_VERSION
   10 # define KWBP_VERSION "0.8.5"
   11 #endif
   12 #ifndef KWBP_VSTAMP
   13 # define KWBP_VSTAMP 10906
   14 #endif
   15 
   16 /*
   17  * Our roles for access control.
   18  * When the database is first opened, the system is set to ROLE_default.
   19  * Roles may then be set using the ort_role() function.
   20  */
   21 enum	ort_role {
   22 	/* Role that isn't allowed to do anything. */
   23 	ROLE_none,
   24 	/*
   25 	 * The default role.
   26 	 * This is assigned when db_open() is called.
   27 	 * It should be limited only to those functions required to narrow 
   28 	 * the role.
   29 	 */
   30 	ROLE_default,
   31 	ROLE_user,
   32 	ROLE_admin
   33 };
   34 
   35 struct	user {
   36 	char	*email;
   37 	char	*hash;
   38 	int64_t	 id;
   39 	/* Private data used for role analysis. */
   40 	struct ort_store *priv_store;
   41 };
   42 
   43 struct	session {
   44 	struct user user;
   45 	/* User associated with session. */
   46 	int64_t	 userid;
   47 	int64_t	 id;
   48 	/* Private data used for role analysis. */
   49 	struct ort_store *priv_store;
   50 };
   51 
   52 /*
   53  * All of the fields we validate.
   54  * These are as VALID_XXX_YYY, where XXX is the structure and YYY is the 
   55  * field.
   56  * Only native types are listed.
   57  */
   58 enum	valid_keys {
   59 	VALID_USER_EMAIL,
   60 	VALID_USER_HASH,
   61 	VALID_USER_ID,
   62 	VALID_SESSION_USERID,
   63 	VALID_SESSION_ID,
   64 	VALID__MAX
   65 };
   66 
   67 /*
   68  * Validation fields.
   69  * Pass this directly into khttp_parse(3) to use them as-is.
   70  * The functions are "valid_xxx_yyy", where "xxx" is the struct and "yyy" 
   71  * the field, and can be used standalone.
   72  * The form inputs are named "xxx-yyy".
   73  */
   74 extern const struct kvalid valid_keys[VALID__MAX];
   75 
   76 __BEGIN_DECLS
   77 
   78 /*
   79  * Forward declaration of opaque pointer.
   80  */
   81 struct ort;
   82 
   83 /*
   84  * Set the argument given to the logging function specified to 
   85  * db_open_logging().
   86  * Has no effect if no logging function has been set.
   87  * The buffer is copied into a child process, so serialised objects may 
   88  * not have any pointers in the current address space or they will fail 
   89  * (at best).
   90  * Set length to zero to unset the logging function callback argument.
   91  */
   92 void db_logging_data(struct ort *ort, const void *arg, size_t sz);
   93 
   94 /*
   95  * Allocate and open the database in "file".
   96  * Returns an opaque pointer or NULL on memory exhaustion.
   97  * The returned pointer must be closed with db_close().
   98  * See db_open_logging() for the equivalent function that accepts logging 
   99  * callbacks.
  100  * This function starts a child with fork(), the child of which opens the 
  101  * database, so a constraint environment (e.g., with pledge) must take 
  102  * this into account.
  103  * Subsequent this function, all database operations take place over IPC.
  104  */
  105 struct ort *db_open(const char *file);
  106 
  107 /*
  108  * Like db_open() but accepts a function for logging.
  109  * If both are provided, the "long" form overrides the "short" form.
  110  * The logging function is run both in a child and parent process, so it 
  111  * must not have side effects.
  112  * The optional pointer is passed to the long form logging function and 
  113  * is inherited by the child process as-is, without being copied by 
  114  * value.
  115  * See db_logging_data() to set the pointer after initialisation.
  116  */
  117 struct ort *db_open_logging(const char *file,
  118 	void (*log)(const char *, void *),
  119 	void (*log_short)(const char *, ...), void *log_arg);
  120 
  121 /*
  122  * Open a transaction with identifier "id".
  123  * If "mode" is 0, the transaction is opened in "deferred" mode, meaning 
  124  * that the database is read-locked (no writes allowed) on the first read 
  125  * operation, and write-locked on the first write (only the current 
  126  * process can write).
  127  * If "mode" is >0, the transaction immediately starts a write-lock.
  128  * If "mode" is <0, the transaction starts in a write-pending, where no 
  129  * other locks can be held at the same time.
  130  * The DB_TRANS_OPEN_IMMEDIATE, DB_TRANS_OPEN_DEFERRED, and 
  131  * DB_TRANS_OPEN_EXCLUSIVE macros accomplish the same but with the "mode" 
  132  * being explicit in the name and not needing to be specified.
  133  */
  134 void db_trans_open(struct ort *ctx, size_t id, int mode);
  135 
  136 #define DB_TRANS_OPEN_IMMEDIATE(_ctx, _id) \
  137 	db_trans_open((_ctx), (_id), 1)
  138 #define DB_TRANS_OPEN_DEFERRED(_ctx, _id)\
  139 	db_trans_open((_ctx), (_id), 0)
  140 #define DB_TRANS_OPEN_EXCLUSIVE(_ctx, _id)\
  141 	db_trans_open((_ctx), (_id), -1)
  142 
  143 /*
  144  * Roll-back an open transaction.
  145  */
  146 void db_trans_rollback(struct ort *ctx, size_t id);
  147 
  148 /*
  149  * Commit an open transaction.
  150  */
  151 void db_trans_commit(struct ort *ctx, size_t id);
  152 
  153 /*
  154  * Close the context opened by db_open().
  155  * Has no effect if "p" is NULL.
  156  */
  157 void db_close(struct ort *p);
  158 
  159 /*
  160  * Drop into a new role.
  161  * If the role is the same as the current one, this is a noop.
  162  * We can only refine roles (i.e., descend the role tree), not ascend or 
  163  * move laterally.
  164  * Attempting to do so causes abort(2) to be called.
  165  * The only exceptions are when leaving ROLE_default or when entering 
  166  * ROLE_none.
  167  */
  168 void db_role(struct ort *ctx, enum ort_role r);
  169 
  170 /*
  171  * Get the current role.
  172  */
  173 enum ort_role db_role_current(struct ort *ctx);
  174 
  175 /*
  176  * Get the role stored into "s".
  177  * This role is set when the object containing the stored role is 
  178  * created, such as when a "search" query function is called.
  179  */
  180 enum ort_role db_role_stored(struct ort_store *s);
  181 
  182 /*
  183  * Clear resources and free "p".
  184  * Has no effect if "p" is NULL.
  185  */
  186 void db_user_free(struct user *p);
  187 
  188 /*
  189  * Lookup by credentials.
  190  * Queries on the following fields in struct user:
  191  * 	v1: email (equals)
  192  * 	v2: hash (pre-hashed password, equals)
  193  * Returns a pointer or NULL on fail.
  194  * Free the pointer with db_user_free().
  195  */
  196 struct user *db_user_get_creds(struct ort *ctx, const char *v1, const char *v2);
  197 
  198 /*
  199  * Clear resources and free "p".
  200  * Has no effect if "p" is NULL.
  201  */
  202 void db_session_free(struct session *p);
  203 
  204 /*
  205  * Insert a new row into the database.
  206  * Only native (and non-rowid) fields may be set.
  207  * 	v1: userid
  208  * Returns the new row's identifier on success or <0 otherwise.
  209  */
  210 int64_t db_session_insert(struct ort *ctx, int64_t v1);
  211 
  212 /*
  213  * Lookup by unique identifier.
  214  * Queries on the following fields in struct session:
  215  * 	v1: id (equals)
  216  * Returns a pointer or NULL on fail.
  217  * Free the pointer with db_session_free().
  218  */
  219 struct session *db_session_get_id(struct ort *ctx, int64_t v1);
  220 
  221 /*
  222  * Constrains the deleted records to:
  223  * 	v1: id (equals)
  224  * Returns zero on constraint violation, non-zero on success.
  225  */
  226 int db_session_delete_by_id_eq(struct ort *ctx, int64_t v1);
  227 
  228 /*
  229  * Print out the fields of a user in JSON including nested structures.
  230  * Omits any password entries or those marked "noexport".
  231  * See json_user_obj() for the full object.
  232  */
  233 void json_user_data(struct kjsonreq *r, const struct user *p);
  234 
  235 /*
  236  * Emit the JSON key-value pair for the object:
  237  * 	"user" : { [data]+ }
  238  * See json_user_data() for the data.
  239  */
  240 void json_user_obj(struct kjsonreq *r, const struct user *p);
  241 
  242 /*
  243  * Print out the fields of a session in JSON including nested structures.
  244  * Omits any password entries or those marked "noexport".
  245  * See json_session_obj() for the full object.
  246  */
  247 void json_session_data(struct kjsonreq *r, const struct session *p);
  248 
  249 /*
  250  * Emit the JSON key-value pair for the object:
  251  * 	"session" : { [data]+ }
  252  * See json_session_data() for the data.
  253  */
  254 void json_session_obj(struct kjsonreq *r, const struct session *p);
  255 
  256 /*
  257  * Validation routines for the email field in struct user.
  258  */
  259 int valid_user_email(struct kpair *p);
  260 
  261 /*
  262  * Validation routines for the hash field in struct user.
  263  */
  264 int valid_user_hash(struct kpair *p);
  265 
  266 /*
  267  * Validation routines for the id field in struct user.
  268  */
  269 int valid_user_id(struct kpair *p);
  270 
  271 /*
  272  * Validation routines for the user field in struct session.
  273  */
  274 int valid_session_user(struct kpair *p);
  275 
  276 /*
  277  * Validation routines for the userid field in struct session.
  278  */
  279 int valid_session_userid(struct kpair *p);
  280 
  281 /*
  282  * Validation routines for the id field in struct session.
  283  */
  284 int valid_session_id(struct kpair *p);
  285 
  286 __END_DECLS
  287 
  288 #endif