A simple database for storing and retrieving images, videos, text or other data by roc_hash. More...

Typedefs
typedef struct roc_database_type *	roc_database
	Path to an existing folder to store the files. More...

Functions
roc_error	roc_open_database (const char path, roc_database database)
	Open a connection to a database. More...

roc_error	roc_close_database (roc_database *database)
	Close a connection to a database. More...

roc_error	roc_database_add_file (roc_database database, const char *file_path, roc_hash key)
	Add a file to the database. More...

roc_error	roc_database_add_link (roc_database database, const char *file_path, roc_hash key)
	Add a symlink of a file to the database. More...

roc_error	roc_database_add_data (roc_database database, const uint8_t *input_byte_array, size_t length, roc_hash key)
	Add arbitrary data to the database. More...

roc_error	roc_database_has_key (roc_database database, roc_hash key, bool *has_key)
	Determine if a key exists in the database. More...

roc_error	roc_database_retrieve_file (roc_database database, roc_hash key, roc_string *file_path)
	Retrieve a file from the database. More...

roc_error	roc_database_retrieve_data (roc_database database, roc_hash key, roc_buffer data, size_t length)
	Retrieve file data from the database. More...

roc_error	roc_database_remove (roc_database database, roc_hash key)
	Remove a file from the database. More...

roc_error	roc_database_first_key (roc_database database, roc_hash *first_key)
	Obtain the first key in the database. More...

roc_error	roc_database_next_key (roc_database database, roc_hash current_key, roc_hash *next_key)
	Obtain the next key in the database. More...

roc_error	roc_database_sync (roc_database from, const char *to, bool async)
	Sync a database to another system. More...

Detailed Description

A simple database for storing and retrieving images, videos, text or other data by roc_hash.

A roc_database is simply a folder on the file system managed by the ROC SDK.

Add data with roc_database_add_file, roc_database_add_link, or roc_database_add_data. Obtain a previously added file with roc_database_retrieve_file or roc_database_retrieve_data.

Typedef Documentation

◆ roc_database

typedef struct roc_database_type* roc_database

Path to an existing folder to store the files.

This folder should be empty and already exist when constructing a new database.

Function Documentation

◆ roc_open_database()

roc_error roc_open_database	(	const char *	path,
		roc_database *	database
	)

Open a connection to a database.

Note: To avoid syncronization issues, do not make multiple calls to roc_open_database with the same underlying local path.

Close database after use with roc_close_database.

Parameters

[in]	path	Path to the database.
[out]	database	Database handle to initialize.

Remarks: This function is reentrant.

◆ roc_close_database()

roc_error roc_close_database ( roc_database * database )

Close a connection to a database.

Sets database to NULL after deallocating. If database is NULL this function has no affect.

Parameters

[in] database Database handle to deallocate.

Remarks: This function is reentrant.

◆ roc_database_add_file()

roc_error roc_database_add_file	(	roc_database	database,
		const char *	file_path,
		roc_hash	key
	)

Add a file to the database.

Copies the file pointed to by file_path to database and associates it with a key used to retrieve it. The key is typically known by virtue of having called roc_read_image or roc_open_video (roc_media_id), however it can also be obtained by calling roc_hash_calc_sha1_file if needed. Any data previously associated with key will be removed.

Parameters

[in]	database	Database to add the file to.
[in]	file_path	File to add to the database.
[in]	key	Key to associate with the data, typically a hash of the file contents.

Remarks: This function is thread-safe.

See also: roc_database_add_link roc_database_add_data

◆ roc_database_add_link()

roc_error roc_database_add_link	(	roc_database	database,
		const char *	file_path,
		roc_hash	key
	)

Add a symlink of a file to the database.

Creates a symbolic link of file_path, copies the symlink to database, and associates it with a key used to retrieve it. The key is typically known by virtue of having called roc_read_image or roc_open_video (roc_media_id), however it can also be obtained by calling roc_hash_calc_sha1_file if needed. Any data previously associated with key will be removed.

Parameters

[in]	database	Database to add the file to.
[in]	file_path	File to symlink into to the database.
[in]	key	Key to associate with the data, typically a hash of the file contents.

Remarks: This function is thread-safe.

See also: roc_database_add_file

