libplist  2.2.0
Macros | Typedefs | Enumerations | Functions
plist.h File Reference

Main include of libplist. More...

#include <stdint.h>
#include <sys/types.h>
#include <stdarg.h>

Macros

#define PLIST_WARN_DEPRECATED(x)
 
#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.
 
typedef void * plist_array_iter
 The plist array 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...
 
void plist_array_item_remove (plist_t node)
 Remove a node that is a child node of a PLIST_ARRAY node. More...
 
void plist_array_new_iter (plist_t node, plist_array_iter *iter)
 Create an iterator of a PLIST_ARRAY node. More...
 
void plist_array_next_item (plist_t node, plist_array_iter iter, plist_t *item)
 Increment iterator of 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 key 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...
 
plist_t plist_dict_item_get_key (plist_t node)
 Get key node associated to an item. 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...
 
const char * plist_get_string_ptr (plist_t node, uint64_t *length)
 Get a pointer to the buffer 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...
 
const char * plist_get_data_ptr (plist_t node, uint64_t *length)
 Get a pointer to the data buffer 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_xml_free (char *plist_xml)
 Frees the memory allocated by plist_to_xml(). 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_to_bin_free (char *plist_bin)
 Frees the memory allocated by plist_to_bin(). 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...
 
int plist_bool_val_is_true (plist_t boolnode)
 Helper function to check the value of a PLIST_BOOL node. More...
 
int plist_uint_val_compare (plist_t uintnode, uint64_t cmpval)
 Helper function to compare the value of a PLIST_UINT node against a given value. More...
 
int plist_uid_val_compare (plist_t uidnode, uint64_t cmpval)
 Helper function to compare the value of a PLIST_UID node against a given value. More...
 
int plist_real_val_compare (plist_t realnode, double cmpval)
 Helper function to compare the value of a PLIST_REAL node against a given value. More...
 
int plist_date_val_compare (plist_t datenode, int32_t cmpsec, int32_t cmpusec)
 Helper function to compare the value of a PLIST_DATE node against a given set of seconds and fraction of a second since epoch. More...
 
int plist_string_val_compare (plist_t strnode, const char *cmpval)
 Helper function to compare the value of a PLIST_STRING node against a given value. More...
 
int plist_string_val_compare_with_size (plist_t strnode, const char *cmpval, size_t n)
 Helper function to compare the value of a PLIST_STRING node against a given value, while not comparing more than n characters. More...
 
int plist_string_val_contains (plist_t strnode, const char *substr)
 Helper function to match a given substring in the value of a PLIST_STRING node. More...
 
int plist_key_val_compare (plist_t keynode, const char *cmpval)
 Helper function to compare the value of a PLIST_KEY node against a given value. More...
 
int plist_key_val_compare_with_size (plist_t keynode, const char *cmpval, size_t n)
 Helper function to compare the value of a PLIST_KEY node against a given value, while not comparing more than n characters. More...
 
int plist_key_val_contains (plist_t keynode, const char *substr)
 Helper function to match a given substring in the value of a PLIST_KEY node. More...
 
int plist_data_val_compare (plist_t datanode, const uint8_t *cmpval, size_t n)
 Helper function to compare the data of a PLIST_DATA node against a given blob and size. More...
 
int plist_data_val_compare_with_size (plist_t datanode, const uint8_t *cmpval, size_t n)
 Helper function to compare the data of a PLIST_DATA node against a given blob and size, while no more than n bytes are compared. More...
 
int plist_data_val_contains (plist_t datanode, const uint8_t *cmpval, size_t n)
 Helper function to match a given data blob within the value of a PLIST_DATA node. More...
 

Detailed Description

Main include of libplist.

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 or UINT_MAX if node index can't be determined

◆ 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_item_remove()

void plist_array_item_remove ( plist_t  node)

Remove a node that is a child node of a PLIST_ARRAY node.

node will be freed using plist_free.

