GDataParsable: GData Reference Manual

## GDataParsable GDataParsable — GData parsable object |

## Stability Level

Stable, unless otherwise indicated

## Functions

const gchar * | gdata_parsable_get_content_type ()
GDataParsable * | gdata_parsable_new_from_xml ()
gchar * | gdata_parsable_get_xml ()
GDataParsable * | gdata_parsable_new_from_json ()
gchar * | gdata_parsable_get_json ()

## Properties

gboolean | constructed-from-xml | Read / Write / Construct Only

## Types and Values

| GDataParsable
| GDataParsableClass

## Object Hierarchy

        GObject
        ╰── GDataParsable
            ├── GDataEntry
            ├── GDataAPPCategories
            ├── GDataAuthor
            ├── GDataFeed
            ├── GDataCategory
            ├── GDataDocumentsMetadata
            ├── GDataGContactCalendar
            ├── GDataGContactEvent
            ├── GDataGContactExternalID
            ├── GDataGContactJot
            ├── GDataGContactLanguage
            ├── GDataGContactRelation
            ├── GDataGContactWebsite
            ├── GDataGDEmailAddress
            ├── GDataGDIMAddress
            ├── GDataGDName
            ├── GDataGDOrganization
            ├── GDataGDPhoneNumber
            ├── GDataGDPostalAddress
            ├── GDataGDReminder
            ├── GDataGDWhen
            ├── GDataGDWhere
            ├── GDataGDWho
            ├── GDataGenerator
            ├── GDataLink
            ├── GDataMediaCategory
            ├── GDataMediaContent
            ├── GDataMediaCredit
            ├── GDataMediaThumbnail
            ╰── GDataYouTubeState

## Includes

    #include <gdata/gdata-parsable.h>

## Description

GDataParsable is an abstract class allowing easy implementation of an extensible parser. It is primarily extended by GDataFeed and GDataEntry, both of which require XML parsing which can be extended by subclassing.

It allows methods to be defined for handling the root XML node, each of its child nodes, and a method to be called after parsing is complete.

## Functions

### gdata_parsable_get_content_type ()

    const gchar *
    gdata_parsable_get_content_type (GDataParsable *self);

Returns the content type upon which the GDataParsable is built. For example, `application/atom+xml` or `application/json`.

#### Parameters

self | a GDataParsable |

#### Returns

the parsable's content type

Since: 0.17.7

### gdata_parsable_new_from_xml ()

    GDataParsable *
    gdata_parsable_new_from_xml (GType parsable_type,
                                 const gchar *xml,
                                 gint length,
                                 GError **error);

Creates a new GDataParsable subclass (of the given `parsable_type` ) from the given `xml` .

An object of the given `parsable_type` is created, and its `pre_parse_xml`, `parse_xml` and `post_parse_xml` class functions called on the XML tree obtained from `xml` . `pre_parse_xml` and `post_parse_xml` are called once each on the root node of the tree, while `parse_xml` is called for each of the child nodes of the root node.

If `length` is -1, `xml` will be assumed to be null-terminated.

If an error occurs during parsing, a suitable error from GDataParserError will be returned.

#### Parameters

parsable_type | the type of the class represented by the XML |
xml | the XML for just the parsable object, with full namespace declarations |
length | the length of `xml` , or -1 |
error | a GError, or `NULL` |

#### Returns

a new GDataParsable, or `NULL`; unref with `g_object_unref()`

Since: 0.4.0

### gdata_parsable_get_xml ()

    gchar *
    gdata_parsable_get_xml (GDataParsable *self);

Builds an XML representation of the GDataParsable in its current state, such that it could be inserted on the server. The XML is guaranteed to have all its namespaces declared properly in a self-contained fashion, and is valid for stand-alone use.

#### Parameters

self | a GDataParsable |

#### Returns

the object's XML; free with `g_free()`

Since: 0.4.0

### gdata_parsable_new_from_json ()

    GDataParsable *
    gdata_parsable_new_from_json (GType parsable_type,
                                  const gchar *json,
                                  gint length,
                                  GError **error);

Creates a new GDataParsable subclass (of the given `parsable_type` ) from the given `json` .

