Typedefs
typedef void *	plist_t
	The basic plist abstract data type.

typedef void *	plist_dict_iter
	The plist dictionary iterator.

Enumerations
enum	plist_type { PLIST_BOOLEAN, PLIST_UINT, PLIST_REAL, PLIST_STRING, PLIST_ARRAY, PLIST_DICT, PLIST_DATE, PLIST_DATA, PLIST_KEY, PLIST_UID, PLIST_NONE }
	The enumeration of plist node types. More...

Functions
plist_t	plist_new_dict (void)
	Create a new root plist_t type PLIST_DICT. More...

plist_t	plist_new_array (void)
	Create a new root plist_t type PLIST_ARRAY. More...

plist_t	plist_new_string (const char *val)
	Create a new plist_t type PLIST_STRING. More...

plist_t	plist_new_bool (uint8_t val)
	Create a new plist_t type PLIST_BOOLEAN. More...

plist_t	plist_new_uint (uint64_t val)
	Create a new plist_t type PLIST_UINT. More...

plist_t	plist_new_real (double val)
	Create a new plist_t type PLIST_REAL. More...

plist_t	plist_new_data (const char *val, uint64_t length)
	Create a new plist_t type PLIST_DATA. More...

plist_t	plist_new_date (int32_t sec, int32_t usec)
	Create a new plist_t type PLIST_DATE. More...

plist_t	plist_new_uid (uint64_t val)
	Create a new plist_t type PLIST_UID. More...

void	plist_free (plist_t plist)
	Destruct a plist_t node and all its children recursively. More...

plist_t	plist_copy (plist_t node)
	Return a copy of passed node and it's children. More...

uint32_t	plist_array_get_size (plist_t node)
	Get size of a PLIST_ARRAY node. More...

plist_t	plist_array_get_item (plist_t node, uint32_t n)
	Get the nth item in a PLIST_ARRAY node. More...

uint32_t	plist_array_get_item_index (plist_t node)
	Get the index of an item. More...

void	plist_array_set_item (plist_t node, plist_t item, uint32_t n)
	Set the nth item in a PLIST_ARRAY node. More...

void	plist_array_append_item (plist_t node, plist_t item)
	Append a new item at the end of a PLIST_ARRAY node. More...

void	plist_array_insert_item (plist_t node, plist_t item, uint32_t n)
	Insert a new item at position n in a PLIST_ARRAY node. More...

void	plist_array_remove_item (plist_t node, uint32_t n)
	Remove an existing position in a PLIST_ARRAY node. More...

uint32_t	plist_dict_get_size (plist_t node)
	Get size of a PLIST_DICT node. More...

void	plist_dict_new_iter (plist_t node, plist_dict_iter *iter)
	Create an iterator of a PLIST_DICT node. More...

void	plist_dict_next_item (plist_t node, plist_dict_iter iter, char *key, plist_t val)
	Increment iterator of a PLIST_DICT node. More...

void	plist_dict_get_item_key (plist_t node, char **key)
	Get key associated to an item. More...

plist_t	plist_dict_get_item (plist_t node, const char *key)
	Get the nth item in a PLIST_DICT node. More...

void	plist_dict_set_item (plist_t node, const char *key, plist_t item)
	Set item identified by key in a PLIST_DICT node. More...

void	plist_dict_insert_item (plist_t node, const char *key, plist_t item)
	Insert a new item into a PLIST_DICT node. More...

void	plist_dict_remove_item (plist_t node, const char *key)
	Remove an existing position in a PLIST_DICT node. More...

void	plist_dict_merge (plist_t *target, plist_t source)
	Merge a dictionary into another. More...

plist_t	plist_get_parent (plist_t node)
	Get the parent of a node. More...

plist_type	plist_get_node_type (plist_t node)
	Get the plist_type of a node. More...

void	plist_get_key_val (plist_t node, char **val)
	Get the value of a PLIST_KEY node. More...

void	plist_get_string_val (plist_t node, char **val)
	Get the value of a PLIST_STRING node. More...

void	plist_get_bool_val (plist_t node, uint8_t *val)
	Get the value of a PLIST_BOOLEAN node. More...