Parameters
nodeThe node to be removed from its PLIST_ARRAY parent.

◆ plist_array_new_iter()

void plist_array_new_iter ( plist_t  node,
plist_array_iter iter 
)

Create an iterator of a PLIST_ARRAY node.

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

Parameters
nodeThe node of type PLIST_ARRAY
iterLocation to store the iterator for the array.

◆ plist_array_next_item()

void plist_array_next_item ( plist_t  node,
plist_array_iter  iter,
plist_t item 
)

Increment iterator of a PLIST_ARRAY node.

Parameters
nodeThe node of type PLIST_ARRAY.
iterIterator of the array
itemLocation to store the item. The caller must not free the returned item. Will be set to NULL when no more items are left to iterate.

◆ 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_bool_val_is_true()

int plist_bool_val_is_true ( plist_t  boolnode)

Helper function to check the value of a PLIST_BOOL node.

Parameters
boolnodenode of type PLIST_BOOL
Returns
1 if the boolean node has a value of TRUE, 0 if FALSE, or -1 if the node is not of type PLIST_BOOL

◆ 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_data_val_compare()

int plist_data_val_compare ( plist_t  datanode,
const uint8_t *  cmpval,
size_t  n 
)

Helper function to compare the data of a PLIST_DATA node against a given blob and size.

This function basically behaves like memcmp after making sure the size of the node's data value is equal to the size of cmpval (n), making this a "full match" comparison.

Parameters
datanodenode of type PLIST_DATA
cmpvaldata blob to compare against
nsize of data blob passed in cmpval
Returns
0 if the node's data blob and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_data_val_compare_with_size()

int plist_data_val_compare_with_size ( plist_t  datanode,
const uint8_t *  cmpval,
size_t  n 
)

Helper function to compare the data of a PLIST_DATA node against a given blob and size, while no more than n bytes are compared.

This function basically behaves like memcmp after making sure the size of the node's data value is at least n, making this a "starts with" comparison.

Parameters
datanodenode of type PLIST_DATA
cmpvaldata blob to compare against
nsize of data blob passed in cmpval
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_data_val_contains()

int plist_data_val_contains ( plist_t  datanode,
const uint8_t *  cmpval,
size_t  n 
)

Helper function to match a given data blob within the value of a PLIST_DATA node.

Parameters
datanodenode of type PLIST_KEY
cmpvaldata blob to match
nsize of data blob passed in cmpval
Returns
1 if the node's value contains the given data blob or 0 if not.

◆ plist_date_val_compare()

int plist_date_val_compare ( plist_t  datenode,
int32_t  cmpsec,
int32_t  cmpusec 
)

Helper function to compare the value of a PLIST_DATE node against a given set of seconds and fraction of a second since epoch.

Parameters
datenodenode of type PLIST_DATE
cmpsecnumber of seconds since epoch to compare against
cmpusecfraction of a second in microseconds to compare against
Returns
0 if the node's date is equal to the supplied values, 1 if the node's date is greater than the supplied values, or -1 if the node's date is less than the supplied values.

◆ 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 key to an item.

Item must be member of a dictionary.

Parameters
nodethe item
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_item_get_key()

plist_t plist_dict_item_get_key ( plist_t  node)

Get key node associated to an item.

Item must be member of a dictionary.

Parameters
nodethe item
Returns
the key node of the given item, or NULL.

◆ 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.
iterLocation to store the iterator for the dictionary.

◆ 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
keyLocation to store the key, or NULL. The caller is responsible for freeing the the returned string.
valLocation to store the value, or NULL. The caller must not free the returned value. Will be set to NULL when no more key/value pairs are left to iterate.

◆ 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_ptr()

const char* plist_get_data_ptr ( plist_t  node,
uint64_t *  length 
)

Get a pointer to the data buffer of a PLIST_DATA node.

