DOM Parsing

Collaboration diagram for DOM Parsing:

Typedefs
typedef struct _tag_dom_parser	GF_DOMParser

Functions
GF_DOMParser *	gf_xml_dom_new ()
void	gf_xml_dom_del (GF_DOMParser *parser)
GF_Err	gf_xml_dom_parse (GF_DOMParser *parser, const char *file, gf_xml_sax_progress OnProgress, void *cbk)
GF_Err	gf_xml_dom_parse_string (GF_DOMParser *parser, char *string)
const char *	gf_xml_dom_get_error (GF_DOMParser *parser)
u32	gf_xml_dom_get_line (GF_DOMParser *parser)
GF_Err	gf_xml_dom_enable_passthrough (GF_DOMParser *dom)
u32	gf_xml_dom_get_root_nodes_count (GF_DOMParser *parser)
GF_XMLNode *	gf_xml_dom_get_root_idx (GF_DOMParser *parser, u32 idx)
GF_XMLNode *	gf_xml_dom_detach_root (GF_DOMParser *parser)
char *	gf_xml_dom_serialize (GF_XMLNode *node, Bool content_only, Bool no_escape)
char *	gf_xml_dom_serialize_root (GF_XMLNode *node, Bool content_only, Bool no_escape)
GF_XMLNode *	gf_xml_dom_get_root (GF_DOMParser *parser)
GF_XMLAttribute *	gf_xml_dom_create_attribute (const char *name, const char *value)
GF_Err	gf_xml_dom_append_child (GF_XMLNode *node, GF_XMLNode *child)
GF_XMLNode *	gf_xml_dom_node_new (const char *ns, const char *name)
void	gf_xml_dom_node_del (GF_XMLNode *node)
void	gf_xml_dom_node_reset (GF_XMLNode *node, Bool reset_attribs, Bool reset_children)
GF_Err	gf_xml_dom_node_check_namespace (const GF_XMLNode *n, const char *expected_node_name, const char *expected_ns_prefix)
void	gf_xml_dump_string (FILE *file, const char *before, const char *str, const char *after)
GF_XMLNode *	gf_xml_dom_node_clone (GF_XMLNode *node)

Detailed Description

    ! DOM Full XML document Parsing API
    GPAC can do one-pass full document parsing of XML document using this DOM API.

Typedef Documentation

GF_DOMParser

typedef struct _tag_dom_parser GF_DOMParser

the DOM loader. GPAC can also load complete XML document in memory, using a DOM-like approach. This is a simpler approach for document parsing not requiring progressive loading

Function Documentation

gf_xml_dom_new()

GF_DOMParser* gf_xml_dom_new

(

)

the DOM loader constructor

Returns

the created DOM loader, NULL if memory error

gf_xml_dom_del()

void gf_xml_dom_del

(

GF_DOMParser *

parser

)

the DOM loader constructor

Parameters

parser

the DOM parser to destroy

gf_xml_dom_parse()

GF_Err gf_xml_dom_parse	(	GF_DOMParser *	parser,
		const char *	file,
		gf_xml_sax_progress	OnProgress,
		void *	cbk
	)

Parses an XML document or fragment contained in a file

Parameters

parser	the DOM parser to use
file	the file to parse
OnProgress	an optional callback for the parser
cbk	an optional user data for the progress callback

Returns

error code if any

gf_xml_dom_parse_string()

GF_Err gf_xml_dom_parse_string	(	GF_DOMParser *	parser,
		char *	string
	)

Parses an XML document or fragment contained in memory

Parameters

parser	the DOM parser to use
string	the string to parse

Returns

error code if any

gf_xml_dom_get_error()

const char* gf_xml_dom_get_error

(

GF_DOMParser *

parser

)

Gets the last error that happened during the parsing. The parser aborts at the first error found within a SAX callback

Parameters

parser

the DOM parser to use

Returns

last error code if any

gf_xml_dom_get_line()

u32 gf_xml_dom_get_line

(

GF_DOMParser *

parser

)

Gets the current line of the parser. Used for error logging

Parameters

parser

the DOM parser to use

Returns

last loaded line number

gf_xml_dom_enable_passthrough()

GF_Err gf_xml_dom_enable_passthrough

(

GF_DOMParser *

dom

)

Enable marking all text nodes as already validated , so that re-serializing will skip text string checking

Parameters

dom	the dom parser

Returns

error if any

gf_xml_dom_get_root_nodes_count()

u32 gf_xml_dom_get_root_nodes_count

(

GF_DOMParser *

parser

)

