tables.h File Reference

#include <cfe-tables/typedef.h>
#include <stdint.h>
#include <cfe/cfe_value.h>

Include dependency graph for tables.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	INIT_TABLE_TYPE_DEF(NAME)
#define	ADD_FIELD(ID, FUNC)   get_functions[ID] = (table_get_function_t)(FUNC);
#define	INIT_TABLE_TYPE(NAME, TYPE)   INIT_TABLE_TYPE_WITH_FIELDS(NAME, TYPE, 0, (void)0;)
#define	INIT_TABLE_TYPE_WITH_FIELDS(NAME, TYPE, N_F, FIELDS)
#define	TABLE_STORE_START(TABLE_TYPE, TABLE, P)
#define	TABLE_STORE_RETURN(TABLE, P, PTR)   return table_store_return((table_t *)TABLE, (rec_t)P, (void *)PTR);

Functions
table_t *	table_new (const char *name, size_t soe, table_init_t init_func, table_compare_t comp_func, table_get_record_number_by_pointer_t get_record_func, table_free_entry_t entry_free_func, table_malloc_func_t malloc_func, table_realloc_func_t realloc_func, table_free_func_t free_func)
void *	table_get_record (const table_t *table, rec_t n)
void *	table_allocate_record (const table_t *table)
void *	table_allocate_record_with_size (const table_t *table, size_t size)
void	table_set_inform_add (table_t *table, table_alter_t add)
void	table_set_inform_remove (table_t *table, table_alter_t remove)
void	table_set_inform_change (table_t *table, table_alter_t change)
void	table_set_inform_user_data (table_t *table, void *user_data)
void	table_set_get_functions (table_t *table, table_get_function_t *array)
cfe_value_t *	table_get_value_by_number (const table_t *table, int field, rec_t n)
cfe_value_t *	table_get_value_by_record (const table_t *table, int field, void *record)
rec_t	table_store_start (const char *type, table_t *t, rec_t pos)
rec_t	table_store_return (table_t *t, rec_t pos, void *ptr)
rec_t	table_get_num_records (const table_t *t)
int8_t	table_check_type (const table_t *t, const char *type)
int8_t	table_validate (const table_t *t, rec_t i, const char *type)
int8_t	table_unique (table_t *t)
int8_t	table_diff (const table_t *t1, table_t *t2)
int8_t	table_sort (table_t *t)
rec_t	table_get_record_number_by_pointer (const table_t *t, void *r)
void	table_record_changed (const table_t *table, rec_t pos)
void	table_record_inserted (const table_t *table, rec_t pos)
void	table_record_removed (const table_t *table, rec_t pos)
int	table_entry_free (table_t *t, rec_t i)
void	table_entry_swap (table_t *t, rec_t i, rec_t j)
void	table_entry_move (table_t *t, rec_t from, rec_t to)
int	table_entry_free_move (table_t *t, rec_t i)
int	table_entry_free_move_by_ptr (table_t *t, void *ptr)
int	table_entry_free_block_move (table_t *t, rec_t first, rec_t last)
int	table_free (table_t *t)
void *	table_malloc_wrapper (const table_t *t, size_t size)
void *	table_realloc_wrapper (const table_t *t, void *ptr, size_t size)
void	table_free_wrapper (const table_t *t, void *)
char *	libcfe_tables_version (void)

Macro Definition Documentation

ADD_FIELD

#define ADD_FIELD	(		ID,
			FUNC
	)		get_functions[ID] = (table_get_function_t)(FUNC);

Macro to add a field definition to the INIT_TABLE_TYPE_WITH_FIELDS macro

Parameters

[in]	ID	Numberical value for this field.
[in]	FUNC	Function associated with this field.

Definition at line 288 of file tables.h.

INIT_TABLE_TYPE

#define INIT_TABLE_TYPE	(		NAME,
			TYPE
	)		INIT_TABLE_TYPE_WITH_FIELDS(NAME, TYPE, 0, (void)0;)

Shorthand for macro INIT_TABLE_TYPE_WITH_FIELDS.

See also

INIT_TABLE_TYPE_WITH_FIELDS

Parameters

[in]	NAME	Name this new table type.
[in]	TYPE	type of record.

Definition at line 296 of file tables.h.

INIT_TABLE_TYPE_DEF

#define INIT_TABLE_TYPE_DEF

(

NAME

)

Value:

table_t * NAME##_table_init(void); \
table_t * NAME##_table_init_with_allocator(table_malloc_func_t malloc_func, table_realloc_func_t realloc_func, table_free_func_t free_func);

This creates a *_table_init and *_table_init_with_allocator function definition for a new (custom) table type.

Parameters

[in]

NAME

Name this new table type.

Definition at line 279 of file tables.h.

INIT_TABLE_TYPE_WITH_FIELDS

