libcapskeyvalue.h File Reference

API declaration to handle key/value pairs in a (dynamic) table. More...

Go to the source code of this file.

Data Structures
struct	caps_kv_table

Functions
void	caps_libkv_init (void)
void	caps_kv_init (struct caps_kv_table *kvt)
void	caps_kv_cleanup (struct caps_kv_table *kvt)
void	caps_kv_duplicate (struct caps_kv_table *dst, const struct caps_kv_table *src)
void	caps_kv_key_value_add (struct caps_kv_table *kvt, const char *key, const char *value)
const char *	caps_kv_keys_value_get (const struct caps_kv_table *kvt, const char *key)
void	caps_kv_keys_value_set (struct caps_kv_table *kvt, const char *key, const char *val)
void	caps_kv_raw_entry_get (const struct caps_kv_table *kvt, size_t entry, const char **key, const char **val)
const struct key_value *	caps_kv_base_get (const struct caps_kv_table *kvt)
size_t	caps_kv_element_count_get (const struct caps_kv_table *kvt)
int	caps_kv_key_value_parse_from_string (struct caps_kv_table *kvt, const char *string)

Detailed Description

Author

Jürgen Borleis

Copyright

GNU Lesser General Public License 2.1

Author

Jürgen Borleis

Warning

Use as experimental

Function Documentation

caps_libkv_init()

void caps_libkv_init

(

void

)

Initialize the library prior use

Mostly sets up NLS (if enabled) and its internally used libraries.

Note

Does not return in case of memory failure

caps_kv_init()

void caps_kv_init

(

struct caps_kv_table *

kvt

)

Init a table to handle key/value pairs

Parameters

[in,out]

kvt

The table to init

Todo:

run-time check

caps_kv_cleanup()

void caps_kv_cleanup

(

struct caps_kv_table *

kvt

)

Free resources occupied by a key/value table

Parameters

[in,out]

kvt

the table to free

Todo:

needs locking!!!!

Todo:

run-time check

caps_kv_duplicate()

void caps_kv_duplicate	(	struct caps_kv_table *	dst,
		const struct caps_kv_table *	src
	)

Create a copy of an existing key/value table

Parameters

[out]	dst	Destination key/value table
[in]	src	Source key/value table

Note

In the case of memory failure it does not return

Todo:

source table needs locking!!!!

Todo:

run-time check

Todo:

run-time check

caps_kv_key_value_add()

void caps_kv_key_value_add	(	struct caps_kv_table *	kvt,
		const char *	key,
		const char *	value
	)

Append a key/value entry to the table

Parameters

[in,out]	kvt	The table to add the new key/value pair to
[in]	key	The key component
[in]	value	The corresponding value (can be NULL)

Note

All strings are copied

If value is NULL, the key is treated as a boolean and 'true'

key handling is non case sensitive!

In the case of memory failure it does not return

Todo:

needs locking!!!!

Todo:

run-time check

Todo:

run-time check

caps_kv_keys_value_get()

const char * caps_kv_keys_value_get	(	const struct caps_kv_table *	kvt,
		const char *	key
	)

Query the value of the given key

Parameters

[in]	kvt	The key/value table to search in
[in]	key	The key to search for

Return values

string	Pointer to the value
NULL	If not found

If a key is found but has no value, it is treated as a boolean key and the return value is always the string 'true'.

Note

key handling is non case sensitive!

Todo:

run-time check

Todo:

run-time check

caps_kv_keys_value_set()

void caps_kv_keys_value_set	(	struct caps_kv_table *	kvt,
		const char *	key,
		const char *	val
	)

Set a new value for the given key

Parameters

[in,out]	kvt	The key/value table to alter
[in]	key	The key to search for
[in]	val	The key's new value

If the key is not found, it will be created instead.

Note

key is handled non case sensitive!

In the case of memory failure it does not return

Todo:

needs locking!!!!

Todo:

run-time check

Todo:

run-time check

caps_kv_raw_entry_get()

void caps_kv_raw_entry_get	(	const struct caps_kv_table *	kvt,
		size_t	entry,
		const char **	key,
		const char **	val
	)

Retrieve the data of the specified raw table entry

Parameters

[in]	kvt	The table to get the raw key/value pair from
[in]	entry	Element number
[out]	key	Where to store the key component
[out]	val	Where to store the value component

Note

In the case of any failure it does not return

Todo:

run-time check

Todo:

run-time check

Todo:

run-time check

caps_kv_base_get()

const struct key_value * caps_kv_base_get

(

const struct caps_kv_table *

kvt

)

Retrieve the array's base pointer

Parameters

[in]

kvt

The table to get its base pointer from

Return values

table	Base address of the managed table
NULL	If the table is uninitialized and thus, empty.

Note

After adding new elements the base pointer must be retrieved again!

caps_kv_element_count_get()

size_t caps_kv_element_count_get

(

const struct caps_kv_table *

kvt

)

Retrieve the array's used elements count

Parameters

[in]

kvt

The table to get the elements count from

Return values

number	Elements count
0	If the array is empty.

caps_kv_key_value_parse_from_string()

int caps_kv_key_value_parse_from_string	(	struct caps_kv_table *	kvt,
		const char *	string
	)

Parse a string with key/value pairs and split and store them into a key/value table

Parameters

[in,out]	kvt	The key/value table where to store the result
[in]	string	The string to parse (can be NULL, in this case nothing will be done)

Return values

0	on success
negative	errno

The string can be of the form

  TonerDensity=1 copies=1 orientation-requested=3

e.g. the key/value delimiter is space and the equal character separates key and value.

Note

The equal character can be omitted, if the key has no value

Keys without a value are treated as a boolean and default to 'true'

This function intended to split the so called 'printing parameters'

Precondition

kvt must be already initialized!