libplist  1.11
Typedefs | Enumerations | Functions | Variables
Public libplist API

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_API plist_t plist_new_dict (void)
 Create a new root plist_t type PLIST_DICT. More...
 
PLIST_API plist_t plist_new_array (void)
 Create a new root plist_t type PLIST_ARRAY. More...
 
PLIST_API plist_t plist_new_string (const char *val)
 Create a new plist_t type PLIST_STRING. More...
 
PLIST_API plist_t plist_new_bool (uint8_t val)
 Create a new plist_t type PLIST_BOOLEAN. More...
 
PLIST_API plist_t plist_new_uint (uint64_t val)
 Create a new plist_t type PLIST_UINT. More...
 
PLIST_API plist_t plist_new_real (double val)
 Create a new plist_t type PLIST_REAL. More...
 
PLIST_API plist_t plist_new_data (const char *val, uint64_t length)
 Create a new plist_t type PLIST_DATA. More...
 
PLIST_API plist_t plist_new_date (int32_t sec, int32_t usec)
 Create a new plist_t type PLIST_DATE. More...
 
PLIST_API plist_t plist_new_uid (uint64_t val)
 Create a new plist_t type PLIST_UID. More...
 
PLIST_API void plist_free (plist_t plist)
 Destruct a plist_t node and all its children recursively. More...
 
PLIST_API plist_t plist_copy (plist_t node)
 Return a copy of passed node and it's children. More...
 
PLIST_API uint32_t plist_array_get_size (plist_t node)
 Get size of a PLIST_ARRAY node. More...
 
PLIST_API plist_t plist_array_get_item (plist_t node, uint32_t n)
 Get the nth item in a PLIST_ARRAY node. More...
 
PLIST_API uint32_t plist_array_get_item_index (plist_t node)
 Get the index of an item. More...
 
PLIST_API void plist_array_set_item (plist_t node, plist_t item, uint32_t n)
 Set the nth item in a PLIST_ARRAY node. More...
 
PLIST_API void plist_array_append_item (plist_t node, plist_t item)
 Append a new item at the end of a PLIST_ARRAY node. More...
 
PLIST_API 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...
 
PLIST_API void plist_array_remove_item (plist_t node, uint32_t n)
 Remove an existing position in a PLIST_ARRAY node. More...
 
PLIST_API uint32_t plist_dict_get_size (plist_t node)
 Get size of a PLIST_DICT node. More...
 
PLIST_API void plist_dict_new_iter (plist_t node, plist_dict_iter *iter)
 Create iterator of a PLIST_DICT node. More...
 
PLIST_API 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...
 
PLIST_API void plist_dict_get_item_key (plist_t node, char **key)
 Get key associated to an item. More...
 
PLIST_API plist_t plist_dict_get_item (plist_t node, const char *key)
 Get the nth item in a PLIST_DICT node. More...
 
