Database access public functions. More...

#include <string.h>
#include "techtype.h"
#include "dbgfuncs.h"
#include "stbhwos.h"
#include "dba.h"
#include "dba_nvm.h"
#include "stbdbram.h"
#include "stbdbnvm.h"
#include "stbnvm.h"
#include "stbcsum.h"
#include "stbheap.h"
#include "stbuni.h"

Macros
#define	FORMAT_VERSION_NUM 3

#define	FORMAT_ID_STRING "STB DB 01"

#define	FORMAT_ID_STRING_SIZE 10

#define	NUM_FIELDS(X) (sizeof(X) / sizeof(FIELD_ACCESS))

#define	DBA_GROUP_NAME_LEN 35

#define	DBA_TRANS_NAME_LEN 31

#define	DBA_SERV_NAME_LEN 32

#define	DBA_TIMER_NAME_LEN 255 /* Max length of an event name is 255 chars */

#define	DBA_FAVLIST_NAME_LEN 128 /* Arbitrary length */

#define	DBA_TIMER_ADDINFO_LEN 255

#define	DBA_LNB_NAME_LEN 24

#define	DBA_CRID_LEN 65

#define	DBA_PROFILE_NAME_LEN 255

Functions
BOOLEAN	DBA_Initialise (void)
	Performs any initialisation required prior to the database being loaded. More...

void	DBA_Terminate (void)
	Releases any resources acquired by initialisation and clears any currently loaded database, including a backup, if one has been created.

BOOLEAN	DBA_LoadDatabase (U8BIT *pathname)
	Reads a database from non-volatile storage, creating any structures in memory that will be required to access it and the records it contains and makes this the working database. If the database is found to be invalid, or doesn't exist at all, then an empty database should be created. More...

BOOLEAN	DBA_SaveDatabase (void)
	Saves any changes made to the working database to non-volatile storage. If saving to a file, the pathname used to open it will be used. More...

BOOLEAN	DBA_ClearDatabase (void)
	Clears the working database of all records. Following this call, it should still be possible to access the database, but it will be empty, and new records can be added to it. More...

BOOLEAN	DBA_BackupDatabase (U8BIT *pathname)
	Creates a backup copy of the working database. Whether the backup database is saved to non-volatile storage is implementation dependant and so the backup database may not survive a system reboot. More...

BOOLEAN	DBA_CanRestoreDatabase (void)
	Checks whether the working database can be restored from a backup copy. More...

BOOLEAN	DBA_RestoreDatabase (void)
	Restores the working database from a previously made backup copy. More...

void	DBA_EraseBackupDatabase (void)
	Erases the backup copy of the database. If data was stored in non-volatile storage then this should be deleted too.

BOOLEAN	DBA_ExportToXML (U8BIT *xml_pathname)
	Export the working database to an XML file. More...

BOOLEAN	DBA_ImportFromXML (U8BIT *xml_pathname)
	Imports records from the given XML file into the working database. If a record already exists in the database then it will be updated, and if it doesn't then a new record will be created. More...

void	DBA_LockDatabase (void)
	Locks the database to prevent access from other threads or processes.

void	DBA_UnlockDatabase (void)
	Unlocks the database to allow other threads or processes to access it.

U8BIT *	DBA_DatabaseVersion (void)
	Returns a version string representing the working database. More...

U32BIT	DBA_DatabaseFileSize (U32BIT *max_size)
	Returns the size in bytes of the database as stored in non-volatile storage. More...

void *	DBA_CreateRecord (U32BIT record_id, void *parent)
	Creates a new record of the given type, adding it to the database as a child of the given parent record, if provided. More...

void	DBA_DestroyRecord (void *record)
	Destroys the given record, removing it from the database and freeing any memory associated with it. More...

void *	DBA_FindRecord (U32BIT record_id, void parent, void last_rec)
	Finds the next record, of the given type, that comes after last_rec. last_rec must be the same type of record as the one being found. Parent is optional, but if provided, a record will only be returned if the parent of the one found is the same. More...