#define INIT_TABLE_TYPE_WITH_FIELDS	(		NAME,
			TYPE,
			N_F,
			FIELDS
	)

Value:

table_t * NAME##_table_init(void) \
{ \
        return NAME##_table_init_with_allocator(table_malloc_wrapper, table_realloc_wrapper, table_free_wrapper); \
} \
table_t * NAME##_table_init_with_allocator(table_malloc_func_t malloc_func, table_realloc_func_t realloc_func, table_free_func_t free_func) \
{ \
        table_t *t = table_new(#NAME, sizeof(TYPE), NAME##_table_init, NAME##_table_compare, NAME##_table_get_record, NAME##_table_entry_free, malloc_func, realloc_func, free_func); \
        table_get_function_t *get_functions = (table_get_function_t *)malloc(N_F * sizeof(table_get_function_t)); \
	FIELDS \
	table_set_get_functions(t, get_functions); \
        return t; \
}

This creates a *_table_init and *_table_init_with_allocator functions for a new (custom) table type.

Parameters

[in]	NAME	Name this new table type.
[in]	TYPE	type of record.
[in]	N_F	Number of fields to add in the next argument
[in]	FIELDS	N_F amount of ADD_FIELD statements.

Definition at line 305 of file tables.h.

TABLE_STORE_RETURN

#define TABLE_STORE_RETURN	(		TABLE,
			P,
			PTR
	)		return table_store_return((table_t *)TABLE, (rec_t)P, (void *)PTR);

Helper macro to call at end of a custom *_table_store function. Internally it calls table_store_return. It will call return, so no code should follow this macro.

Parameters

[in]	TABLE	Pointer to the table.
[in]	P	Position of the insert.
[in]	PTR	Pointer to the record that needs to be inserted.

Definition at line 339 of file tables.h.

TABLE_STORE_START

#define TABLE_STORE_START	(		TABLE_TYPE,
			TABLE,
			P
	)

Value:

