Top | ![]() |
![]() |
![]() |
![]() |
GQuark | plist_error_quark () |
PlistObject * | plist_object_new () |
PlistObject * | plist_object_copy () |
void | plist_object_free () |
gboolean | plist_object_get_boolean () |
double | plist_object_get_real () |
int | plist_object_get_integer () |
const char * | plist_object_get_string () |
const GTimeVal | plist_object_get_date () |
GList * | plist_object_get_array () |
GHashTable * | plist_object_get_dict () |
unsigned char * | plist_object_get_data () |
void | plist_object_set_boolean () |
void | plist_object_set_real () |
void | plist_object_set_integer () |
void | plist_object_set_string () |
void | plist_object_set_date () |
void | plist_object_set_array () |
void | plist_object_set_dict () |
void | plist_object_set_data () |
PlistObject * | plist_object_lookup () |
PlistObject * | plist_read () |
PlistObject * | plist_read_file () |
PlistObject * | plist_read_from_string () |
gboolean | plist_write () |
gboolean | plist_write_file () |
gchar * | plist_write_to_string () |
Property lists are used in Mac OS X, NeXTSTEP, and GNUstep to store serialized objects. Mac OS X uses an XML format to store property lists in files with the extension “.plist”. This module reads and writes property lists in the XML format. For more information on the format, see the Apple developer documentation. Instead of deserializing the property list into Core Foundation types as in Mac OS X, the property list is represented using a hierarchical structure of PlistObjects, lightweight objects that can contain any type of data.
Each property list object type has a corresponding PlistObject structure. For completeness, the data types are listed here:
XML Element | Core Foundation data type | PlistObject struct |
---|---|---|
true , false
|
CFBoolean |
PlistObjectBoolean |
integer |
CFNumber |
PlistObjectInteger |
real |
CFNumber |
PlistObjectReal |
string |
CFString |
PlistObjectString |
date |
CFDate |
PlistObjectDate |
data |
CFData |
PlistObjectData |
array |
CFArray |
PlistObjectArray |
dict |
CFDictionary |
PlistObjectDict |
PlistObject *
plist_object_new (const PlistObjectType type
);
Allocates a PlistObject, with its value initialized to zero in whatever way
is appropriate for type
.
PlistObject *
plist_object_copy (PlistObject *object
);
Makes a copy of a PlistObject.
Since 1.1
void
plist_object_free (PlistObject *object
);
Deallocates a PlistObject. If object
is a container type, also deallocates
all of the PlistObjects inside it.
gboolean
plist_object_get_boolean (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->boolean.val
.
Since 1.1
double
plist_object_get_real (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->real.val
.
Since 1.1
int
plist_object_get_integer (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->integer.val
.
Since 1.1
const char *
plist_object_get_string (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->string.val
.
Since 1.1
const GTimeVal
plist_object_get_date (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->date.val
.
Since 1.1
GList *
plist_object_get_array (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->array.val
.
Since 1.1
GHashTable *
plist_object_get_dict (PlistObject *object
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->dict.val
.
Since 1.1
unsigned char * plist_object_get_data (PlistObject *object
,size_t *length
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->data.val
and
object->data.length
.
object |
a PlistObject holding binary data |
|
length |
return location for the length of the data. |
[out] |
Since 1.1
void plist_object_set_boolean (PlistObject *object
,gboolean val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->boolean.val
.
Since 1.1
void plist_object_set_real (PlistObject *object
,double val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->real.val
.
Since 1.1
void plist_object_set_integer (PlistObject *object
,int val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->integer.val
.
Since 1.1
void plist_object_set_string (PlistObject *object
,const char *val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->string.val
.
Since 1.1
void plist_object_set_date (PlistObject *object
,GTimeVal val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->date.val
.
Since 1.1
void plist_object_set_array (PlistObject *object
,GList *val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->array.val
.
object |
a PlistObject holding an array |
|
val |
a new array. |
[transfer none][element-type PlistObject] |
Since 1.1
void plist_object_set_dict (PlistObject *object
,GHashTable *val
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->dict.val
.
object |
a PlistObject holding a dictionary |
|
val |
a new dictionary. |
[transfer none][element-type char* PlistObject] |
Since 1.1
void plist_object_set_data (PlistObject *object
,unsigned char *val
,size_t length
);
This function is intended for bindings to other programming languages; in C,
you can simply use object->data.val
and
object->data.length
.
object |
a PlistObject holding binary data |
|
val |
new binary data. |
[transfer none][array length=length] |
length |
length of |
Since 1.1
PlistObject * plist_object_lookup (PlistObject *tree
,...
);
Convenience function for looking up an object that exists at a certain path within the plist. The variable argument list can consist of either strings (dictionary keys, if the object at that point in the path is a dict) or integers (array indices, if the object at that point in the path is an array.)
The variable argument list must be terminated by -1.
For example, given the following plist:
<dict> <key>Array</key> <array> <integer>1</integer> <string>2</string> <real>3.0</real> </array> <key>Dict</key> <dict> <key>Integer</key> <integer>1</integer> <key>Real</key> <real>2.0</real> <key>String</key> <string>3</string> </dict> </plist>]| then the following code: |[PlistObject *obj1 = plist_object_lookup(plist, "Array", 0, -1); PlistObject *obj2 = plist_object_lookup(plist, "Dict", "Integer", -1);]| will place in @obj1 and @obj2 two identical #PlistObjects containing the integer 1, although they will both point to two different spots in the @plist tree.
tree |
The root object of the plist |
|
... |
A path consisting of dictionary keys and array indices, terminated by -1 |
The requested PlistObject, or NULL
if the path
did not exist. The returned object is a pointer to the object within the
original tree
, and is not copied. Therefore, it should not be freed
separately from tree
.
[transfer none]
Since 1.1
PlistObject * plist_read (const gchar *filename
,GError **error
);
Reads a property list in XML format from filename
and returns a PlistObject
representing the property list.
filename |
The path to a file containing a property list in XML format. |
|
error |
Return location for an error, or |
the property list, or NULL
if an error occurred, in which case
error
is set. The property list must be freed with plist_object_free()
after
use.
PlistObject * plist_read_file (GFile *file
,GCancellable *cancellable
,GError **error
);
Reads a property list in XML format from file
and returns a PlistObject
representing the property list. The operation will be cancelled if
cancellable
is triggered from another thread.
file |
A GFile containing a property list in XML format. |
|
cancellable |
An optional GCancellable object, or |
[allow-none] |
error |
Return location for an error, or |
the property list, or NULL
if an error occurred, in which case
error
is set. The property list must be freed with plist_object_free()
after
use.
PlistObject * plist_read_from_string (const gchar *string
,GError **error
);
Reads a property list in XML format from string
and returns a PlistObject
representing the property list.
string |
A string containing a property list in XML format. |
|
error |
Return location for an error, or |
the property list, or NULL
if an error occurred, in which case
error
is set. The property list must be freed with plist_object_free()
after
use.
gboolean plist_write (PlistObject *plist
,const gchar *filename
,GError **error
);
Writes the property list plist
to a file in XML format. If filename
exists,
it will be overwritten.
plist |
A property list object. |
|
filename |
The filename to write to. |
|
error |
Return location for an error, or |
gboolean plist_write_file (PlistObject *plist
,GFile *file
,GCancellable *cancellable
,GError **error
);
Writes the property list plist
to a file in XML format. If file
exists,
it will be overwritten. The operation will be cancelled if cancellable
is
triggered from another thread.
plist |
A property list object. |
|
file |
A GFile to write to. |
|
cancellable |
optional GCancellable object, or |
[allow-none] |
error |
Return location for an error, or |
gchar *
plist_write_to_string (PlistObject *plist
);
Writes the property list plist
to a string in XML format.
a newly-allocated string containing an XML property list. The string
must be freed with g_free()
typedef struct { PlistObjectType type; gboolean val; } PlistObjectBoolean;
A PlistObject which contains a boolean, similar to CFBoolean
.
typedef struct { PlistObjectType type; gdouble val; } PlistObjectReal;
A PlistObject which contains a double-precision floating point number.
CFNumber
is used to represent these in CoreFoundation.
typedef struct { PlistObjectType type; gint val; } PlistObjectInteger;
A PlistObject which contains an integer. CFNumber
is used to
represent these in CoreFoundation.
typedef struct { PlistObjectType type; gchar *val; } PlistObjectString;
A PlistObject which contains a string, similar to CFString
.
typedef struct { PlistObjectType type; GTimeVal val; } PlistObjectDate;
A PlistObject which contains a date in GLib's timeval format, similar to
CFDate
.
typedef struct { PlistObjectType type; GList *val; } PlistObjectArray;
A PlistObject which contains any number of child PlistObjects,
similar to CFArray
.
typedef struct { PlistObjectType type; GHashTable *val; } PlistObjectDict;
A PlistObject which contains a dictionary of child PlistObjects
accessed by string keys, similar to CFDictionary
.
PlistObjectType |
Must be |
|
GHashTable * |
A hash table of PlistObjects |
typedef struct { PlistObjectType type; guchar *val; gsize length; } PlistObjectData;
A PlistObject which contains arbitary binary data, similar to
CFData
.
PlistObjectType |
Must be |
|
guchar * |
The data |
|
The length of the data |
The PlistObject type is a union of all the types that can be stored in a
property list. It is similar to a NSValue
or
CFValue
, or an extremely lightweight GValue
. In
this library, PlistObjects provide a lightweight interface for storing and manipulating property lists so that the library doesn't have to depend on CoreFoundation.
Similar to GdkEvent, the type
field is
always the first member of the structure, so that the type of value can
always be determined.
Here is an example:
if(obj->type == PLIST_OBJECT_ARRAY) g_list_foreach(obj->array.val, some_function, NULL);]|
PlistObjectType |
The type of value stored in this object. |
|
PlistObjectBoolean |
The object as a PlistObjectBoolean. |
|
PlistObjectReal |
The object as a PlistObjectReal. |
|
PlistObjectInteger |
The object as a PlistObjectInteger. |
|
PlistObjectString |
The object as a PlistObjectString. |
|
PlistObjectDate |
The object as a PlistObjectDate. |
|
PlistObjectArray |
The object as a PlistObjectArray. |
|
PlistObjectDict |
The object as a PlistObjectDict. |
|
PlistObjectData |
The object as a PlistObjectData. |
The different error codes which can be thrown in the PLIST_ERROR domain.