From 7ce89123f73efd5a075a2927aa87647637a051f4 Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Wed, 6 Mar 2024 12:46:27 -0500 Subject: [PATCH] 85 make docs warnings remain. --- src/ssb.db.h | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/src/ssb.db.h b/src/ssb.db.h index 1a479103..a8777d48 100644 --- a/src/ssb.db.h +++ b/src/ssb.db.h @@ -13,29 +13,112 @@ #include +/** An SSB instance. */ typedef struct _tf_ssb_t tf_ssb_t; +/** +** Initialize the database writer for an SSB instance. +** @param ssb The SSB instance. +*/ void tf_ssb_db_init(tf_ssb_t* ssb); + +/** +** Configure an opened SQLite database for reading. +*/ void tf_ssb_db_init_reader(sqlite3* db); + +/** +** Get message content by ID. +** @param ssb The SSB instance. +** @param id The message identifier. +** @param[out] out_blob Populated with the message content. +** @param[out] out_size POpulated with the size of the message content. +** @return true If the message content was found and retrieved. +*/ bool tf_ssb_db_message_content_get(tf_ssb_t* ssb, const char* id, uint8_t** out_blob, size_t* out_size); + +/** +** Determine whether a blob is in the database by ID. +** @param ssb The SSB instasnce. +** @param id The blob identifier. +** @return true If the blob is in the database. +*/ bool tf_ssb_db_blob_has(tf_ssb_t* ssb, const char* id); + +/** +** Retrieve a blob from the database. +** @param ssb The SSB instance. +** @param id The blob identifier. +** @param[out] out_blob Populated with the blob data. +** @param[out] out_size The size of the blob data. +** @return true If the blob was found and retrieved. +*/ bool tf_ssb_db_blob_get(tf_ssb_t* ssb, const char* id, uint8_t** out_blob, size_t* out_size); +/** +** A function called when a message is stored in the database. +** @param id The message identifier. +** @param stored True if the message wasn't already in the database. +** @param user_data The user data. +*/ typedef void(tf_ssb_db_store_message_callback_t)(const char* id, bool stored, void* user_data); + +/** +** Store a message in the database. +** @param ssb The SSB instance. +** @param context The JS context. +** @param id The message identifier. +** @param val The message object. +** @param signature The signature of the message. +** @param sequence_before_author The order of the message fields. +** @param callback A callback to call upon completion. +** @param user_data User data for the callback. +*/ void tf_ssb_db_store_message(tf_ssb_t* ssb, JSContext* context, const char* id, JSValue val, const char* signature, bool sequence_before_author, tf_ssb_db_store_message_callback_t* callback, void* user_data); +/** +** A function called when a block is stored in the database. +** @param id The blob identifier. +** @param is_new True if the blob wasn't already in the database. +** @param user_data The user data. +*/ typedef void(tf_ssb_db_blob_store_callback_t)(const char* id, bool is_new, void* user_data); + +/** +** Store a blob in the database asynchronously. +** @param ssb The SSB instance. +** @param blob The blob data. +** @param size The size of the blob data. +** @param callback A callback to call upon completion. +** @param user_data User data for the callback. +*/ void tf_ssb_db_blob_store_async(tf_ssb_t* ssb, const uint8_t* blob, size_t size, tf_ssb_db_blob_store_callback_t* callback, void* user_data); + +/** +** Store a blob in the database and wait for the operation to complete. +** @param ssb The SSB instance. +** @param blob The blob data. +** @param size The size of the blob. +** @param[out] out_id Populated with the blob identifier. +** @param out_id_size The size of the out_id buffer. +** @param[out] out_new True if the blob wasn't already in the datbase. +*/ bool tf_ssb_db_blob_store(tf_ssb_t* ssb, const uint8_t* blob, size_t size, char* out_id, size_t out_id_size, bool* out_new); +/** +** Get a message by its identifier. +** @param ssb The SSB instance. +** @param id The message identifier. +** @param is_keys Whether to produce {"key": id, "value": message, "timestamp": ts} or just the message. +** @return The message. +*/ JSValue tf_ssb_db_get_message_by_id(tf_ssb_t* ssb, const char* id, bool is_keys); bool tf_ssb_db_get_message_by_author_and_sequence( tf_ssb_t* ssb, const char* author, int64_t sequence, char* out_message_id, size_t out_message_id_size, double* out_timestamp, char** out_content); bool tf_ssb_db_get_latest_message_by_author(tf_ssb_t* ssb, const char* author, int64_t* out_sequence, char* out_message_id, size_t out_message_id_size); JSValue tf_ssb_db_visit_query(tf_ssb_t* ssb, const char* query, const JSValue binds, void (*callback)(JSValue row, void* user_data), void* user_data); -typedef struct sqlite3 sqlite3; bool tf_ssb_db_check(sqlite3* db, const char* author); int tf_ssb_db_identity_get_count_for_user(tf_ssb_t* ssb, const char* user);