db.h File Reference

DAL - Interface. More...

#include "errstatus.h"
#include "tchatator413/cfg.h"
#include "types.h"

Go to the source code of this file.

Data Structures
struct	user_t
	Represents a user in the system. More...
struct	msg_list_t
	Represents a list of messages. More...

Typedefs
typedef void	db_t
	An opaque handle to a database connection.
typedef errstatus_t(*	fn_transaction_t) (db_t *db, cfg_t *cfg, void *ctx)
	A transaction body function.

Functions
db_t *	db_connect (cfg_t *cfg, int verbosity, char const *host, char const *port, char const *database, char const *username, char const *password)
	Initialize a database connection.
void	db_destroy (db_t *db)
	Destroy a database connection.
void	db_collect (void *memory_owner)
	Cleans up a memory owner.
errstatus_t	db_verify_user_api_key (db_t *db, cfg_t *cfg, user_identity_t *out_user, api_key_t api_key)
	Verify an API key.
serial_t	db_get_user_id_by_email (db_t *db, cfg_t *cfg, char const *email)
	Get the ID of an user from their e-mail.
serial_t	db_get_user_id_by_name (db_t *db, cfg_t *cfg, char const *name)
	Get the ID of an user from their name.
errstatus_t	db_get_user (db_t *db, cfg_t *cfg, user_t *user)
	Fills a user record from its ID. If user->id is undefined, the behavior is undefined.
errstatus_t	db_get_msg (db_t *db, cfg_t *cfg, msg_t *msg, void **out_memory_owner_db)
	Retrieves a message from the database. If msg->id is undefined, the behavior is undefined.
errstatus_t	db_check_password (db_t *db, cfg_t *cfg, serial_t user_id, char const *password)
	Check a password against the stored hash for an user.
int	db_get_user_role (db_t *db, cfg_t *cfg, serial_t user_id)
	Get the role of an user.
int	db_count_msg (db_t *db, cfg_t *cfg, serial_t sender_id, serial_t recipient_id)
	Counts the amount of messages sent from sender to a recipient.
serial_t	db_send_msg (db_t *db, cfg_t *cfg, serial_t sender_id, serial_t recipient_id, char const *content)
	Sends a message.
msg_list_t	db_get_inbox (db_t *db, cfg_t *cfg, int32_t limit, int32_t offset, serial_t recipient_id)
	Creates an array with the messages an user has recieved, sorted by sent/edited date, in reverse chronological order.
errstatus_t	db_rm_msg (db_t *db, cfg_t *cfg, serial_t msg_id)
	Removes a message from the database.
errstatus_t	db_transaction (db_t *db, cfg_t *cfg, fn_transaction_t body, void *ctx)
	Perform a transaction.

Detailed Description

DAL - Interface.

Author

Raphaël

Date

23/01/2025

Definition in file db.h.

Typedef Documentation

db_t

typedef void db_t

An opaque handle to a database connection.

Definition at line 14 of file db.h.

fn_transaction_t

typedef errstatus_t(* fn_transaction_t) (db_t *db, cfg_t *cfg, void *ctx)

A transaction body function.

This function is called by db_transaction. If this function returns something else than errstatus_ok, the transaction is {aborted}. A ROLLBACK is issued. Otherwise the transaction is considered {valid}. A COMMIT is issued.

Definition at line 165 of file db.h.

Function Documentation

db_check_password()

errstatus_t db_check_password	(	db_t *	db,
		cfg_t *	cfg,
		serial_t	user_id,
		char const *	password
	)

Check a password against the stored hash for an user.

Parameters

db	The database.
cfg	The configuration.
user_id	The ID of the user to check the password of. Can be 0 for the administrator.
password	The clear password to check.

Returns

errstatus_ok The password matched.

errstatus_error The password didn't match or no user of ID user_id exists in the database.

errstatus_handled On database error (handled).

db_collect()

void db_collect

(

void *

memory_owner

)

Cleans up a memory owner.

Parameters

memory_owner

The memory owner to clean up.

Note

NULL is no-op

db_connect()

db_t * db_connect	(	cfg_t *	cfg,
		int	verbosity,
		char const *	host,
		char const *	port,
		char const *	database,
		char const *	username,
		char const *	password
	)

Initialize a database connection.

Parameters

cfg	The configuration.
verbosity	The verbosity level.
host	The database host name to use for the connection.
port	The database port number to use for the connection.
database	The database name to use for the connection.
username	The database username to use for the connection.
password	The database password to use for the connection.

Returns

A new database connection.

NULL if the connection failed.

db_count_msg()

int db_count_msg	(	db_t *	db,
		cfg_t *	cfg,
		serial_t	sender_id,
		serial_t	recipient_id
	)

Counts the amount of messages sent from sender to a recipient.

Parameters

db	The database.
cfg	The configuration.
sender_id	The ID of the sender user of the messages. (0 for adminitrator)
recipient_id	The ID of the recipient user of the message.

Returns

The counts of message from sender_id to recipient_id.

errstatus_handled A database error occured. A message has been shown.