void	DBA_SetRecordParent (void record, void parent)
	Set of change the parent of the given record. More...

void *	DBA_GetRecordParent (void *record)
	Returns the handle to the parent of the given record. More...

void	DBA_SaveRecord (void *record)
	Forces a record to be saved to non-volatile storage. Depending on the implementation, this function may not do anything if the data is updated to non-volatile storage as any records and/or fields are created or updated. More...

BOOLEAN	DBA_SetFieldValue (void *record, U32BIT field_id, U32BIT value)
	Set the value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is a string value. More...

BOOLEAN	DBA_SetFieldString (void record, U16BIT field_id, U8BIT string, U16BIT num_bytes)
	Set the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is an integer value. The string data provided will be copied and no interpretation is made of the format of the string. More...

BOOLEAN	DBA_SetFieldLangString (void record, U32BIT field_id, U32BIT lang_code, U8BIT string, U16BIT num_bytes)
	Set the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a string field. The string data provided will be copied and no interpretation is made of the format of the string. More...

BOOLEAN	DBA_SetFieldData (void record, U32BIT field_id, U8BIT data, U16BIT num_bytes)
	Set a variable amount of data of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field doesn't hold data. The data provided will be copied. More...

BOOLEAN	DBA_GetFieldValue (void record, U32BIT field_id, U32BIT value)
	Gets the value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is a string value. More...

BOOLEAN	DBA_GetFieldString (void record, U32BIT field_id, U8BIT string, U16BIT num_bytes)
	Gets the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is an integer value. The pointer to the string returned will be to the data held by the database, so the data must not be changed. More...

BOOLEAN	DBA_GetFieldLangString (void record, U32BIT field_id, U32BIT lang_code, U8BIT string, U16BIT num_bytes)
	Gets the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is an integer value. The pointer to the string returned will be to the data held by the database, so the data must not be changed. More...

BOOLEAN	DBA_GetFieldData (void record, U32BIT field_id, U8BIT data, U16BIT num_bytes)
	Gets the data of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a data field. The pointer to the data returned will be to the data held by the database, so the data must not be changed. More...

U32BIT	DBA_DataBlockSize (U32BIT data_block_id)
	Returns the number of bytes available for the given data block. More...

U32BIT	DBA_DataBlockRead (U32BIT data_block_id, U8BIT *data, U32BIT num_bytes)
	Read a block of data from the database into the given buffer. More...

BOOLEAN	DBA_DataBlockWrite (U32BIT data_block_id, U8BIT *data, U32BIT num_bytes)
	Writes a block of data into the database from the given buffer. More...

Detailed Description

Database access public functions.

Date: 11/11/2013

Author: Ocean Blue

Function Documentation

BOOLEAN DBA_BackupDatabase ( U8BIT * pathname )

Creates a backup copy of the working database. Whether the backup database is saved to non-volatile storage is implementation dependant and so the backup database may not survive a system reboot.

Parameters

pathname full pathname of the file to save the backup to if this is supported by the database implementation.

Returns: TRUE if a backup is created, FALSE otherwise

BOOLEAN DBA_CanRestoreDatabase ( void )

Checks whether the working database can be restored from a backup copy.

Returns: TRUE if there is a backup copy and it can be restored, FALSE otherwise

BOOLEAN DBA_ClearDatabase ( void )

Clears the working database of all records. Following this call, it should still be possible to access the database, but it will be empty, and new records can be added to it.

Returns: TRUE if the database is cleared, FALSE otherwise

void* DBA_CreateRecord	(	U32BIT	record_id,
		void *	parent
	)

Creates a new record of the given type, adding it to the database as a child of the given parent record, if provided.

Parameters

record_id	type of record to be created
parent	create a record that is a child of this parent, can be passed as NULL

Returns: handle of new record, or NULL if creation fails

U32BIT DBA_DatabaseFileSize ( U32BIT * max_size )

Returns the size in bytes of the database as stored in non-volatile storage.

Parameters

max_size returns the maximum size in bytes that the database can grow to. This value may be returned as 0 if this can't be determined.