Note
DO NOT MODIFY the buffer. Mind that the buffer is only available until the plist node gets freed. Make a copy if needed.
Parameters
nodeThe node
lengthPointer to a uint64_t that will be set to the length of the buffer
Returns
Pointer to the buffer

◆ 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_ptr()

const char* plist_get_string_ptr ( plist_t  node,
uint64_t *  length 
)

Get a pointer to the buffer of a PLIST_STRING node.

Note
DO NOT MODIFY the buffer. Mind that the buffer is only available until the plist node gets freed. Make a copy if needed.
Parameters
nodeThe node
lengthIf non-NULL, will be set to the length of the string
Returns
Pointer to the NULL-terminated buffer.

◆ 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_key_val_compare()

int plist_key_val_compare ( plist_t  keynode,
const char *  cmpval 
)

Helper function to compare the value of a PLIST_KEY node against a given value.

This function basically behaves like strcmp.

Parameters
keynodenode of type PLIST_KEY
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_key_val_compare_with_size()

int plist_key_val_compare_with_size ( plist_t  keynode,
const char *  cmpval,
size_t  n 
)

Helper function to compare the value of a PLIST_KEY node against a given value, while not comparing more than n characters.

This function basically behaves like strncmp.

Parameters
keynodenode of type PLIST_KEY
cmpvalvalue to compare against
nmaximum number of characters to compare
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_key_val_contains()

int plist_key_val_contains ( plist_t  keynode,
const char *  substr 
)

Helper function to match a given substring in the value of a PLIST_KEY node.

Parameters
keynodenode of type PLIST_KEY
substrvalue to match
Returns
1 if the node's value contains the given substring, or 0 if not.

◆ 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_real_val_compare()

int plist_real_val_compare ( plist_t  realnode,
double  cmpval 
)

Helper function to compare the value of a PLIST_REAL node against a given value.

Note
WARNING: Comparing floating point values can give inaccurate results because of the nature of floating point values on computer systems. While this function is designed to be as accurate as possible, please don't rely on it too much.
Parameters
realnodenode of type PLIST_REAL
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are (almost) equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.

◆ 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_string_val_compare()

int plist_string_val_compare ( plist_t  strnode,
const char *  cmpval 
)

Helper function to compare the value of a PLIST_STRING node against a given value.

This function basically behaves like strcmp.

Parameters
strnodenode of type PLIST_STRING
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_string_val_compare_with_size()

int plist_string_val_compare_with_size ( plist_t  strnode,
const char *  cmpval,
size_t  n 
)

Helper function to compare the value of a PLIST_STRING node against a given value, while not comparing more than n characters.

This function basically behaves like strncmp.

Parameters
strnodenode of type PLIST_STRING
cmpvalvalue to compare against
nmaximum number of characters to compare
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_string_val_contains()

int plist_string_val_contains ( plist_t  strnode,
const char *  substr 
)

Helper function to match a given substring in the value of a PLIST_STRING node.

Parameters
strnodenode of type PLIST_STRING
substrvalue to match
Returns
1 if the node's value contains the given substring, or 0 if not.

◆ 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_bin_free()

void plist_to_bin_free ( char *  plist_bin)

Frees the memory allocated by plist_to_bin().

Parameters
plist_binThe buffer allocated by plist_to_bin().

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

◆ plist_to_xml_free()

void plist_to_xml_free ( char *  plist_xml)

Frees the memory allocated by plist_to_xml().

Parameters
plist_xmlThe buffer allocated by plist_to_xml().

◆ plist_uid_val_compare()

int plist_uid_val_compare ( plist_t  uidnode,
uint64_t  cmpval 
)

Helper function to compare the value of a PLIST_UID node against a given value.

Parameters
uidnodenode of type PLIST_UID
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.

◆ plist_uint_val_compare()

int plist_uint_val_compare ( plist_t  uintnode,
uint64_t  cmpval 
)

Helper function to compare the value of a PLIST_UINT node against a given value.

Parameters
uintnodenode of type PLIST_UINT
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.