PLIST_API 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...
 
 DEPRECATED ("use plist_dict_set_item instead") PLIST_API void plist_dict_insert_item(plist_t node
 Insert a new item into a PLIST_DICT node. More...
 
PLIST_API void plist_dict_remove_item (plist_t node, const char *key)
 Remove an existing position in a PLIST_DICT node. More...
 
PLIST_API void plist_dict_merge (plist_t *target, plist_t source)
 Merge a dictionary into another. More...
 
PLIST_API plist_t plist_get_parent (plist_t node)
 Get the parent of a node. More...
 
PLIST_API plist_type plist_get_node_type (plist_t node)
 Get the plist_type of a node. More...
 
PLIST_API void plist_get_key_val (plist_t node, char **val)
 Get the value of a PLIST_KEY node. More...
 
PLIST_API void plist_get_string_val (plist_t node, char **val)
 Get the value of a PLIST_STRING node. More...
 
PLIST_API void plist_get_bool_val (plist_t node, uint8_t *val)
 Get the value of a PLIST_BOOLEAN node. More...
 
PLIST_API void plist_get_uint_val (plist_t node, uint64_t *val)
 Get the value of a PLIST_UINT node. More...
 
PLIST_API void plist_get_real_val (plist_t node, double *val)
 Get the value of a PLIST_REAL node. More...
 
PLIST_API void plist_get_data_val (plist_t node, char **val, uint64_t *length)
 Get the value of a PLIST_DATA node. More...
 
PLIST_API void plist_get_date_val (plist_t node, int32_t *sec, int32_t *usec)
 Get the value of a PLIST_DATE node. More...
 
PLIST_API void plist_get_uid_val (plist_t node, uint64_t *val)
 Get the value of a PLIST_UID node. More...
 
PLIST_API void plist_set_type (plist_t node, plist_type type)
 Forces type of node. More...
 
PLIST_API void plist_set_key_val (plist_t node, const char *val)
 Set the value of a node. More...
 
PLIST_API void plist_set_string_val (plist_t node, const char *val)
 Set the value of a node. More...
 
PLIST_API void plist_set_bool_val (plist_t node, uint8_t val)
 Set the value of a node. More...
 
PLIST_API void plist_set_uint_val (plist_t node, uint64_t val)
 Set the value of a node. More...
 
PLIST_API void plist_set_real_val (plist_t node, double val)
 Set the value of a node. More...
 
PLIST_API void plist_set_data_val (plist_t node, const char *val, uint64_t length)
 Set the value of a node. More...
 
PLIST_API void plist_set_date_val (plist_t node, int32_t sec, int32_t usec)
 Set the value of a node. More...
 
PLIST_API void plist_set_uid_val (plist_t node, uint64_t val)
 Set the value of a node. More...
 
PLIST_API void plist_to_xml (plist_t plist, char **plist_xml, uint32_t *length)
 Export the plist_t structure to XML format. More...
 
PLIST_API void plist_to_bin (plist_t plist, char **plist_bin, uint32_t *length)
 Export the plist_t structure to binary format. More...
 
PLIST_API void plist_from_xml (const char *plist_xml, uint32_t length, plist_t *plist)
 Import the plist_t structure from XML format. More...
 
PLIST_API void plist_from_bin (const char *plist_bin, uint32_t length, plist_t *plist)
 Import the plist_t structure from binary format. More...
 
PLIST_API plist_t plist_access_path (plist_t plist, uint32_t length,...)
 Get a node from its path. More...
 
PLIST_API plist_t plist_access_pathv (plist_t plist, uint32_t length, va_list v)
 Variadic version of plist_access_path. More...
 
PLIST_API char plist_compare_node_value (plist_t node_l, plist_t node_r)
 Compare two node values. More...
 

Variables

const char * key
 
const char plist_t item
 

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

DEPRECATED ( "use plist_dict_set_item instead"  )

Insert a new item into a PLIST_DICT node.

Deprecated:
Deprecated. Use plist_dict_set_item instead.
Parameters
nodethe node of type PLIST_DICT
itemthe new item to insert
keyThe identifier of the item to insert.
PLIST_API 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
plistthe node to access result from.
lengthlength of the path to access
Returns
the value to access.

References plist_access_pathv().

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

Variadic version of plist_access_path.

Parameters
plistthe node to access result from.
lengthlength of the path to access
vlist 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().

PLIST_API void plist_array_append_item ( plist_t  node,
plist_t  item 
)

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

Parameters
nodethe node of type PLIST_ARRAY
itemthe new item

References PLIST_ARRAY, and plist_get_node_type().

PLIST_API plist_t plist_array_get_item ( plist_t  node,
uint32_t  n 
)

Get the nth item in a PLIST_ARRAY node.

Parameters
nodethe node of type PLIST_ARRAY
nthe 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().

PLIST_API 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
nodethe node
Returns
the node index

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

PLIST_API uint32_t plist_array_get_size ( plist_t  node)

Get size of a PLIST_ARRAY node.

Parameters
nodethe node of type PLIST_ARRAY
Returns
size of the PLIST_ARRAY node

References PLIST_ARRAY, and plist_get_node_type().

PLIST_API 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
nodethe node of type PLIST_ARRAY
itemthe new item to insert
nThe 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().

PLIST_API 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
nodethe node of type PLIST_ARRAY
nThe 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().

PLIST_API 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
nodethe node of type PLIST_ARRAY
itemthe new item at index n
nthe 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().

PLIST_API char plist_compare_node_value ( plist_t  node_l,
plist_t  node_r 
)

Compare two node values.

Parameters
node_lleft node to compare
node_rrigth node to compare
Returns
TRUE is type and value match, FALSE otherwise.
PLIST_API plist_t plist_copy ( plist_t  node)

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

Parameters
nodethe plist to copy
Returns
copied plist

Referenced by plist_dict_merge().

PLIST_API plist_t plist_dict_get_item ( plist_t  node,
const char *  key 
)

Get the nth item in a PLIST_DICT node.

Parameters
nodethe node of type PLIST_DICT
keythe identifier of the item to get.
Returns
the item or NULL if node is not of type PLIST_DICT

References PLIST_DICT, plist_get_node_type(), and PLIST_KEY.

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

PLIST_API 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
nodethe node
keya location to store the key.

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

PLIST_API uint32_t plist_dict_get_size ( plist_t  node)

Get size of a PLIST_DICT node.

Parameters
nodethe node of type PLIST_DICT
Returns
size of the PLIST_DICT node

References PLIST_DICT, and plist_get_node_type().

PLIST_API 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
targetpointer to an existing node of type PLIST_DICT
sourcenode of type PLIST_DICT that should be merged into target

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

PLIST_API void plist_dict_new_iter ( plist_t  node,
plist_dict_iter iter 
)

Create iterator of a PLIST_DICT node.

The allocated iterator shoult be freed with tandard free function

Parameters
nodethe node of type PLIST_DICT
iteriterator of the PLIST_DICT node

Referenced by plist_dict_merge().

PLIST_API 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
nodethe node of type PLIST_DICT
iteriterator of the dictionary
keya location to store the key, or NULL.
vala location to store the value, or NULL.

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

Referenced by plist_dict_merge().

PLIST_API 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
nodethe node of type PLIST_DICT
keyThe 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().

Referenced by plist_dict_merge().

PLIST_API 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
nodethe node of type PLIST_DICT
itemthe new item associated to key
keythe identifier of the item to set.

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

Referenced by plist_dict_merge().

PLIST_API void plist_free ( plist_t  plist)

Destruct a plist_t node and all its children recursively.

Parameters
plistthe plist to free

Referenced by plist_array_remove_item(), and plist_dict_remove_item().

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

Import the plist_t structure from binary format.

Parameters
plist_bina pointer to the xml buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.

References PLIST_ARRAY, PLIST_DICT, and PLIST_KEY.

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

Import the plist_t structure from XML format.

Parameters
plist_xmla pointer to the xml buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.
PLIST_API 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
nodethe node
vala pointer to a uint8_t variable.

References PLIST_BOOLEAN, and plist_get_node_type().

PLIST_API 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
nodethe node
vala pointer to an unallocated char buffer. This function allocates the memory, caller is responsible for freeing it.
lengththe length of the buffer

References PLIST_DATA, and plist_get_node_type().

PLIST_API 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
nodethe node
seca pointer to an int32_t variable. Represents the number of seconds since 01/01/2001.
useca pointer to an int32_t variable. Represents the number of microseconds

References PLIST_DATE, and plist_get_node_type().

PLIST_API 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
nodethe node
vala 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_API plist_type plist_get_node_type ( plist_t  node)
PLIST_API plist_t plist_get_parent ( plist_t  node)

Get the parent of a node.

Parameters
nodethe parent (NULL if node is root)

Referenced by plist_array_get_item_index(), and plist_dict_get_item_key().

PLIST_API 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
nodethe node
vala pointer to a double variable.

References plist_get_node_type(), and PLIST_REAL.

PLIST_API 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
nodethe node
vala 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.

PLIST_API 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
nodethe node
vala pointer to a uint64_t variable.

References plist_get_node_type(), and PLIST_UID.

PLIST_API 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
nodethe node
vala pointer to a uint64_t variable.

References plist_get_node_type(), and PLIST_UINT.

PLIST_API 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.

PLIST_API plist_t plist_new_bool ( uint8_t  val)

Create a new plist_t type PLIST_BOOLEAN.

Parameters
valthe boolean value, 0 is false, other values are true.
Returns
the created item
See also
plist_type

References PLIST_BOOLEAN.

PLIST_API plist_t plist_new_data ( const char *  val,
uint64_t  length 
)

Create a new plist_t type PLIST_DATA.

Parameters
valthe binary buffer
lengththe length of the buffer
Returns
the created item
See also
plist_type

References PLIST_DATA.

PLIST_API plist_t plist_new_date ( int32_t  sec,
int32_t  usec 
)

Create a new plist_t type PLIST_DATE.

Parameters
secthe number of seconds since 01/01/2001
usecthe number of microseconds
Returns
the created item
See also
plist_type

References PLIST_DATE.

PLIST_API 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_API plist_t plist_new_real ( double  val)

Create a new plist_t type PLIST_REAL.

Parameters
valthe real value
Returns
the created item
See also
plist_type

References PLIST_REAL.

PLIST_API plist_t plist_new_string ( const char *  val)

Create a new plist_t type PLIST_STRING.

Parameters
valthe sting value, encoded in UTF8.
Returns
the created item
See also
plist_type

References PLIST_STRING.

PLIST_API plist_t plist_new_uid ( uint64_t  val)

Create a new plist_t type PLIST_UID.

Parameters
valthe unsigned integer value
Returns
the created item
See also
plist_type

References PLIST_UID.

PLIST_API plist_t plist_new_uint ( uint64_t  val)

Create a new plist_t type PLIST_UINT.

Parameters
valthe unsigned integer value
Returns
the created item
See also
plist_type

References PLIST_UINT.

PLIST_API 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
nodethe node
valthe boolean value

References PLIST_BOOLEAN.

PLIST_API 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
nodethe node
valthe binary buffer
lengththe length of the buffer

References PLIST_DATA.

PLIST_API 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
nodethe node
secthe number of seconds since 01/01/2001
usecthe number of microseconds

References PLIST_DATE.

PLIST_API 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
nodethe node
valthe key value

References PLIST_KEY.

PLIST_API void plist_set_real_val ( plist_t  node,
double  val 
)

Set the value of a node.

Forces type of node to PLIST_REAL

Parameters
nodethe node
valthe real value

References PLIST_REAL.

PLIST_API 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
nodethe node
valthe string value

References PLIST_STRING.

PLIST_API void plist_set_type ( plist_t  node,
plist_type  type 
)

Forces type of node.

Changing type of structured nodes is only allowed if node is empty. Reset value of node;

Parameters
nodethe node
typethe key value

References PLIST_BOOLEAN, PLIST_DATE, PLIST_REAL, PLIST_UID, and PLIST_UINT.

PLIST_API 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
nodethe node
valthe unsigned integer value

References PLIST_UID.

PLIST_API 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
nodethe node
valthe unsigned integer value

References PLIST_UINT.

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

Export the plist_t structure to binary format.

Parameters
plistthe root node to export
plist_bina pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
lengtha 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.

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

Export the plist_t structure to XML format.

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