A SQLiteTool is a datatype that allows access to the data stored within a SQLite instance. More...

#include <sqlite_tool.h>

Public Member Functions
const SQLITE_PREFIX char *SQLITE_OP_EQUALS_S	SQLITE_VAL ("=")

bool	SetSQLiteDatabase (SQLiteTool tool_p, const char db_s, int flags)
	Set the database an collection that a SQLite will use. More...

bool	SetSQLiteToolTable (SQLiteTool tool_p, const char table_s)
	Set the tablethat a SQLite will use. More...

SQLiteTool *	AllocateSQLiteTool (const char *db_s, int flags)
	This allocates a SQLiteTool that connects to the SQLite instance specified in the grassroots.config file. More...

bool	CloseSQLiteTool (SQLiteTool *tool_p)
	Close the database connection for a given a SQLiteTool. More...

void	FreeSQLiteTool (SQLiteTool *tool_p)
	Delete a SQLiteTool and release the connection that it held This calls CloseSqlTool() and then releases the memory. More...

char *	InsertOrUpdateSQLiteData (SQLiteTool tool_p, json_t values_p, const char const table_s, const char const primary_key_s)
	Insert data from a given JSON fragment using a given SQLite. More...

bool	RemoveSQLiteRows (SQLiteTool tool_p, const json_t selector_json_p, const bool remove_first_match_only_flag)
	Remove some documents from a SQLite collection. More...

json_t *	FindMatchingSQLiteDocuments (SQLiteTool tool_p, LinkedList where_clauses_p, const char fields_ss, char error_ss)
	Find matching documents for a given query. More...

json_t *	GetAllSQLiteResultsAsJSON (SQLiteTool *tool_p)
	Get all results from a SQLite database. More...

int32	GetAllSQLiteResultsForKeyValuePair (SQLiteTool tool_p, json_t docs_pp, const char const key_s, const char const value_s, const char *fields_ss)
	Get all results for a given key-value query. More...

json_t *	GetCurrentValuesFromSQLiteToolAsJSON (SQLiteTool tool_p, const char *fields_ss, const size_t num_fields)
	When iterating over a SQLite's results get the values and increment the current result that the SQLite is pointing at. More...

json_t *	GetAllExistingSQLiteResultsAsJSON (SQLiteTool *tool_p)
	Convert all of a SQLiteTool results into JSON array. More...

int32	IsKeyValuePairInDatabase (SQLiteTool tool_p, const char database_s, const char key_s, const char value_s)
	Check whether a database_s contains any documents with a given key-value pair. More...

void	FreeSQLiteToolErrorString (SQLiteTool tool_p, char error_s)
	Free an error string that was generated from a given SQLiteTool. More...

char *	CreateSQLiteTable (SQLiteTool tool_p, const char table_s, LinkedList *columns_p, const bool delete_if_exists_flag)
	Create a table for the given SQLiteTool. More...

Data Fields
char *	sqlt_table_s
	The name of the table that this SQLiteTool is currently accessing. More...

Detailed Description

A SQLiteTool is a datatype that allows access to the data stored within a SQLite instance.

Member Function Documentation

◆ SQLITE_VAL()

const SQLITE_PREFIX char *SQLITE_OP_EQUALS_S SQLITE_VAL ( )

◆ SetSQLiteDatabase()

bool SetSQLiteDatabase	(	SQLiteTool *	tool_p,
		const char *	db_s,
		int	flags
	)

Set the database an collection that a SQLite will use.

Parameters

tool_p	The SQLite to update.
db_s	The database to use.
flags	The flags to use when opening the underlying sqlite database see sqlite3_open_v2()

Returns: true if the SQLite was updated successfully. false otherwise.

◆ SetSQLiteToolTable()

bool SetSQLiteToolTable	(	SQLiteTool *	tool_p,
		const char *	table_s
	)

Set the tablethat a SQLite will use.

Parameters

tool_p	The SQLite to update.
table_s	The table to use.

Returns: true if the SQLite was updated successfully. false otherwise.

◆ AllocateSQLiteTool()

SQLiteTool * AllocateSQLiteTool	(	const char *	db_s,
		int	flags
	)

This allocates a SQLiteTool that connects to the SQLite instance specified in the grassroots.config file.

Parameters

db_s	The database to use.
flags	The flags to use when opening the underlying sqlite database see sqlite3_open_v2()

Returns: A SQLiteTool or NULL upon error.

See also: InitSQLite

◆ CloseSQLiteTool()

bool CloseSQLiteTool ( SQLiteTool * tool_p )

Close the database connection for a given a SQLiteTool.

Parameters

tool_p The SQLiteTool to close.

Returns: true if the tool was closed successfully, false otherwise.

◆ FreeSQLiteTool()

void FreeSQLiteTool ( SQLiteTool * tool_p )

Delete a SQLiteTool and release the connection that it held This calls CloseSqlTool() and then releases the memory.

Parameters

tool_p The SQLiteTool to free.

◆ InsertOrUpdateSQLiteData()

char * InsertOrUpdateSQLiteData	(	SQLiteTool *	tool_p,
		json_t *	values_p,
		const char *const	table_s,
		const char *const	primary_key_s
	)

Insert data from a given JSON fragment using a given SQLite.

Insert of update data in a set of matching documents.

Parameters

tool_p	The SQLite to use.
values_p	The JSON fragment to insert.
primary_key_id_s	The key used to get the values from values_p that the matching documents will be updated with.

Returns: A pointer to a newly-created BSON id or NULL upon error. This value will need to be freed using FreeMemory() to avoid a memory leak.

Parameters

tool_p	The SQLite to update with.
values_p	The JSON values to add to the documents.
table_s	The table to add the data to.
primary_key_s	The primary key for this data.