P = table_store_start(#TABLE_TYPE, (table_t *)TABLE, (rec_t)P); \
if(P == RECORD_INVALID) \
{ \
return RECORD_INVALID; \
}

Helper macro to be called at the start of a custom *_table_store function. Internally it calls table_store_start and checks the return value.

Parameters

[in]	TABLE_TYPE	unique (to this table type) character sequence to identify this type of table.
[in]	TABLE	Pointer to the table.
[in]	P	Desired position where insert.

Note

This macro can call return -1 in case of an error, ex. not enough memory.

Definition at line 326 of file tables.h.

Function Documentation

libcfe_tables_version()

char* libcfe_tables_version

(

void

)

Gives the version of the API.

Returns

A pointer to a character string describing the API version

table_allocate_record()

void* table_allocate_record

(

const table_t *

table

)

Allocate space for a record. The size of the allocated memory is taken from the soe parameter given to table_new.

Note

Only use this function if you want to add a record to the table.

Parameters

[in]

table

The table where the record is for.

Returns

A newly allocate piece of memory to store a record.

table_allocate_record_with_size()

void* table_allocate_record_with_size	(	const table_t *	table,
		size_t	size
	)

Allocate space for a record.

Note

Only use this function if you want to add a record to the table.

Parameters

[in]	table	The table where the record is for.
[in]	size	The size of the allocate memory.

Returns

A newly allocate piece of memory to store a record.

table_check_type()

int8_t table_check_type	(	const table_t *	t,
		const char *	type
	)

Check if the table type matches the given type string. The string should be unique to a table type.

Parameters

[in]	t	Pointer to the table.
[in]	type	string which is unique to this type of table.

Returns

If the table is of the requested type:

• 0 does not match the given type.
• 1 table is of the same type.

table_diff()

int8_t table_diff	(	const table_t *	t1,
		table_t *	t2
	)

Removes all entries in the second table which have an exact match in the first table. table one and two must be sorted tables and of the same type (or at least the should use the same compare function).

Parameters

[in]	t1	Pointer to the first table.
[in]	t2	Pointer to the second table.

Returns

0

table_entry_free()

int table_entry_free	(	table_t *	t,
		rec_t	i
	)

Free the memory used by a record, also calls the type specific free function to free memory allocation inside the record. The following records are not moved. So if the number is not the last record, it will leave a gap in the table. If this is a GTK Tree View (if enabled by defining _ENABLE_GTK) then the view is informed of the removal of the record.

Parameters

[in]	t	Pointer to the table.
[in]	i	Number of the record that should be freed.

Returns

Return 0 on success and -1 on an error, which means that nothing was freed.

table_entry_free_block_move()

int table_entry_free_block_move	(	table_t *	t,
		rec_t	first,
		rec_t	last
	)

Remove all records from first to last (including first and last). The following records are moved forward to fill the gap. If this is a GTK Tree View (if enabled by defining _ENABLE_GTK) then the view is informed of the removal of the record and the change of the other, moved, records.

Parameters

[in]	t	Pointer to the table.
[in]	first	First record to remove.
[in]	last	Last record to remove.

Returns

Return 0 on success and -1 on an error, which means that nothing was freed.

table_entry_free_move()

int table_entry_free_move	(	table_t *	t,
		rec_t	i
	)

Same as table_entry_free(table_t *, rec_t), except that the following records are moved to fill the resulting gap. If this is a GTK Tree View (if enabled by defining _ENABLE_GTK) then the view is informed of the removal of the record and the change of the other, moved, records.

Parameters

[in]	t	Pointer to the table.
[in]	i	Number of the record that should be freed.

Returns

Return 0 on success and -1 on an error, which means that nothing was freed or moved.

table_entry_free_move_by_ptr()

int table_entry_free_move_by_ptr	(	table_t *	t,
		void *	ptr
	)

Same as table_entry_free_move(table_t *, rec_t), except that the pointer to the record is given instead of the position. This table is search to the first matching pointer.

Parameters

[in]	t	Pointer to the table.
[in]	ptr	Pointer to the record that should be freed.

Returns

Return 0 on success and -1 on an error, which means that nothing was freed.

table_entry_move()

void table_entry_move	(	table_t *	t,
		rec_t	from,
		rec_t	to
	)

Move the record at the given position to the new position. It will free the new position if it already contains a record. If this is a GTK Tree View (if enabled by defining _ENABLE_GTK) then the view is informed of the change of the new position and the removal of the record at the old position.

Parameters

[in]	t	Pointer to the table.
[in]	from	Number of original position record.
[in]	to	Number of new position record.

table_entry_swap()

void table_entry_swap	(	table_t *	t,
		rec_t	i,
		rec_t	j
	)

Swap the two given records if position. If this is a GTK Tree View (if enabled by defining _ENABLE_GTK) then the view is informed of the change of the two record.

Parameters

[in]	t	Pointer to the table.
[in]	i	Number of the first record.
[in]	j	Number of the second record.

table_free()

int table_free

(

table_t *

t

)

Free the complete table and set all values to zero(0) or NULL and erase the type. This results in a uninitialized table, and therefore this table cannot be used until it is recreated first. The table_entry_free(table_t *, rec_t) function is called to free the records.

Parameters

[in]

t

Pointer to the table.

Returns

Return 0 on success and -1 on an error, which means that nothing was freed.

table_free_wrapper()

void table_free_wrapper	(	const table_t *	t,
		void *
	)

Wrapper for the standard free function, this is the default free function.

Parameters

[in]	t	Pointer to the table (unused).
[in]	ptr	Pointer to the current allocated memory.

table_get_num_records()

rec_t table_get_num_records

(

const table_t *

t

)

Returns the number of records in a table.

Parameters

[in]

t

Pointer to the table.

Returns

number of records in the given table.

table_get_record()

void* table_get_record	(	const table_t *	table,
		rec_t	n
	)

Return a pointer to the record at the n-th postion in the table.

Parameters

[in]	table	Pointer to a table instance to get the record from.
[in]	n	Record number to return.

Returns

Pointer to the requested record or NULL if n is not a valid record number.

table_get_record_number_by_pointer()

rec_t table_get_record_number_by_pointer	(	const table_t *	t,
		void *	r
	)

Get the record number corresponding to the given record, the record is retrieved by using the type specific get_record function

Parameters

[in]	t	Pointer to the table.
[in]	r	Record.

table_get_value_by_number()

cfe_value_t* table_get_value_by_number	(	const table_t *	table,
		int	field,
		rec_t	n
	)

table_get_value_by_record()

cfe_value_t* table_get_value_by_record	(	const table_t *	table,
		int	field,
		void *	record
	)

table_malloc_wrapper()

void* table_malloc_wrapper	(	const table_t *	t,
		size_t	size
	)

Wrapper for the standard malloc function, this is the default malloc function.

Parameters

[in]	t	Pointer to the table (unused).
[in]	size	Size of the requested memory block.

Returns

A pointer to the memory allocated by malloc.

table_new()

table_t* table_new	(	const char *	name,
		size_t	soe,
		table_init_t	init_func,
		table_compare_t	comp_func,
		table_get_record_number_by_pointer_t	get_record_func,
		table_free_entry_t	entry_free_func,
		table_malloc_func_t	malloc_func,
		table_realloc_func_t	realloc_func,
		table_free_func_t	free_func
	)

Create a new table instance. This function allocates the memory and initialize the table so it is ready to use. To destroy the table instance when finished, call table_free on it and after that call free on the pointer to also free the allocate memory.

Parameters

[in]	name	Name of the this table type.
[in]	soe	Size of a table record.
[in]	init_func	Pointer to the tables type specific init function.
[in]	comp_func	Pointer to the tables type specific compare function.
[in]	get_record_func	Pointer to the tables type specific get record function.
[in]	entry_free_func	Pointer to the tables type specific entr free function.
[in]	malloc_func	Function to use for data allocation.
[in]	realloc_func	Function to use for data reallocation.
[in]	free_func	Function to use for data deallocation.

Returns

A pointer to a newly allocated piece of memory which holds the table internals.

table_realloc_wrapper()

void* table_realloc_wrapper	(	const table_t *	t,
		void *	ptr,
		size_t	size
	)

Wrapper for the standard realloc function, this is the default realloc function.

Parameters

[in]	t	Pointer to the table (unused).
[in]	ptr	Pointer to the current allocated memory.
[in]	size	Size of the requested memory block.

Returns

A pointer to the memory allocated by realloc.

table_record_changed()

void table_record_changed	(	const table_t *	table,
		rec_t	pos
	)

Call this function to inform that a record has been changed. Then the appropriate callback function will be called.

Parameters

[in]	table	Pointer to the table.
[in]	pos	Number of the changes record.

table_record_inserted()

void table_record_inserted	(	const table_t *	table,
		rec_t	pos
	)

Call this function to inform that a record has been inserted into the table. Then the appropriate callback function will be called.

Parameters

[in]	table	Pointer to the table.
[in]	pos	Number of the new record.

table_record_removed()

void table_record_removed	(	const table_t *	table,
		rec_t	pos
	)

Call this function to inform that a record has been removed from the table. Then the appropriate callback function will be called.

Parameters

[in]	table	Pointer to the table.
[in]	pos	Number of the old, already removed, record.

table_set_get_functions()

void table_set_get_functions	(	table_t *	table,
		table_get_function_t *	array
	)

table_set_inform_add()

void table_set_inform_add	(	table_t *	table,
		table_alter_t	add
	)

table_set_inform_change()

void table_set_inform_change	(	table_t *	table,
		table_alter_t	change
	)

table_set_inform_remove()

void table_set_inform_remove	(	table_t *	table,
		table_alter_t	remove
	)

table_set_inform_user_data()

void table_set_inform_user_data	(	table_t *	table,
		void *	user_data
	)

table_sort()

int8_t table_sort

(

table_t *

t

)

Sorts the table using the type specific compare function.

Parameters

[in]

t

Pointer to the table.

Returns

0

Note

This function uses a recursive divide-and-conquer algorithm, in the style suggested by Knuth volume 3 (2nd edition), exercise 5.2.4-23. Use the optimization suggested by exercise 5.2.4-10; this requires room for only 1.5*N lines, rather than the usual 2*N lines. Knuth writes that this memory optimization was originally published by D. A. Bell, Comp J. 1 (1958), 75.

table_store_return()

rec_t table_store_return	(	table_t *	t,
		rec_t	pos,
		void *	ptr
	)

Helper function, this should be called at the end of a custom *_table_store function. It stores the record at the given position, increase the index counter and informs the GTK Tree View (if enabled by defining _ENABLE_GTK) of the insert.

Parameters

[in]	t	Pointer to the table.
[in]	pos	Position of the new record (there is no check if this position is free or the next available free position).
[in]	ptr	Pointer to the record, the pointer is stored at the given position in the table.

Returns

The inserted position.

table_store_start()

rec_t table_store_start	(	const char *	type,
		table_t *	t,
		rec_t	pos
	)

Helper function, this should be called at the start of a custom *_table_store function. It validates the table, resize the table (if necessary) and moves the records if the inserted position is not at the end of the table. It also informs the GTK Tree View (if enabled by defining _ENABLE_GTK) of moves.

Parameters

[in]	type	string which is unique to this type of table.
[in]	t	Pointer to the table.
[in]	pos	Desired position of the new record.

Returns

The position where the new record should be inserted.

table_unique()

int8_t table_unique

(

table_t *

t

)

Remove repeated series of the same record in a sorted table. It compares records with the type specific compare function. If two consecutive records are considered equal, then the later record is removed. This will continue until each next record is considered different than the previous one. The table should be sorted by the table_sort(table_t *) function first.

Parameters

[in]

t

Pointer to the table.

Returns

- 0 success

• -1 failed

table_validate()

int8_t table_validate	(	const table_t *	t,
		rec_t	i,
		const char *	type
	)

Check if the table is a valide instance and that it contains at least the requested number of records. The string should be unique to a table type.

Parameters

[in]	t	Pointer to the table.
[in]	i	requested record.
[in]	type	string which is unique to this type of table.

Returns

If the table is of the requested type:

• 0 does not match the given type or has less records.
• 1 table is of the same type and has at least the requested records.