Gets the number of root nodes in the document (not XML compliant, but used in DASH for remote periods)

Parameters

parser

the DOM parser to use

Returns

the number of root elements in the document

gf_xml_dom_get_root_idx()

GF_XMLNode* gf_xml_dom_get_root_idx	(	GF_DOMParser *	parser,
		u32	idx
	)

Gets the root node at the given index.

Parameters

parser	the DOM parser to use
idx	index of the root node to get (0 being the first node)

Returns

the root element at the given index, or NULL if error

gf_xml_dom_detach_root()

GF_XMLNode* gf_xml_dom_detach_root

(

GF_DOMParser *

parser

)

Gets the root node of the document and assign the parser root to NULL.

Parameters

parser

the DOM parser to use

Returns

the root element at the given index, or NULL if error. The element must be freed by the caller

gf_xml_dom_serialize()

char* gf_xml_dom_serialize	(	GF_XMLNode *	node,
		Bool	content_only,
		Bool	no_escape
	)

Serialize a node to a string

Parameters

node	the node to flush
content_only	Whether to include or not the parent node
no_escape	if set, disable escape of XML reserved chars (<,>,",') in text nodes

Returns

The resulting serialization. The string has to be freed with gf_free

gf_xml_dom_serialize_root()

char* gf_xml_dom_serialize_root	(	GF_XMLNode *	node,
		Bool	content_only,
		Bool	no_escape
	)

Serialize a root document node - same as gf_xml_dom_serialize but insert

<?xml version="1.0" encoding="UTF-8"?> 

at beginning

Parameters

node	the node to flush
content_only	Whether to include or not the parent node
no_escape	if set, disable escape of XML reserved chars (<,>,",') in text nodes

Returns

The resulting serialization. The string has to be freed with gf_free

gf_xml_dom_get_root()

GF_XMLNode* gf_xml_dom_get_root

(

GF_DOMParser *

parser

)

Get the root element – the only top level element – of the document.

Parameters

parser

the DOM structure

Returns

The corresponding node if exists, otherwise NULL;

gf_xml_dom_create_attribute()

GF_XMLAttribute* gf_xml_dom_create_attribute	(	const char *	name,
		const char *	value
	)

Creates an attribute with the given name and value.

Parameters

name	the attribute name
value	the value

Returns

The created attribute ;

gf_xml_dom_append_child()

GF_Err gf_xml_dom_append_child	(	GF_XMLNode *	node,
		GF_XMLNode *	child
	)

Adds the node to the end of the list of children of this node.

Parameters

node	the GF_XMLNode node
child	the GF_XMLNode child to append

Returns

Error code if any, otherwise GF_OK

gf_xml_dom_node_new()

GF_XMLNode* gf_xml_dom_node_new	(	const char *	ns,
		const char *	name
	)

Create a node.

Parameters

ns	the target namespace or NULL if none
name	the target name or NULL to create text node

Returns

new node, NULL if error.

gf_xml_dom_node_del()

void gf_xml_dom_node_del

(

GF_XMLNode *

node

)

Destroys a node, its attributes and its children

Parameters

node	the node to free

gf_xml_dom_node_reset()

void gf_xml_dom_node_reset	(	GF_XMLNode *	node,
		Bool	reset_attribs,
		Bool	reset_children
	)

Reset a node

Parameters

node	the node to reset
reset_attribs	if GF_TRUE, reset all node attributes
reset_children	if GF_TRUE, reset all node children

gf_xml_dom_node_check_namespace()

GF_Err gf_xml_dom_node_check_namespace	(	const GF_XMLNode *	n,
		const char *	expected_node_name,
		const char *	expected_ns_prefix
	)

Gets the element and check that the namespace is known ('xmlns'-only supported for now)

Parameters

n	the node to process
expected_node_name	optional expected name for node n
expected_ns_prefix	optional expected namespace prefix for node n

Returns

error code or GF_OK

gf_xml_dump_string()

void gf_xml_dump_string	(	FILE *	file,
		const char *	before,
		const char *	str,
		const char *	after
	)

Writes a string to an xml file and replaces forbidden chars with xml entities

Parameters

file	the xml output file
before	optional string prefix (assumed xml-valid, pass NULL if not needed)
str	the string to dump and escape
after	optional string suffix (assumed xml-valid, pass NULL if not needed)

gf_xml_dom_node_clone()

GF_XMLNode* gf_xml_dom_node_clone

(

GF_XMLNode *

node

)

Deep cloning of a node

Parameters

node	the node to clone

Returns

the cloned node