paf_props.h File Reference

Pathfinder Service Properties API. More...

#include <sys/types.h>
#include <paf_value.h>

Go to the source code of this file.

Typedefs
typedef void(*	paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user)

Functions
struct paf_props *	paf_props_create (void)
void	paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value)
void	paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value)
void	paf_props_add_str (struct paf_props *props, const char *name, const char *value)
size_t	paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity)
const struct paf_value *	paf_props_get_one (const struct paf_props *props, const char *prop_name)
void	paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user)
bool	paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b)
size_t	paf_props_num_values (const struct paf_props *props)
size_t	paf_props_num_names (const struct paf_props *props)
struct paf_props *	paf_props_clone (const struct paf_props *orig)
void	paf_props_destroy (struct paf_props *props)

Detailed Description

Pathfinder Service Properties API.

Service properties are a multimap. Thus, each property name may be assoicated to one or more values.

Typedef Documentation

paf_props_foreach_cb

typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user)

Callback function prototype used for iteration.

Function Documentation

paf_props_create()

struct paf_props * paf_props_create

(

void

)

Create a service properties instance.

Returns

An empty service properties instance.

paf_props_add()

void paf_props_add	(	struct paf_props *	props,
		const char *	name,
		const struct paf_value *	value
	)

Add a property.

This function adds a property to props.

Both the name and the value will be copied, and thus will still be owned by the caller at call completion.

Parameters

[in]	props	The service properties instance.
[in]	name	The name of the property to be added.
[in]	value	The value of the property to be added.

paf_props_add_int64()

void paf_props_add_int64	(	struct paf_props *	props,
		const char *	name,
		int64_t	value
	)

Add a property with an integer value.

This function adds a property with an integer value to props.

Parameters

[in]	props	The service properties instance.
[in]	name	The name of the property to be added.
[in]	value	The value of the property to be added.

paf_props_add_str()

void paf_props_add_str	(	struct paf_props *	props,
		const char *	name,
		const char *	value
	)

Add a property with a string value.

This function adds a property with a string value to props.

Parameters

[in]	props	The service properties instance.
[in]	name	The name of the property to be added.
[in]	value	The value of the property to be added.

paf_props_get()

size_t paf_props_get	(	const struct paf_props *	props,
		const char *	prop_name,
		const struct paf_value **	values,
		size_t	capacity
	)

Retrieve all values for a particular property.

This function retrieves the zero-or-more values associated with the supplied prop_name, and stores them in values.

If values' capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props will be returned regardless.

In case capacity is 0, props may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values array, before the actual paf_props_get() call.

Parameters

[in]	props	The service properties instance.
[in]	prop_name	The name of the property whose values is to be retrieved.
[out]	values	A pointer to an user-allocated array of paf_value pointers.
[in]	capacity	The number of elements values can hold.

Returns

Returns the number of values associated with prop_name (even in the case this number is larger than capacity).

paf_props_get_one()

const struct paf_value * paf_props_get_one	(	const struct paf_props *	props,
		const char *	prop_name
	)

Retrieve a value for a particular property.

This function returns a value associated with the supplied prop_name.

Parameters

[in]	props	The service properties instance.
[in]	prop_name	The name of the property whose value is to be retrieved.

Returns

Returns one of the values associated with prop_name, or NULL in case there is none.

paf_props_foreach()

void paf_props_foreach	(	const struct paf_props *	props,
		paf_props_foreach_cb	cb,
		void *	user
	)

Iterate over all name-value pairs.

This function calls the supplied callback function cb for each property name-value pair in props.

props may not be modified during the iteration.

Parameters

[in]	props	The service properties instance.
[in]	cb	The callback function.
[in]	user	An opaque pointer, supplied back to the application in every cb call.

paf_props_equal()

bool paf_props_equal	(	const struct paf_props *	props_a,
		const struct paf_props *	props_b
	)

Compares two property multimaps for equality (by value).

Parameters

[in]	props_a	A service properties instance.
[in]	props_b	A service properties instance.

Returns

Returns true if props_a and props_b are equal, false otherwise.

paf_props_num_values()

size_t paf_props_num_values

(

const struct paf_props *

props

)

Returns the total number of property name-value pairs.

This function returns the total number of name-value pairs in the properties instance.

Parameters

[in]

props

The service properties instance.

Returns

Returns the total number of values.

paf_props_num_names()

size_t paf_props_num_names

(

const struct paf_props *

props

)

Returns the total number of property names in the properties instance.

Parameters

[in]

props

The service properties instance.

Returns

Returns the total number of names.

paf_props_clone()

struct paf_props * paf_props_clone

(

const struct paf_props *

orig

)

Returns a copy of the supplied properties instance.

Parameters

[in]

orig

The service properties instance to be copied.

Returns

Returns a copy of the properties instance.

paf_props_destroy()

void paf_props_destroy

(

struct paf_props *

props

)

Destroys a properties instance.

This function destroys the properties instance and frees all the resources associated with it.

Parameters

[in]

props

The service properties instance.