An object of the given `parsable_type` is created, and its `parse_json` and `post_parse_json` class functions called on the JSON node obtained from `json` . `post_parse_json` is called once on the root node, while `parse_json` is called for each of the node's members.

If `length` is -1, `json` will be assumed to be nul-terminated.

If an error occurs during parsing, a suitable error from GDataParserError will be returned.

#### Parameters

parsable_type | the type of the class represented by the JSON |
json | the JSON for just the parsable object |
length | the length of `json` , or -1 |
error | a GError, or `NULL` |

#### Returns

a new GDataParsable, or `NULL`; unref with `g_object_unref()`

Since: 0.15.0

### gdata_parsable_get_json ()

    gchar *
    gdata_parsable_get_json (GDataParsable *self);

Builds a JSON representation of the GDataParsable in its current state, such that it could be inserted on the server. The JSON is valid for stand-alone use.

#### Parameters

self | a GDataParsable |

#### Returns

the object's JSON; free with `g_free()`

Since: 0.15.0

## Types and Values

### GDataParsable

    typedef struct _GDataParsable GDataParsable;

All the fields in the GDataParsable structure are private and should never be accessed directly.

Since: 0.3.0

### GDataParsableClass

    typedef struct {
    	GObjectClass parent;

    	gboolean (*pre_parse_xml) (GDataParsable *parsable, xmlDoc *doc, xmlNode *root_node, gpointer user_data, GError **error);
    	gboolean (*parse_xml) (GDataParsable *parsable, xmlDoc *doc, xmlNode *node, gpointer user_data, GError **error);
    	gboolean (*post_parse_xml) (GDataParsable *parsable, gpointer user_data, GError **error);

    	void (*pre_get_xml) (GDataParsable *parsable, GString *xml_string);
    	void (*get_xml) (GDataParsable *parsable, GString *xml_string);
    	void (*get_namespaces) (GDataParsable *parsable, GHashTable *namespaces);

    	gboolean (*parse_json) (GDataParsable *parsable, JsonReader *reader, gpointer user_data, GError **error);
    	gboolean (*post_parse_json) (GDataParsable *parsable, gpointer user_data, GError **error);
    	void (*get_json) (GDataParsable *parsable, JsonBuilder *builder);

    	const gchar *(*get_content_type) (void);

    	const gchar *element_name;
    	const gchar *element_namespace;
    } GDataParsableClass;

The class structure for the GDataParsable class. Note that JSON and XML functions are mutually exclusive: a given implementation of GDataParsable is represented as exactly one of JSON and XML.

#### Members

GObjectClass `parent`; | the parent class |
`pre_parse_xml` () | a function called before parsing of an XML tree is started, which allows properties from the root node to be extracted and used in `parsable` |
`parse_xml` () | a function to parse an XML representation of the GDataParsable to set the properties of the `parsable` |
`post_parse_xml` () | a function called after parsing an XML tree, to allow the `parsable` to validate the parsed properties |
`pre_get_xml` () | a function called before building the XML representation of the children of the GDataParsable, which allows attributes of the root XML node to be added to `xml_string` |
`get_xml` () | a function to build an XML representation of the GDataParsable in its current state, appending it to the provided GString |
`get_namespaces` () | a function to return a string containing the namespace declarations used by the `parsable` when represented in XML form |
`parse_json` () | a function to parse a JSON representation of the GDataParsable to set the properties of the `parsable` |
`post_parse_json` () | a function called after parsing a JSON object, to allow the `parsable` to validate the parsed properties |
`get_json` () | a function to build a JSON representation of the GDataParsable in its current state, appending it to the provided JsonBuilder |
`get_content_type` () | a function which returns content type upon which is GDataParsable built |
const gchar *`element_name`; | the name of the XML element which represents this parsable |
const gchar *`element_namespace`; | the prefix of the XML namespace used for the parsable |

Since: 0.3.0

## Property Details

### The `“constructed-from-xml”` property

      “constructed-from-xml”     gboolean

Specifies whether the object was constructed by parsing XML or manually.

Flags: Read / Write / Construct Only

Default value: FALSE

Since: 0.7.0