◆ roc_database_add_data()

roc_error roc_database_add_data	(	roc_database	database,
		const uint8_t *	input_byte_array,
		size_t	length,
		roc_hash	key
	)

Add arbitrary data to the database.

Copies input_byte_array to a new file in the database and associates it with a key used to retrieve it. This function can be used to store the result of roc_encode_image, in which case key can be obtained by calling roc_hash_calc_sha1. This function can also be used to store arbitrary data associated with a roc_uuid, in which case key should be obtained by calling roc_hash_from_uuid. Any data previously associated with key will be removed.

Parameters

[in]	database	Database to add the data buffer to.
[in]	input_byte_array	Data buffer to add to the database.
[in]	length	Length of `input_byte_array`.
[in]	key	Key to associate with the data.

Remarks: This function is thread-safe.

See also: roc_database_add_file

◆ roc_database_has_key()

roc_error roc_database_has_key	(	roc_database	database,
		roc_hash	key,
		bool *	has_key
	)

Determine if a key exists in the database.

Parameters

[in]	database	Database to check for the key.
[in]	key	Key to check for.
[out]	has_key	`true` if `key` exists in `database`, `false` otherwise.

Remarks: This function is thread-safe.

◆ roc_database_retrieve_file()

roc_error roc_database_retrieve_file	(	roc_database	database,
		roc_hash	key,
		roc_string *	file_path
	)

Retrieve a file from the database.

Obtain the file_path to a file in database for key. Free file_path after use with roc_free_string.

Parameters

[in]	database	Database to obtain a file from.
[in]	key	File to obtain.
[out]	file_path	Path to the file in `database` associated with `key`.

Remarks: This function is thread-safe.

◆ roc_database_retrieve_data()

roc_error roc_database_retrieve_data	(	roc_database	database,
		roc_hash	key,
		roc_buffer *	data,
		size_t *	length
	)

Retrieve file data from the database.

Read the contents of the file in database for key. Free data after use with roc_free_buffer.

Parameters

[in]	database	Database to obtain the contents from.
[in]	key	File contents to obtain.
[out]	data	Contents of the file in `database` associated with `key`.
[out]	length	Length of `data`

Remarks: This function is thread-safe.

◆ roc_database_remove()

roc_error roc_database_remove	(	roc_database	database,
		roc_hash	key
	)

Remove a file from the database.

Remove the file in database associated with key.

Parameters

[in]	database	Database to remove a file from.
[in]	key	File to remove.

Remarks: This function is thread-safe.

◆ roc_database_first_key()

roc_error roc_database_first_key	(	roc_database	database,
		roc_hash *	first_key
	)

Obtain the first key in the database.

Useful for iterating through the database. first_key is roc_hash_get_null for an empty database.

Parameters

[in]	database	Database to return the first key of.
[out]	first_key	First key in the database.

Remarks: This function is thread-safe.

See also: roc_database_next_key

◆ roc_database_next_key()

roc_error roc_database_next_key	(	roc_database	database,
		roc_hash	current_key,
		roc_hash *	next_key
	)

Obtain the next key in the database.

Useful for iterating through the database. next_key is roc_hash_get_null when the end of the database is reached. Keys are ordered by roc_hash_is_less_than.

Parameters

[in]	database	Database to return the next key of.
[in]	current_key	Current key.
[out]	next_key	The next key after `current_key`.

Remarks: This function is thread-safe.

See also: roc_database_first_key

◆ roc_database_sync()

roc_error roc_database_sync	(	roc_database	from,
		const char *	to,
		bool	async
	)

Sync a database to another system.

The rsync command must be installed on calling system for this function to operate.

Parameters

[in]	from	Database to sync from.
[in]	to	Location to sync to.
[in]	async	If `true` this function will start the sync and then return immediately, else it will wait until the sync completes to return.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ roc_database

Function Documentation

◆ roc_open_database()

◆ roc_close_database()

◆ roc_database_add_file()

◆ roc_database_add_link()

◆ roc_database_add_data()

◆ roc_database_has_key()

◆ roc_database_retrieve_file()

◆ roc_database_retrieve_data()

◆ roc_database_remove()

◆ roc_database_first_key()

◆ roc_database_next_key()

◆ roc_database_sync()