Returns: current size of the working database in bytes

U8BIT* DBA_DatabaseVersion ( void )

Returns a version string representing the working database.

Returns: '\0' terminated string in UTF-8 format

U32BIT DBA_DataBlockRead	(	U32BIT	data_block_id,
		U8BIT *	data,
		U32BIT	num_bytes
	)

Read a block of data from the database into the given buffer.

Parameters

data_block_id	id of the data block to be read
data	pointer to the buffer into which the data will be read
num_bytes	the number of bytes to be read

Returns: number of bytes read into the buffer

U32BIT DBA_DataBlockSize ( U32BIT data_block_id )

Returns the number of bytes available for the given data block.

Parameters

data_block_id the data block whose size is to be returned

Returns: size of bytes of the data block, or 0 if block not found

BOOLEAN DBA_DataBlockWrite	(	U32BIT	data_block_id,
		U8BIT *	data,
		U32BIT	num_bytes
	)

Writes a block of data into the database from the given buffer.

Parameters

data_block_id	id of the data block being written
data	pointer to the data to be written
num_bytes	number of bytes of data to be written

Returns: TRUE if the data is written, FALSE otherwise

void DBA_DestroyRecord ( void * record )

Destroys the given record, removing it from the database and freeing any memory associated with it.

Parameters

record database record to be deleted

BOOLEAN DBA_ExportToXML ( U8BIT * xml_pathname )

Export the working database to an XML file.

Parameters

xml_pathname full pathname of the file to export to

Returns: TRUE if the database is exported successfully, FALSE otherwise

void* DBA_FindRecord	(	U32BIT	record_id,
		void *	parent,
		void *	last_rec
	)

Finds the next record, of the given type, that comes after last_rec. last_rec must be the same type of record as the one being found. Parent is optional, but if provided, a record will only be returned if the parent of the one found is the same.

Parameters

record_id	- type of record to look for
parent	if not NULL, this must be the parent of the record found for it to be returned
last_rec	previous record of the type being looked for, if NULL then the first record will be returned.

Returns: handle of the record, or NULL if none found

BOOLEAN DBA_GetFieldData	(	void *	record,
		U32BIT	field_id,
		U8BIT **	data,
		U16BIT *	num_bytes
	)

Gets the data of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a data field. The pointer to the data returned will be to the data held by the database, so the data must not be changed.

Parameters

record	handle of the record being queried
field_id	field within the record being queried
data	pointer to the returned data in the field
num_bytes	number of bytes of data

Returns: TRUE if data is returned, FALSE otherwise

BOOLEAN DBA_GetFieldLangString	(	void *	record,
		U32BIT	field_id,
		U32BIT	lang_code,
		U8BIT **	string,
		U16BIT *	num_bytes
	)

Gets the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is an integer value. The pointer to the string returned will be to the data held by the database, so the data must not be changed.

Gets the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a string field. The pointer to the string returned will be to the string data held by the database, so the data must not be changed.

Parameters

record	handle of the record being queried
field_id	field within the record being queried
lang_code	language code of the string to be returned
string	pointer to the returned string value in the field
num_bytes	number of bytes in the string

Returns: TRUE if a string is returned, FALSE otherwise

BOOLEAN DBA_GetFieldString	(	void *	record,
		U32BIT	field_id,
		U8BIT **	string,
		U16BIT *	num_bytes
	)

Gets the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is an integer value. The pointer to the string returned will be to the data held by the database, so the data must not be changed.

Gets the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a string field. The pointer to the string returned will be to the string data held by the database, so the data must not be changed.

Parameters

record	handle of the record being queried
field_id	field within the record being queried
string	pointer to the returned string value in the field
num_bytes	number of bytes in the string

Returns: TRUE if a string is returned, FALSE otherwise

BOOLEAN DBA_GetFieldValue	(	void *	record,
		U32BIT	field_id,
		U32BIT *	value
	)

Gets the value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is a string value.

Gets the value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a value field.

Parameters

record	handle of the record being queried
field_id	field within the record being queried
value	pointer to the returned value if function returns TRUE