Returns: An error string or NULL if the updates were successful.

◆ RemoveSQLiteRows()

bool RemoveSQLiteRows	(	SQLiteTool *	tool_p,
		const json_t *	selector_json_p,
		const bool	remove_first_match_only_flag
	)

Remove some documents from a SQLite collection.

Parameters

tool_p	The SQLite that will amend the collection.
selector_json_p	The statement used to choose which documents to remove.
remove_first_match_only_flag	If this is `true` then only the first matching document will be removed. If this is `false` then all matching documents will be removed.

Returns: true if any matching SQLite documents were removed successfully, false otherwise.

◆ FindMatchingSQLiteDocuments()

json_t * FindMatchingSQLiteDocuments	(	SQLiteTool *	tool_p,
		LinkedList *	where_clauses_p,
		const char **	fields_ss,
		char **	error_ss
	)

Find matching documents for a given query.

Parameters

tool_p	The SQLite that will search the collection.
where_clauses_p	The LinkedList of SqlClauseNodes specifying the query to run.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. This array must have `NULL` as its final element. If this is `NULL`, then all of the keys and values in the matching documents will be stored.
error_ss	If an error occurs, this will point to a newly-allocated string describing the error. This needs to be freed using FreeSQLiteToolErrorString().

Returns: true if any matching SQLite documents were found successfully, false otherwise.

◆ GetAllSQLiteResultsAsJSON()

json_t * GetAllSQLiteResultsAsJSON ( SQLiteTool * tool_p )

Get all results from a SQLite database.

Parameters

tool_p The SQLite to get the results with.

Returns: A json_t array with all of the results from the search or NULL upon error.

◆ GetAllSQLiteResultsForKeyValuePair()

int32 GetAllSQLiteResultsForKeyValuePair	(	SQLiteTool *	tool_p,
		json_t **	docs_pp,
		const char *const	key_s,
		const char *const	value_s,
		const char **	fields_ss
	)

Get all results for a given key-value query.

Parameters

tool_p	The SQLite to get the results with.
docs_pp	A pointer to a JSON array pointer where the results will be placed.
key_s	The key of the query.
value_s	The value of the query.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. This array must have `NULL` as its final element. If this is `NULL`, then all of the keys and values in the matching documents will be stored.

Returns: The number of results found or -1 on error.

◆ GetCurrentValuesFromSQLiteToolAsJSON()

json_t * GetCurrentValuesFromSQLiteToolAsJSON	(	SQLiteTool *	tool_p,
		const char **	fields_ss,
		const size_t	num_fields
	)

When iterating over a SQLite's results get the values and increment the current result that the SQLite is pointing at.

Parameters

tool_p	The SQLite to get the results from.
fields_ss	If specified, then just the keys listed in this array along with their associated values will be stored. If this is `NULL`, then all of the keys and values in the matching documents will be stored.
num_fields	The number of entries in fields_ss.

Returns: A newly-allocated json_object with the key-value pair results or NULL upon error.

◆ GetAllExistingSQLiteResultsAsJSON()

json_t * GetAllExistingSQLiteResultsAsJSON ( SQLiteTool * tool_p )

Convert all of a SQLiteTool results into JSON array.

Parameters

tool_p The SQLiteTool to get the results with.

Returns: The newly-allocated JSON array containing the results or NULL upon error.

◆ IsKeyValuePairInDatabase()

int32 IsKeyValuePairInDatabase	(	SQLiteTool *	tool_p,
		const char *	database_s,
		const char *	key_s,
		const char *	value_s
	)

Check whether a database_s contains any documents with a given key-value pair.

Parameters

tool_p	The SQLite to check with.
database_s	The database to check.
key_s	The key to search for.
value_s	The value to search for.

Returns: The number of matching documents in the given collection or -1 upon error.

◆ FreeSQLiteToolErrorString()

void FreeSQLiteToolErrorString	(	SQLiteTool *	tool_p,
		char *	error_s
	)

Free an error string that was generated from a given SQLiteTool.

Parameters

tool_p	The given SQLiteTool.
error_s	The error string to free.

◆ CreateSQLiteTable()

char * CreateSQLiteTable	(	SQLiteTool *	tool_p,
		const char *	table_s,
		LinkedList *	columns_p,
		const bool	delete_if_exists_flag
	)

Create a table for the given SQLiteTool.

Parameters

tool_p	The given SQLiteTool.
table_s	The name of the table to create.
columns_p	A LinkedList of SQLiteColumnNodes describing the table's columns.
delete_if_exists_flag	If this is `true`, then any existing table with the given name will get deleted and then recreated. If this is `false` then the function will fail and return an error if table already exists.

Returns: An error string or NULL if the table creation was successful.

Field Documentation

◆ sqlt_table_s

char* sqlt_table_s

The name of the table that this SQLiteTool is currently accessing.

The documentation for this struct was generated from the following file:

sqlite_tool.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ SQLITE_VAL()

◆ SetSQLiteDatabase()

◆ SetSQLiteToolTable()

◆ AllocateSQLiteTool()

◆ CloseSQLiteTool()

◆ FreeSQLiteTool()

◆ InsertOrUpdateSQLiteData()

◆ RemoveSQLiteRows()

◆ FindMatchingSQLiteDocuments()

◆ GetAllSQLiteResultsAsJSON()

◆ GetAllSQLiteResultsForKeyValuePair()

◆ GetCurrentValuesFromSQLiteToolAsJSON()

◆ GetAllExistingSQLiteResultsAsJSON()

◆ IsKeyValuePairInDatabase()

◆ FreeSQLiteToolErrorString()

◆ CreateSQLiteTable()

Field Documentation

◆ sqlt_table_s