void	plist_get_uint_val (plist_t node, uint64_t *val)
	Get the value of a PLIST_UINT node. More...

void	plist_get_real_val (plist_t node, double *val)
	Get the value of a PLIST_REAL node. More...

void	plist_get_data_val (plist_t node, char *val, uint64_t length)
	Get the value of a PLIST_DATA node. More...

void	plist_get_date_val (plist_t node, int32_t sec, int32_t usec)
	Get the value of a PLIST_DATE node. More...

void	plist_get_uid_val (plist_t node, uint64_t *val)
	Get the value of a PLIST_UID node. More...

void	plist_set_key_val (plist_t node, const char *val)
	Set the value of a node. More...

void	plist_set_string_val (plist_t node, const char *val)
	Set the value of a node. More...

void	plist_set_bool_val (plist_t node, uint8_t val)
	Set the value of a node. More...

void	plist_set_uint_val (plist_t node, uint64_t val)
	Set the value of a node. More...

void	plist_set_real_val (plist_t node, double val)
	Set the value of a node. More...

void	plist_set_data_val (plist_t node, const char *val, uint64_t length)
	Set the value of a node. More...

void	plist_set_date_val (plist_t node, int32_t sec, int32_t usec)
	Set the value of a node. More...

void	plist_set_uid_val (plist_t node, uint64_t val)
	Set the value of a node. More...

void	plist_to_xml (plist_t plist, char *plist_xml, uint32_t length)
	Export the plist_t structure to XML format. More...

void	plist_to_bin (plist_t plist, char *plist_bin, uint32_t length)
	Export the plist_t structure to binary format. More...

void	plist_from_xml (const char plist_xml, uint32_t length, plist_t plist)
	Import the plist_t structure from XML format. More...

void	plist_from_bin (const char plist_bin, uint32_t length, plist_t plist)
	Import the plist_t structure from binary format. More...

plist_t	plist_access_path (plist_t plist, uint32_t length,...)
	Get a node from its path. More...

plist_t	plist_access_pathv (plist_t plist, uint32_t length, va_list v)
	Variadic version of plist_access_path. More...

char	plist_compare_node_value (plist_t node_l, plist_t node_r)
	Compare two node values. More...

Detailed Description

Enumeration Type Documentation

enum plist_type

The enumeration of plist node types.

Enumerator
PLIST_BOOLEAN	Boolean, scalar type.
PLIST_UINT	Unsigned integer, scalar type.
PLIST_REAL	Real, scalar type.
PLIST_STRING	ASCII string, scalar type.
PLIST_ARRAY	Ordered array, structured type.
PLIST_DICT	Unordered dictionary (key/value pair), structured type.
PLIST_DATE	Date, scalar type.
PLIST_DATA	Binary data, scalar type.
PLIST_KEY	Key in dictionaries (ASCII String), scalar type.
PLIST_UID	Special type used for 'keyed encoding'.
PLIST_NONE	No type.

Function Documentation

plist_t plist_access_path	(	plist_t	plist,
		uint32_t	length,
			...
	)

Get a node from its path.

Each path element depends on the associated father node type. For Dictionaries, var args are casted to const char*, for arrays, var args are caster to uint32_t Search is breath first order.

Parameters

plist	the node to access result from.
length	length of the path to access

Returns: the value to access.

References plist_access_pathv(), PLIST_ARRAY, PLIST_BOOLEAN, PLIST_DATA, PLIST_DATE, PLIST_DICT, PLIST_KEY, PLIST_REAL, PLIST_STRING, PLIST_UID, and PLIST_UINT.

plist_t plist_access_pathv	(	plist_t	plist,
		uint32_t	length,
		va_list	v
	)

Variadic version of plist_access_path.

Parameters

plist	the node to access result from.
length	length of the path to access
v	list of array's index and dic'st key

Returns: the value to access.

References PLIST_ARRAY, plist_array_get_item(), PLIST_DICT, plist_dict_get_item(), plist_get_node_type(), and PLIST_NONE.

Referenced by plist_access_path().

void plist_array_append_item	(	plist_t	node,
		plist_t	item
	)

Append a new item at the end of a PLIST_ARRAY node.

Parameters