Returns: TRUE if a value is returned, FALSE otherwise

void* DBA_GetRecordParent ( void * record )

Returns the handle to the parent of the given record.

Parameters

record handle of record whose parent is to be returned

Returns: handle of the record's parent

BOOLEAN DBA_ImportFromXML ( U8BIT * xml_pathname )

Imports records from the given XML file into the working database. If a record already exists in the database then it will be updated, and if it doesn't then a new record will be created.

Parameters

xml_pathname full pathname of the file to be imported

Returns: TRUE if the file is imported successfully, FALSE otherwise

BOOLEAN DBA_Initialise ( void )

Performs any initialisation required prior to the database being loaded.

Returns: TRUE if initialisation is successful, FALSE otherwise

BOOLEAN DBA_LoadDatabase ( U8BIT * pathname )

Reads a database from non-volatile storage, creating any structures in memory that will be required to access it and the records it contains and makes this the working database. If the database is found to be invalid, or doesn't exist at all, then an empty database should be created.

Parameters

pathname full pathname of the file to be loaded containing the database. This argument is only relevant where the system being used is file based.

Returns: TRUE if a database is loaded successfully, FALSE otherwise

BOOLEAN DBA_RestoreDatabase ( void )

Restores the working database from a previously made backup copy.

Returns: TRUE if the working database is restored from the backup, FALSE otherwise

BOOLEAN DBA_SaveDatabase ( void )

Saves any changes made to the working database to non-volatile storage. If saving to a file, the pathname used to open it will be used.

Returns: TRUE if the database is saved successfully, FALSE otherwise

void DBA_SaveRecord ( void * record )

Forces a record to be saved to non-volatile storage. Depending on the implementation, this function may not do anything if the data is updated to non-volatile storage as any records and/or fields are created or updated.

Parameters

record handle of record to be saved

BOOLEAN DBA_SetFieldData	(	void *	record,
		U32BIT	field_id,
		U8BIT *	data,
		U16BIT	num_bytes
	)

Set a variable amount of data of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field doesn't hold data. The data provided will be copied.

Parameters

record	handle of the record to be changed
field_id	field within the record to be changed
data	data to be stored in the field
num_bytes	number of bytes of data

Returns: TRUE if the data is set, FALSE otherwise

BOOLEAN DBA_SetFieldLangString	(	void *	record,
		U32BIT	field_id,
		U32BIT	lang_code,
		U8BIT *	string,
		U16BIT	num_bytes
	)

Set the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a string field. The string data provided will be copied and no interpretation is made of the format of the string.

Parameters

record	handle of the record to be changed
field_id	field within the record to be changed
lang_code	language code of the string
string	string value of the field
num_bytes	number of bytes in the string, should include null terminator if present

Returns: TRUE if the string is set, FALSE otherwise

BOOLEAN DBA_SetFieldString	(	void *	record,
		U16BIT	field_id,
		U8BIT *	string,
		U16BIT	num_bytes
	)

Set the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is an integer value. The string data provided will be copied and no interpretation is made of the format of the string.

Set the string value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a string field. The string data provided will be copied and no interpretation is made of the format of the string.

Parameters

record	handle of the record to be changed
field_id	field within the record to be changed
string	string value of the field
num_bytes	number of bytes in the string, should include null terminator if present

Returns: TRUE if the string is set, FALSE otherwise

BOOLEAN DBA_SetFieldValue	(	void *	record,
		U32BIT	field_id,
		U32BIT	value
	)

Set the value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field is a string value.

Set the value of a record's field. The function will fail if the record doesn't exist, the record doesn't include the given field, or the field isn't a value field.

Parameters

record	handle of the record to be changed
field_id	field within the record to be changed
value	new value of the field

Returns: TRUE if the value is set, FALSE otherwise

void DBA_SetRecordParent	(	void *	record,
		void *	parent
	)

Set of change the parent of the given record.

Parameters

record	handle of the record whose parent is to be changed
parent	handle of the new parent record, can be NULL

Macros

Functions

Detailed Description

Function Documentation