libcapskeyvalue.c File Reference

Simple manager for key/value data pairs in a autosize table. More...

Data Structures
struct	key_value

Macros
#define	INCREMENT_STEP   10

Functions
void	caps_libkv_init (void)
static void	init_key_value (struct key_value *kv)
static void	cleanup_key_value (struct key_value *kv)
static struct key_value *	create_new_key_value_pair (struct caps_kv_table *kvt)
const char *	caps_kv_keys_value_get (const struct caps_kv_table *kvt, const char *key)
void	caps_kv_raw_entry_get (const struct caps_kv_table *kvt, size_t entry, const char **key, const char **value)
void	caps_kv_key_value_add (struct caps_kv_table *kvt, const char *key, const char *value)
void	caps_kv_keys_value_set (struct caps_kv_table *kvt, const char *key, const char *val)
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)
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)
static bool	is_keyword (int c)
static bool	is_value (int c)
static ssize_t	split_key_value (const unsigned char *string, char **key, char **value)
int	caps_kv_key_value_parse_from_string (struct caps_kv_table *kvt, const char *string)

Variables
static const struct caps_table_desc	key_value_desc
static const char	its_true [] = "true"

Detailed Description

Author

Jürgen Borleis

Copyright

GNU Lesser General Public License 2.1

Warning

Use as experimental

Macro Definition Documentation

INCREMENT_STEP

#define INCREMENT_STEP   10

Whenever the dynamic array is exhausted, create additionally 10 elements

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

init_key_value()

static void init_key_value ( struct key_value *  kv )

static

Init a key/value structure

Parameters

[in,out]

kv

The key/value structure to init

cleanup_key_value()

static void cleanup_key_value ( struct key_value *  kv )

static

Destroy a key/value structure

Parameters

[in,out]

kv

The key/value structure to destroy

create_new_key_value_pair()

static struct key_value * create_new_key_value_pair ( struct caps_kv_table *  kvt )

static

Create a new key/value structure

Parameters

[in,out]

kvt

The key/value table structure

Returns

A new key/value structure

Note

This function does not return in case of memory failure.

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_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_key_value_add()

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

Todo:

needs locking!!!!

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
	)

Todo:

needs locking!!!!

Todo:

run-time check

Todo:

run-time check

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

)

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
	)

Todo:

source table needs locking!!!!

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.

is_keyword()

static bool is_keyword ( int  c )

static

Control the supported delimiters for key/value strings.

It's still unclear what strings are to be expected: KDE3 will use the space as the delimiter like this:

"sides=two-sided-long-edge copies=2 ColorModel=Mono Duplex=DuplexNoTumble"

but the manpage of cupsdoprint-trinity uses the comma as the delimiter:

"sides=two-sided-long-edge,copies=2,ColorModel=Mono,Duplex=DuplexNoTumble"

But the latter one will conflict with the 'page-ranges' option, which also uses the comma as the delimiter to the next range:

"page-ranges=1-4,7,9-12"

Or the 'media' entry: "media=A4,Normal,Upper" Check if the given character is an allowed one for a keyword

Parameters

[in]

c

The character to check

Returns

'true' if the character is allowed for a keyword, 'false' if not

All kind of characters are allowed for a keyword. Delimiters are:

• a space (for keys without a value)
• a comma (it's still unclear, for keys without a value -> conflicts with page-ranges!)
• '='
• '\0' end of string

is_value()

static bool is_value ( int  c )

static

Check if the given character is an allowed one for a value

Parameters

[in]

c

The character to check

Returns

'true' if the character is allowed for a value, 'false' if not

All kind of characters are allowed for a value. Delimiters are:

• a space
• a comma (it's still unclear -> conflicts with page-ranges!)
• '\0' end of string

split_key_value()

static ssize_t split_key_value ( const unsigned char *  string, char **  key, char **  value  )

static

Split the first key/value pair from the given string

Parameters

[in]	string	String to work on ('\0' terminated)
[out]	key	Where to store the 'key' string
[out]	value	Where to store the 'value' string

Returns

consumed characters from string, negative errno on error

In case of failure, key and value are undefined!

Note

Does not return in case of memory failure

Precondition

A keyword must start with an alpha character

Note

*value will be NULL if the keyword has no parameter, *key will be NULL if string was empty

With trailing whitespaces in string the consumed characters returned are positive, but *key and *value are still NULL!

All returned 'key'/'value' strings are created with strdup(), so they need to be freed if no longer used.

If it returns 0, the string is (now) empty and *key and *value are NULL

Examples:

• 'mirror' -> *key = 'mirror', *value = NULL (used as a boolean option)
• 'option=' -> *key = 'option', *value = NULL (used as a boolen option)
• 'copies=1' -> *key = 'copies', *value = '1'

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!

Variable Documentation

key_value_desc

const struct caps_table_desc key_value_desc

static

Initial value:

= {
    .element_sz = sizeof(struct key_value),
    .increment =  10 ,
}

its_true

const char its_true[] = "true"

static

The static return for a boolean key. If it is given without a value, it defaults to 'true'