dba_nvm.c File Reference

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"

Go to the source code of this file.

Classes
struct	DATABASE_FORMAT
struct	DATABASE_DESCRIPTOR
struct	RECORD_DESCRIPTOR
struct	FIELD_DESCRIPTOR
struct	FIELD_TYPE
struct	FIELD_ACCESS
struct	RECORD_ACCESS

Macros
#define	FORMAT_VERSION_NUM   4
#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_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, U32BIT 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

Definition in file dba_nvm.c.

Function Documentation

DBA_BackupDatabase()

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

Definition at line 723 of file dba_nvm.c.

DBA_CanRestoreDatabase()

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

Definition at line 766 of file dba_nvm.c.

DBA_ClearDatabase()

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

Definition at line 694 of file dba_nvm.c.

DBA_CreateRecord()

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

Definition at line 940 of file dba_nvm.c.

DBA_DatabaseFileSize()

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

Definition at line 915 of file dba_nvm.c.

DBA_DatabaseVersion()

U8BIT* DBA_DatabaseVersion

(

void

)

Returns a version string representing the working database.

Returns

'\0' terminated string in UTF-8 format

Definition at line 887 of file dba_nvm.c.

DBA_DataBlockRead()

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

Definition at line 1528 of file dba_nvm.c.

DBA_DataBlockSize()

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

Definition at line 1508 of file dba_nvm.c.

DBA_DataBlockWrite()

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

Definition at line 1560 of file dba_nvm.c.

DBA_DestroyRecord()

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

Definition at line 1013 of file dba_nvm.c.

DBA_ExportToXML()

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

Definition at line 840 of file dba_nvm.c.

DBA_FindRecord()

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

Definition at line 1055 of file dba_nvm.c.

DBA_GetFieldData()

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

Definition at line 1488 of file dba_nvm.c.

DBA_GetFieldLangString()

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

Definition at line 1460 of file dba_nvm.c.

DBA_GetFieldString()

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

Definition at line 1400 of file dba_nvm.c.

DBA_GetFieldValue()

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

Definition at line 1341 of file dba_nvm.c.

DBA_GetRecordParent()

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

Definition at line 1129 of file dba_nvm.c.

DBA_ImportFromXML()

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

Definition at line 855 of file dba_nvm.c.

DBA_Initialise()

BOOLEAN DBA_Initialise

(

void

)

Performs any initialisation required prior to the database being loaded.

Returns

TRUE if initialisation is successful, FALSE otherwise

Definition at line 482 of file dba_nvm.c.

DBA_LoadDatabase()

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

Definition at line 541 of file dba_nvm.c.

DBA_RestoreDatabase()

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

Definition at line 789 of file dba_nvm.c.

DBA_SaveDatabase()

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

Definition at line 667 of file dba_nvm.c.

DBA_SaveRecord()

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

Definition at line 1157 of file dba_nvm.c.

DBA_SetFieldData()

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

Definition at line 1318 of file dba_nvm.c.

DBA_SetFieldLangString()

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

Definition at line 1291 of file dba_nvm.c.

DBA_SetFieldString()

BOOLEAN DBA_SetFieldString	(	void *	record,
		U32BIT	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

Definition at line 1227 of file dba_nvm.c.

DBA_SetFieldValue()

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

Definition at line 1175 of file dba_nvm.c.

DBA_SetRecordParent()

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

Definition at line 1080 of file dba_nvm.c.