db_destroy()

void db_destroy

(

db_t *

db

)

Destroy a database connection.

Parameters

db	The database connection to destroy. No-op if NULL.

db_get_inbox()

msg_list_t db_get_inbox	(	db_t *	db,
		cfg_t *	cfg,
		int32_t	limit,
		int32_t	offset,
		serial_t	recipient_id
	)

Creates an array with the messages an user has recieved, sorted by sent/edited date, in reverse chronological order.

Parameters

db	The database.
cfg	The configuration.
limit	The maximum number of messages to fetch.
offset	The offset of the query.
recipient_id	The ID of the user who recieved the messages.

Returns

A message list. The memory owner is NULL on error.

db_get_msg()

errstatus_t db_get_msg	(	db_t *	db,
		cfg_t *	cfg,
		msg_t *	msg,
		void **	out_memory_owner_db
	)

Retrieves a message from the database. If msg->id is undefined, the behavior is undefined.

Parameters

db	The database.
cfg	The configuration.
msg	The message to be filled with the retrieved data.
out_memory_owner_db	Assigned to the owner of the memory allocated for the message data.

Returns

errstatus_ok The message was successfully retrieved.

errstatus_error The message could not be retrieved. No message of ID msg->id exists in the database.

errstatus_handled A database error occured. A message has been shown. msg and out_memory_owner_db are untouched.

db_get_user()

errstatus_t db_get_user	(	db_t *	db,
		cfg_t *	cfg,
		user_t *	user
	)

Fills a user record from its ID. If user->id is undefined, the behavior is undefined.

Parameters

db	The database.
cfg	The configuration.
user	The user record to fill.

Returns

errstatus_handled A database error occured. A message has been shown. user is untouched.

errstatus_error No user of ID user->id exists in the database. user is untouched.

errstatus_ok Success.

db_get_user_id_by_email()

serial_t db_get_user_id_by_email	(	db_t *	db,
		cfg_t *	cfg,
		char const *	email
	)

Get the ID of an user from their e-mail.

Parameters

db	The database.
cfg	The configuration.
email	The e-mail to look for.

Returns

The ID of the user with the specified e-mail.

errstatus_handled A database error occured. A message has been shown. out_user is untouched.

errstatus_error No user of e-mail email exists in the database.

db_get_user_id_by_name()

serial_t db_get_user_id_by_name	(	db_t *	db,
		cfg_t *	cfg,
		char const *	name
	)

Get the ID of an user from their name.

Parameters

db	The database.
cfg	The configuration.
name	The name to look for. It can be a member's pseudo or a pro's display name

Returns

The ID of the user with the specified name.

errstatus_handled A database error occured. A message has been shown. out_user is untouched.

errstatus_error No user of name name exists in the database.

db_get_user_role()

int db_get_user_role	(	db_t *	db,
		cfg_t *	cfg,
		serial_t	user_id
	)

Get the role of an user.

Parameters

db	The database.
cfg	The configuration.
user_id	The ID of the user to get the role of.

Returns

role_flags_t the role of the user is found.

errstatus_handled A database error occured. A message has been shown. out_user is untouched.

errstatus_error No user of ID user_id exists in the database.

db_rm_msg()

errstatus_t db_rm_msg	(	db_t *	db,
		cfg_t *	cfg,
		serial_t	msg_id
	)

Removes a message from the database.

Parameters

db	The database.
cfg	The configuration.
msg_id	The ID of the message to be removed.

Returns

errstatus_ok The message was successfully removed.

errstatus_error The message could not be removed.

db_send_msg()

serial_t db_send_msg	(	db_t *	db,
		cfg_t *	cfg,
		serial_t	sender_id,
		serial_t	recipient_id,
		char const *	content
	)

Sends a message.

Parameters

db	The database.
cfg	The configuration.
sender_id	The ID of the sender user
recipient_id	The ID of the recipient user
content	The null-terminated string containing the content of the message.

Returns

serial_t The message ID.

errstatus_handled A database error occured. A message has been shown. out_user is untouched.

errstatus_error The sender has been blocked from sending messages, either globally or by this particular recipient.

db_transaction()

errstatus_t db_transaction	(	db_t *	db,
		cfg_t *	cfg,
		fn_transaction_t	body,
		void *	ctx
	)

Perform a transaction.

Parameters

db	The database.
cfg	The configuration.
body	The transaction body function.
ctx	The context to pass to {body}. Can be {NULL}.

Returns

The error status of {body}, or of the BEGIN, COMMIT or ROLLBACK action if they weren't successful.

db_verify_user_api_key()

errstatus_t db_verify_user_api_key	(	db_t *	db,
		cfg_t *	cfg,
		user_identity_t *	out_user,
		api_key_t	api_key
	)

Verify an API key.

Parameters

db	The database.
cfg	The configuration.
out_user	Assigned to the identity of the user.
api_key	The API key to verify.

Returns

errstatus_handled A database error occured. A message has been shown. out_user is untouched.

errstatus_error The API key isn't valid. out_user is untouched.

errstatus_ok The API key is valid.