libplist  2.0.0
Macros | Typedefs | Enumerations | Functions
Public libplist API

Macros

#define _PLIST_IS_TYPE(__plist, __plist_type)   (__plist && (plist_get_node_type(__plist) == PLIST_##__plist_type))
 
#define PLIST_IS_BOOLEAN(__plist)   _PLIST_IS_TYPE(__plist, BOOLEAN)
 
#define PLIST_IS_UINT(__plist)   _PLIST_IS_TYPE(__plist, UINT)
 
#define PLIST_IS_REAL(__plist)   _PLIST_IS_TYPE(__plist, REAL)
 
#define PLIST_IS_STRING(__plist)   _PLIST_IS_TYPE(__plist, STRING)
 
#define PLIST_IS_ARRAY(__plist)   _PLIST_IS_TYPE(__plist, ARRAY)
 
#define PLIST_IS_DICT(__plist)   _PLIST_IS_TYPE(__plist, DICT)
 
#define PLIST_IS_DATE(__plist)   _PLIST_IS_TYPE(__plist, DATE)
 
#define PLIST_IS_DATA(__plist)   _PLIST_IS_TYPE(__plist, DATA)
 
#define PLIST_IS_KEY(__plist)   _PLIST_IS_TYPE(__plist, KEY)
 
#define PLIST_IS_UID(__plist)   _PLIST_IS_TYPE(__plist, UID)
 

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...
 
void plist_from_memory (const char *plist_data, uint32_t length, plist_t *plist)
 Import the plist_t structure from memory data. More...
 
int plist_is_binary (const char *plist_data, uint32_t length)
 Test if in-memory plist data is binary or XML This method will look at the first bytes of plist_data to determine if plist_data contains a binary or XML plist. 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

◆ plist_type

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_access_path()

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.

◆ plist_access_pathv()

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.

◆ plist_array_append_item()

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. The array is responsible for freeing item when it is no longer needed.

◆ plist_array_get_item()

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

◆ plist_array_get_item_index()

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

◆ plist_array_get_size()

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

◆ plist_array_insert_item()

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. The array is responsible for freeing item when it is no longer needed.
nThe position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range.

◆ plist_array_remove_item()

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.

◆ plist_array_set_item()

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. The array is responsible for freeing item when it is no longer needed.
nthe index of the item to get. Range is [0, array_size[. Assert if n is not in range.

◆ plist_compare_node_value()

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_copy()

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

◆ plist_dict_get_item()

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. The caller should not free the returned node.

◆ plist_dict_get_item_key()

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. The caller is responsible for freeing the returned string.

◆ plist_dict_get_size()

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

◆ plist_dict_insert_item()

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
nodethe node of type PLIST_DICT
itemthe new item to insert
keyThe identifier of the item to insert.

◆ plist_dict_merge()

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

◆ plist_dict_new_iter()

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
nodethe node of type PLIST_DICT
iteriterator of the PLIST_DICT node

◆ plist_dict_next_item()

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. The caller is responsible for freeing the the returned string.
vala location to store the value, or NULL. The caller should not free the returned value.

◆ plist_dict_remove_item()

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.

◆ plist_dict_set_item()

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.

◆ plist_free()

void plist_free ( plist_t  plist)

Destruct a plist_t node and all its children recursively.

Parameters
plistthe plist to free

◆ 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_bina pointer to the xml buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.

◆ plist_from_memory()

void plist_from_memory ( const char *  plist_data,
uint32_t  length,
plist_t plist 
)

Import the plist_t structure from memory data.

This method will look at the first bytes of plist_data to determine if plist_data contains a binary or XML plist.

Parameters
plist_dataa pointer to the memory buffer containing plist data.
lengthlength of the buffer to read.
plista pointer to the imported plist.

◆ plist_from_xml()

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_get_bool_val()

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.

◆ plist_get_data_val()

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

◆ plist_get_date_val()

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

◆ plist_get_key_val()

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.

◆ plist_get_node_type()

plist_type plist_get_node_type ( plist_t  node)

Get the plist_type of a node.

Parameters
nodethe node
Returns
the type of the node

◆ plist_get_parent()

plist_t plist_get_parent ( plist_t  node)

Get the parent of a node.

Parameters
nodethe parent (NULL if node is root)

◆ plist_get_real_val()

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.

◆ plist_get_string_val()

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.

◆ plist_get_uid_val()

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.

◆ plist_get_uint_val()

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.

◆ plist_is_binary()

int plist_is_binary ( const char *  plist_data,
uint32_t  length 
)

Test if in-memory plist data is binary or XML This method will look at the first bytes of plist_data to determine if plist_data contains a binary or XML plist.

This method is not validating the whole memory buffer to check if the content is truly a plist, it's only using some heuristic on the first few bytes of plist_data.

Parameters
plist_dataa pointer to the memory buffer containing plist data.
lengthlength of the buffer to read.
Returns
1 if the buffer is a binary plist, 0 otherwise.

◆ plist_new_array()

plist_t plist_new_array ( void  )

Create a new root plist_t type PLIST_ARRAY.

Returns
the created plist
See also
plist_type

◆ plist_new_bool()

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

◆ plist_new_data()

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

◆ plist_new_date()

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

◆ plist_new_dict()

plist_t plist_new_dict ( void  )

Create a new root plist_t type PLIST_DICT.

Returns
the created plist
See also
plist_type

◆ plist_new_real()

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

◆ plist_new_string()

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

◆ plist_new_uid()

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

◆ plist_new_uint()

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

◆ plist_set_bool_val()

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

◆ plist_set_data_val()

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. The buffer is copied when set and will be freed by the node.
lengththe length of the buffer

◆ plist_set_date_val()

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

◆ plist_set_key_val()

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

◆ plist_set_real_val()

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

◆ plist_set_string_val()

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. The string is copied when set and will be freed by the node.

◆ plist_set_uid_val()

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

◆ plist_set_uint_val()

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

◆ plist_to_bin()

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.

◆ plist_to_xml()

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.