node	the node of type PLIST_ARRAY
item	the new item. The array is responsible for freeing item when it is no longer needed.

References PLIST_ARRAY, and plist_get_node_type().

plist_t plist_array_get_item	(	plist_t	node,
		uint32_t	n
	)

Get the nth item in a PLIST_ARRAY node.

Parameters

node	the node of type PLIST_ARRAY
n	the index of the item to get. Range is [0, array_size[

Returns: the nth item or NULL if node is not of type PLIST_ARRAY

References PLIST_ARRAY, and plist_get_node_type().

Referenced by plist_access_pathv(), plist_array_remove_item(), and plist_array_set_item().

uint32_t plist_array_get_item_index ( plist_t node )

Get the index of an item.

item must be a member of a PLIST_ARRAY node.

Parameters

node the node

Returns: the node index

References PLIST_ARRAY, plist_get_node_type(), and plist_get_parent().

uint32_t plist_array_get_size ( plist_t node )

Get size of a PLIST_ARRAY node.

Parameters

node	the node of type PLIST_ARRAY

Returns: size of the PLIST_ARRAY node

References PLIST_ARRAY, and plist_get_node_type().

void plist_array_insert_item	(	plist_t	node,
		plist_t	item,
		uint32_t	n
	)

Insert a new item at position n in a PLIST_ARRAY node.

Parameters

node	the node of type PLIST_ARRAY
item	the new item to insert. The array is responsible for freeing item when it is no longer needed.
n	The position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range.

References PLIST_ARRAY, and plist_get_node_type().

void plist_array_remove_item	(	plist_t	node,
		uint32_t	n
	)

Remove an existing position in a PLIST_ARRAY node.

Removed position will be freed using plist_free.

Parameters

node	the node of type PLIST_ARRAY
n	The position to remove. Range is [0, array_size[. Assert if n is not in range.

References PLIST_ARRAY, plist_array_get_item(), plist_free(), and plist_get_node_type().

void plist_array_set_item	(	plist_t	node,
		plist_t	item,
		uint32_t	n
	)

Set the nth item in a PLIST_ARRAY node.

The previous item at index n will be freed using plist_free

Parameters

node	the node of type PLIST_ARRAY
item	the new item at index n. The array is responsible for freeing item when it is no longer needed.
n	the index of the item to get. Range is [0, array_size[. Assert if n is not in range.

References PLIST_ARRAY, plist_array_get_item(), and plist_get_node_type().

char plist_compare_node_value	(	plist_t	node_l,
		plist_t	node_r
	)

Compare two node values.

Parameters

node_l	left node to compare
node_r	rigth node to compare

Returns: TRUE is type and value match, FALSE otherwise.

References PLIST_ARRAY, PLIST_BOOLEAN, PLIST_DATA, PLIST_DATE, PLIST_DICT, PLIST_KEY, PLIST_REAL, PLIST_STRING, PLIST_UID, and PLIST_UINT.

plist_t plist_copy ( plist_t node )

Return a copy of passed node and it's children.

Parameters

node	the plist to copy

Returns: copied plist

Referenced by plist_dict_merge().

plist_t plist_dict_get_item	(	plist_t	node,
		const char *	key
	)

Get the nth item in a PLIST_DICT node.

Parameters

node	the node of type PLIST_DICT
key	the identifier of the item to get.

Returns: the item or NULL if node is not of type PLIST_DICT. The caller should not free the returned node.

References PLIST_DICT, plist_get_node_type(), and PLIST_KEY.

Referenced by plist_access_pathv(), plist_dict_remove_item(), and plist_dict_set_item().

void plist_dict_get_item_key	(	plist_t	node,
		char **	key
	)

Get key associated to an item.

Item must be member of a dictionary

Parameters

node	the node
key	a location to store the key. The caller is responsible for freeing the returned string.

References PLIST_DICT, plist_get_key_val(), plist_get_node_type(), and plist_get_parent().

uint32_t plist_dict_get_size ( plist_t node )

Get size of a PLIST_DICT node.

Parameters

node	the node of type PLIST_DICT

Returns: size of the PLIST_DICT node

References PLIST_DICT, and plist_get_node_type().

void plist_dict_insert_item	(	plist_t	node,
		const char *	key,
		plist_t	item
	)

Insert a new item into a PLIST_DICT node.

Deprecated:: Deprecated. Use plist_dict_set_item instead.

Parameters

node	the node of type PLIST_DICT
item	the new item to insert
key	The identifier of the item to insert.

References plist_dict_set_item().

void plist_dict_merge	(	plist_t *	target,
		plist_t	source
	)

Merge a dictionary into another.

This will add all key/value pairs from the source dictionary to the target dictionary, overwriting any existing key/value pairs that are already present in target.

Parameters

target	pointer to an existing node of type PLIST_DICT
source	node of type PLIST_DICT that should be merged into target

References plist_copy(), PLIST_DICT, plist_dict_new_iter(), plist_dict_next_item(), plist_dict_set_item(), and plist_get_node_type().

void plist_dict_new_iter	(	plist_t	node,
		plist_dict_iter *	iter
	)

Create an iterator of a PLIST_DICT node.

The allocated iterator should be freed with the standard free function.

Parameters

node	the node of type PLIST_DICT
iter	iterator of the PLIST_DICT node

Referenced by plist_dict_merge().

void plist_dict_next_item	(	plist_t	node,
		plist_dict_iter	iter,
		char **	key,
		plist_t *	val
	)

Increment iterator of a PLIST_DICT node.

Parameters

node	the node of type PLIST_DICT
iter	iterator of the dictionary
key	a location to store the key, or NULL. The caller is responsible for freeing the the returned string.
val	a location to store the value, or NULL. The caller should not free the returned value.

References PLIST_DICT, plist_get_key_val(), and plist_get_node_type().

Referenced by plist_dict_merge().

void plist_dict_remove_item	(	plist_t	node,
		const char *	key
	)

Remove an existing position in a PLIST_DICT node.

Removed position will be freed using plist_free

Parameters

node	the node of type PLIST_DICT
key	The identifier of the item to remove. Assert if identifier is not present.

References PLIST_DICT, plist_dict_get_item(), plist_free(), and plist_get_node_type().

void plist_dict_set_item	(	plist_t	node,
		const char *	key,
		plist_t	item
	)

Set item identified by key in a PLIST_DICT node.

The previous item identified by key will be freed using plist_free. If there is no item for the given key a new item will be inserted.

Parameters

node	the node of type PLIST_DICT
item	the new item associated to key
key	the identifier of the item to set.

References PLIST_DICT, plist_dict_get_item(), and plist_get_node_type().

Referenced by plist_dict_insert_item(), and plist_dict_merge().

void plist_free ( plist_t plist )

Destruct a plist_t node and all its children recursively.

Parameters

plist the plist to free

References PLIST_DATA, plist_get_node_type(), PLIST_KEY, PLIST_NONE, and PLIST_STRING.

Referenced by plist_array_remove_item(), plist_dict_remove_item(), and plist_from_bin().

void plist_from_bin	(	const char *	plist_bin,
		uint32_t	length,
		plist_t *	plist
	)

Import the plist_t structure from binary format.

Parameters

plist_bin	a pointer to the xml buffer.
length	length of the buffer to read.
plist	a pointer to the imported plist.

References PLIST_ARRAY, PLIST_BOOLEAN, PLIST_DATA, PLIST_DATE, PLIST_DICT, plist_free(), PLIST_KEY, PLIST_REAL, PLIST_STRING, PLIST_UID, and PLIST_UINT.

void plist_from_xml	(	const char *	plist_xml,
		uint32_t	length,
		plist_t *	plist
	)

Import the plist_t structure from XML format.

Parameters

plist_xml	a pointer to the xml buffer.
length	length of the buffer to read.
plist	a pointer to the imported plist.

void plist_get_bool_val	(	plist_t	node,
		uint8_t *	val
	)

Get the value of a PLIST_BOOLEAN node.

This function does nothing if node is not of type PLIST_BOOLEAN

Parameters

node	the node
val	a pointer to a uint8_t variable.

References PLIST_BOOLEAN, and plist_get_node_type().

void plist_get_data_val	(	plist_t	node,
		char **	val,
		uint64_t *	length
	)

Get the value of a PLIST_DATA node.

This function does nothing if node is not of type PLIST_DATA

Parameters

node	the node
val	a pointer to an unallocated char buffer. This function allocates the memory, caller is responsible for freeing it.
length	the length of the buffer

References PLIST_DATA, and plist_get_node_type().

void plist_get_date_val	(	plist_t	node,
		int32_t *	sec,
		int32_t *	usec
	)

Get the value of a PLIST_DATE node.

This function does nothing if node is not of type PLIST_DATE

Parameters

node	the node
sec	a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001.
usec	a pointer to an int32_t variable. Represents the number of microseconds

References PLIST_ARRAY, PLIST_BOOLEAN, PLIST_DATA, PLIST_DATE, PLIST_DICT, plist_get_node_type(), PLIST_KEY, PLIST_REAL, PLIST_STRING, PLIST_UID, and PLIST_UINT.

void plist_get_key_val	(	plist_t	node,
		char **	val
	)

Get the value of a PLIST_KEY node.

This function does nothing if node is not of type PLIST_KEY

Parameters

node	the node
val	a pointer to a C-string. This function allocates the memory, caller is responsible for freeing it.

References plist_get_node_type(), and PLIST_KEY.

Referenced by plist_dict_get_item_key(), and plist_dict_next_item().

plist_type plist_get_node_type ( plist_t node )

Get the plist_type of a node.

Parameters

node the node

Returns: the type of the node

References PLIST_NONE.

Referenced by plist_access_pathv(), plist_array_append_item(), plist_array_get_item(), plist_array_get_item_index(), plist_array_get_size(), plist_array_insert_item(), plist_array_remove_item(), plist_array_set_item(), plist_dict_get_item(), plist_dict_get_item_key(), plist_dict_get_size(), plist_dict_merge(), plist_dict_next_item(), plist_dict_remove_item(), plist_dict_set_item(), plist_free(), plist_get_bool_val(), plist_get_data_val(), plist_get_date_val(), plist_get_key_val(), plist_get_real_val(), plist_get_string_val(), plist_get_uid_val(), and plist_get_uint_val().

plist_t plist_get_parent ( plist_t node )

Get the parent of a node.

Parameters

node	the parent (NULL if node is root)

Referenced by plist_array_get_item_index(), and plist_dict_get_item_key().

void plist_get_real_val	(	plist_t	node,
		double *	val
	)

Get the value of a PLIST_REAL node.

This function does nothing if node is not of type PLIST_REAL

Parameters

node	the node
val	a pointer to a double variable.

References plist_get_node_type(), and PLIST_REAL.

void plist_get_string_val	(	plist_t	node,
		char **	val
	)

Get the value of a PLIST_STRING node.

This function does nothing if node is not of type PLIST_STRING

Parameters

node	the node
val	a pointer to a C-string. This function allocates the memory, caller is responsible for freeing it. Data is UTF-8 encoded.

References plist_get_node_type(), and PLIST_STRING.

void plist_get_uid_val	(	plist_t	node,
		uint64_t *	val
	)

Get the value of a PLIST_UID node.

This function does nothing if node is not of type PLIST_UID

Parameters

node	the node
val	a pointer to a uint64_t variable.

References plist_get_node_type(), and PLIST_UID.

void plist_get_uint_val	(	plist_t	node,
		uint64_t *	val
	)

Get the value of a PLIST_UINT node.

This function does nothing if node is not of type PLIST_UINT

Parameters

node	the node
val	a pointer to a uint64_t variable.

References plist_get_node_type(), and PLIST_UINT.

plist_t plist_new_array ( void )

Create a new root plist_t type PLIST_ARRAY.

Returns: the created plist

See also: plist_type

References PLIST_ARRAY, and PLIST_KEY.

plist_t plist_new_bool ( uint8_t val )

Create a new plist_t type PLIST_BOOLEAN.

Parameters

val	the boolean value, 0 is false, other values are true.

Returns: the created item

See also: plist_type

References PLIST_BOOLEAN.

plist_t plist_new_data	(	const char *	val,
		uint64_t	length
	)

Create a new plist_t type PLIST_DATA.

Parameters

val	the binary buffer
length	the length of the buffer

Returns: the created item

See also: plist_type

References PLIST_DATA.

plist_t plist_new_date	(	int32_t	sec,
		int32_t	usec
	)

Create a new plist_t type PLIST_DATE.

Parameters

sec	the number of seconds since 01/01/2001
usec	the number of microseconds

Returns: the created item

See also: plist_type

References PLIST_DATE.

plist_t plist_new_dict ( void )

Create a new root plist_t type PLIST_DICT.

Returns: the created plist

See also: plist_type

References PLIST_DICT.

plist_t plist_new_real ( double val )

Create a new plist_t type PLIST_REAL.

Parameters

val	the real value

Returns: the created item

See also: plist_type

References PLIST_REAL.

plist_t plist_new_string ( const char * val )

Create a new plist_t type PLIST_STRING.

Parameters

val	the sting value, encoded in UTF8.

Returns: the created item

See also: plist_type

References PLIST_STRING.

plist_t plist_new_uid ( uint64_t val )

Create a new plist_t type PLIST_UID.

Parameters

val	the unsigned integer value

Returns: the created item

See also: plist_type

References PLIST_UID.

plist_t plist_new_uint ( uint64_t val )

Create a new plist_t type PLIST_UINT.

Parameters

val	the unsigned integer value

Returns: the created item

See also: plist_type

References PLIST_UINT.

void plist_set_bool_val	(	plist_t	node,
		uint8_t	val
	)

Set the value of a node.

Forces type of node to PLIST_BOOLEAN

Parameters

node	the node
val	the boolean value

References PLIST_BOOLEAN.

void plist_set_data_val	(	plist_t	node,
		const char *	val,
		uint64_t	length
	)

Set the value of a node.

Forces type of node to PLIST_DATA

Parameters

node	the node
val	the binary buffer. The buffer is copied when set and will be freed by the node.
length	the length of the buffer

References PLIST_DATA.

void plist_set_date_val	(	plist_t	node,
		int32_t	sec,
		int32_t	usec
	)

Set the value of a node.

Forces type of node to PLIST_DATE

Parameters

node	the node
sec	the number of seconds since 01/01/2001
usec	the number of microseconds

References PLIST_DATE.

void plist_set_key_val	(	plist_t	node,
		const char *	val
	)

Set the value of a node.

Forces type of node to PLIST_KEY

Parameters

node	the node
val	the key value

References PLIST_KEY.

void plist_set_real_val	(	plist_t	node,
		double	val
	)

Set the value of a node.

Forces type of node to PLIST_REAL

Parameters

node	the node
val	the real value

References PLIST_REAL.

void plist_set_string_val	(	plist_t	node,
		const char *	val
	)

Set the value of a node.

Forces type of node to PLIST_STRING

Parameters

node	the node
val	the string value. The string is copied when set and will be freed by the node.

References PLIST_STRING.

void plist_set_uid_val	(	plist_t	node,
		uint64_t	val
	)

Set the value of a node.

Forces type of node to PLIST_UID

Parameters

node	the node
val	the unsigned integer value

References PLIST_UID.

void plist_set_uint_val	(	plist_t	node,
		uint64_t	val
	)

Set the value of a node.

Forces type of node to PLIST_UINT

Parameters

node	the node
val	the unsigned integer value

References PLIST_UINT.

void plist_to_bin	(	plist_t	plist,
		char **	plist_bin,
		uint32_t *	length
	)

Export the plist_t structure to binary format.

Parameters

plist	the root node to export
plist_bin	a pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
length	a pointer to an uint32_t variable. Represents the length of the allocated buffer.

References PLIST_ARRAY, PLIST_BOOLEAN, PLIST_DATA, PLIST_DATE, PLIST_DICT, PLIST_KEY, PLIST_REAL, PLIST_STRING, PLIST_UID, and PLIST_UINT.

void plist_to_xml	(	plist_t	plist,
		char **	plist_xml,
		uint32_t *	length
	)

Export the plist_t structure to XML format.

Parameters

plist	the root node to export
plist_xml	a pointer to a C-string. This function allocates the memory, caller is responsible for freeing it. Data is UTF-8 encoded.
length	a pointer to an uint32_t variable. Represents the length of the allocated buffer.

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation