element.h File Reference

#include <stdbool.h>
#include <dom/core/element.h>
#include "core/node.h"

Go to the source code of this file.

Classes
struct	dom_element
struct	dom_element_protected_vtable

Macros
#define	DOM_ELEMENT_VTABLE
#define	DOM_NODE_VTABLE_ELEMENT
#define	dom_element_parse_attribute(e, n, v, p)
#define	DOM_ELEMENT_PROTECT_VTABLE    _dom_element_parse_attribute
#define	DOM_NODE_PROTECT_VTABLE_ELEMENT
#define	dom_element_copy_internal(o, n)

Typedefs
typedef struct dom_element_protected_vtable	dom_element_protected_vtable

Functions
dom_exception	_dom_element_create (struct dom_document *doc, dom_string *name, dom_string *namespace, dom_string *prefix, struct dom_element **result)
dom_exception	_dom_element_initialise (struct dom_document *doc, struct dom_element *el, dom_string *name, dom_string *namespace, dom_string *prefix)
void	_dom_element_finalise (struct dom_element *ele)
void	_dom_element_destroy (struct dom_element *element)
dom_exception	_dom_element_get_tag_name (struct dom_element *element, dom_string **name)
dom_exception	_dom_element_get_attribute (struct dom_element *element, dom_string *name, dom_string **value)
dom_exception	_dom_element_set_attribute (struct dom_element *element, dom_string *name, dom_string *value)
dom_exception	_dom_element_remove_attribute (struct dom_element *element, dom_string *name)
dom_exception	_dom_element_get_attribute_node (struct dom_element *element, dom_string *name, struct dom_attr **result)
dom_exception	_dom_element_set_attribute_node (struct dom_element *element, struct dom_attr *attr, struct dom_attr **result)
dom_exception	_dom_element_remove_attribute_node (struct dom_element *element, struct dom_attr *attr, struct dom_attr **result)
dom_exception	_dom_element_get_elements_by_tag_name (struct dom_element *element, dom_string *name, struct dom_nodelist **result)
dom_exception	_dom_element_get_attribute_ns (struct dom_element *element, dom_string *namespace, dom_string *localname, dom_string **value)
dom_exception	_dom_element_set_attribute_ns (struct dom_element *element, dom_string *namespace, dom_string *qname, dom_string *value)
dom_exception	_dom_element_remove_attribute_ns (struct dom_element *element, dom_string *namespace, dom_string *localname)
dom_exception	_dom_element_get_attribute_node_ns (struct dom_element *element, dom_string *namespace, dom_string *localname, struct dom_attr **result)
dom_exception	_dom_element_set_attribute_node_ns (struct dom_element *element, struct dom_attr *attr, struct dom_attr **result)
dom_exception	_dom_element_get_elements_by_tag_name_ns (struct dom_element *element, dom_string *namespace, dom_string *localname, struct dom_nodelist **result)
dom_exception	_dom_element_has_attribute (struct dom_element *element, dom_string *name, bool *result)
dom_exception	_dom_element_has_attribute_ns (struct dom_element *element, dom_string *namespace, dom_string *localname, bool *result)
dom_exception	_dom_element_get_schema_type_info (struct dom_element *element, struct dom_type_info **result)
dom_exception	_dom_element_set_id_attribute (struct dom_element *element, dom_string *name, bool is_id)
dom_exception	_dom_element_set_id_attribute_ns (struct dom_element *element, dom_string *namespace, dom_string *localname, bool is_id)
dom_exception	_dom_element_set_id_attribute_node (struct dom_element *element, struct dom_attr *id_attr, bool is_id)
dom_exception	_dom_element_get_classes (struct dom_element *element, lwc_string ***classes, uint32_t *n_classes)
dom_exception	_dom_element_has_class (struct dom_element *element, lwc_string *name, bool *match)
dom_exception	_dom_element_get_attributes (dom_node_internal *node, struct dom_namednodemap **result)
dom_exception	_dom_element_has_attributes (dom_node_internal *node, bool *result)
dom_exception	_dom_element_normalize (dom_node_internal *node)
dom_exception	_dom_element_lookup_prefix (dom_node_internal *node, dom_string *namespace, dom_string **result)
dom_exception	_dom_element_is_default_namespace (dom_node_internal *node, dom_string *namespace, bool *result)
dom_exception	_dom_element_lookup_namespace (dom_node_internal *node, dom_string *prefix, dom_string **result)
dom_exception	_dom_element_parse_attribute (dom_element *ele, dom_string *name, dom_string *value, dom_string **parsed)
void	__dom_element_destroy (dom_node_internal *node)
dom_exception	_dom_element_copy (dom_node_internal *old, dom_node_internal **copy)
dom_exception	_dom_element_copy_internal (dom_element *old, dom_element *new)
dom_exception	_dom_element_get_id (struct dom_element *ele, dom_string **id)

Variables
const struct dom_element_vtable	_dom_element_vtable

Macro Definition Documentation

dom_element_copy_internal

#define dom_element_copy_internal	(		o,
			n
	)

Value:

                _dom_element_copy_internal( \
                (dom_element *) (o), (dom_element *) (n))

dom_element_parse_attribute

#define dom_element_parse_attribute	(		e,
			n,
			v,
			p
	)

Value:

                dom_element_parse_attribute( \
                (dom_element *) (e), (dom_string *) (n), \
                (dom_string *) (v), (dom_string **) (p))

DOM_ELEMENT_PROTECT_VTABLE

#define DOM_ELEMENT_PROTECT_VTABLE    _dom_element_parse_attribute

DOM_ELEMENT_VTABLE

#define DOM_ELEMENT_VTABLE

Value:

        _dom_element_get_tag_name, \
        _dom_element_get_attribute, \
        _dom_element_set_attribute, \
        _dom_element_remove_attribute, \
        _dom_element_get_attribute_node, \
        _dom_element_set_attribute_node, \
        _dom_element_remove_attribute_node, \
        _dom_element_get_elements_by_tag_name, \
        _dom_element_get_attribute_ns, \
        _dom_element_set_attribute_ns, \
        _dom_element_remove_attribute_ns, \
        _dom_element_get_attribute_node_ns, \
        _dom_element_set_attribute_node_ns, \
        _dom_element_get_elements_by_tag_name_ns, \
        _dom_element_has_attribute, \
        _dom_element_has_attribute_ns, \
        _dom_element_get_schema_type_info, \
        _dom_element_set_id_attribute, \
        _dom_element_set_id_attribute_ns, \
        _dom_element_set_id_attribute_node, \
        _dom_element_get_classes, \
        _dom_element_has_class

DOM_NODE_PROTECT_VTABLE_ELEMENT

#define DOM_NODE_PROTECT_VTABLE_ELEMENT

Value:

        __dom_element_destroy, \
        _dom_element_copy

DOM_NODE_VTABLE_ELEMENT

#define DOM_NODE_VTABLE_ELEMENT

Typedef Documentation

dom_element_protected_vtable

typedef struct dom_element_protected_vtable dom_element_protected_vtable

Function Documentation

__dom_element_destroy()

void __dom_element_destroy

(

dom_node_internal *

node

)

_dom_element_copy()

dom_exception _dom_element_copy	(	dom_node_internal *	old,
		dom_node_internal **	copy
	)

_dom_element_copy_internal()

dom_exception _dom_element_copy_internal	(	dom_element *	old,
		dom_element *	new
	)

_dom_element_create()

dom_exception _dom_element_create	(	struct dom_document *	doc,
		dom_string *	name,
		dom_string *	namespace,
		dom_string *	prefix,
		struct dom_element **	result
	)

Create an element node

Parameters

doc	The owning document
name	The (local) name of the node to create
namespace	The namespace URI of the element, or NULL
prefix	The namespace prefix of the element, or NULL
result	Pointer to location to receive created element

Returns

DOM_NO_ERR on success, DOM_INVALID_CHARACTER_ERR if ::name is invalid, DOM_NO_MEM_ERR on memory exhaustion.

::doc, ::name, ::namespace and ::prefix will have their reference counts increased.

The returned element will already be referenced.

_dom_element_destroy()

void _dom_element_destroy

(

struct dom_element *

element

)

Destroy an element

Parameters

element

The element to destroy

The contents of ::element will be destroyed and ::element will be freed.

_dom_element_finalise()

void _dom_element_finalise

(

struct dom_element *

ele

)

Finalise a dom_element

Parameters

ele	The element

Todo:

destroy schema type info

_dom_element_get_attribute()

dom_exception _dom_element_get_attribute	(	struct dom_element *	element,
		dom_string *	name,
		dom_string **	value
	)

Retrieve an attribute from an element by name

Parameters

element	The element to retrieve attribute from
name	The attribute's name
value	Pointer to location to receive attribute's value

Returns

DOM_NO_ERR.

The returned string will have its reference count increased. It is the responsibility of the caller to unref the string once it has finished with it.

_dom_element_get_attribute_node()

dom_exception _dom_element_get_attribute_node	(	struct dom_element *	element,
		dom_string *	name,
		struct dom_attr **	result
	)

Retrieve an attribute node from an element by name

Parameters

element	The element to retrieve attribute node from
name	The attribute's name
result	Pointer to location to receive attribute node

Returns

DOM_NO_ERR.

The returned node will have its reference count increased. It is the responsibility of the caller to unref the node once it has finished with it.

_dom_element_get_attribute_node_ns()

dom_exception _dom_element_get_attribute_node_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	localname,
		struct dom_attr **	result
	)

Retrieve an attribute node from an element by namespace/localname

Parameters

element	The element to retrieve attribute from
namespace	The attribute's namespace URI
localname	The attribute's local name
result	Pointer to location to receive attribute node

Returns

DOM_NO_ERR on success, DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

The returned node will have its reference count increased. It is the responsibility of the caller to unref the node once it has finished with it.

_dom_element_get_attribute_ns()

dom_exception _dom_element_get_attribute_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	localname,
		dom_string **	value
	)

Retrieve an attribute from an element by namespace/localname

Parameters

element	The element to retrieve attribute from
namespace	The attribute's namespace URI, or NULL
localname	The attribute's local name
value	Pointer to location to receive attribute's value

Returns

DOM_NO_ERR on success, DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

The returned string will have its reference count increased. It is the responsibility of the caller to unref the string once it has finished with it.

_dom_element_get_attributes()

dom_exception _dom_element_get_attributes	(	dom_node_internal *	node,
		struct dom_namednodemap **	result
	)

_dom_element_get_classes()

dom_exception _dom_element_get_classes	(	struct dom_element *	element,
		lwc_string ***	classes,
		uint32_t *	n_classes
	)

Obtain a pre-parsed array of class names for an element

Parameters

element	Element containing classes
classes	Pointer to location to receive libdom-owned array
n_classes	Pointer to location to receive number of classes

Returns

DOM_NO_ERR on success, DOM_NO_MEM_ERR on memory exhaustion

_dom_element_get_elements_by_tag_name()

dom_exception _dom_element_get_elements_by_tag_name	(	struct dom_element *	element,
		dom_string *	name,
		struct dom_nodelist **	result
	)

Retrieve a list of descendant elements of an element which match a given tag name

Parameters

element	The root of the subtree to search
name	The tag name to match (or "*" for all tags)
result	Pointer to location to receive result

Returns

DOM_NO_ERR.

The returned nodelist will have its reference count increased. It is the responsibility of the caller to unref the nodelist once it has finished with it.

_dom_element_get_elements_by_tag_name_ns()

dom_exception _dom_element_get_elements_by_tag_name_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	localname,
		struct dom_nodelist **	result
	)

Retrieve a list of descendant elements of an element which match a given namespace/localname pair.

Parameters

element	The root of the subtree to search
namespace	The namespace URI to match (or "*" for all)
localname	The local name to match (or "*" for all)
result	Pointer to location to receive result

Returns

DOM_NO_ERR on success, DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

The returned nodelist will have its reference count increased. It is the responsibility of the caller to unref the nodelist once it has finished with it.

Todo:

ensure XML feature is supported

_dom_element_get_id()

dom_exception _dom_element_get_id	(	struct dom_element *	ele,
		dom_string **	id
	)

Get the ID string of the element

Parameters

ele	The element
id	The ID of this element

Returns

DOM_NO_ERR on success, appropriate dom_exception on failure.

_dom_element_get_schema_type_info()

dom_exception _dom_element_get_schema_type_info	(	struct dom_element *	element,
		struct dom_type_info **	result
	)

Retrieve the type information associated with an element

Parameters

element	The element to retrieve type information from
result	Pointer to location to receive type information

Returns

DOM_NO_ERR.

The returned typeinfo will have its reference count increased. It is the responsibility of the caller to unref the typeinfo once it has finished with it.

_dom_element_get_tag_name()

dom_exception _dom_element_get_tag_name	(	struct dom_element *	element,
		dom_string **	name
	)

Retrieve an element's tag name

Parameters

element	The element to retrieve the name from
name	Pointer to location to receive name

Returns

DOM_NO_ERR on success, DOM_NO_MEM_ERR on memory exhaustion.

The returned string will have its reference count increased. It is the responsibility of the caller to unref the string once it has finished with it.

_dom_element_has_attribute()

dom_exception _dom_element_has_attribute	(	struct dom_element *	element,
		dom_string *	name,
		bool *	result
	)

Determine if an element possesses and attribute with the given name

Parameters

element	The element to query
name	The attribute name to look for
result	Pointer to location to receive result

Returns

DOM_NO_ERR.

_dom_element_has_attribute_ns()

dom_exception _dom_element_has_attribute_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	localname,
		bool *	result
	)

Determine if an element possesses and attribute with the given namespace/localname pair.

Parameters

element	The element to query
namespace	The attribute namespace URI to look for
localname	The attribute local name to look for
result	Pointer to location to receive result

Returns

DOM_NO_ERR on success, DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

_dom_element_has_attributes()

dom_exception _dom_element_has_attributes	(	dom_node_internal *	node,
		bool *	result
	)

_dom_element_has_class()

dom_exception _dom_element_has_class	(	struct dom_element *	element,
		lwc_string *	name,
		bool *	match
	)

Determine if an element has an associated class

Parameters

element	Element to consider
name	Class name to look for
match	Pointer to location to receive result

Returns

DOM_NO_ERR.

_dom_element_initialise()

dom_exception _dom_element_initialise	(	struct dom_document *	doc,
		struct dom_element *	el,
		dom_string *	name,
		dom_string *	namespace,
		dom_string *	prefix
	)

Initialise an element node

Parameters

doc	The owning document
el	The element
name	The (local) name of the node to create
namespace	The namespace URI of the element, or NULL
prefix	The namespace prefix of the element, or NULL

Returns

DOM_NO_ERR on success, DOM_INVALID_CHARACTER_ERR if ::name is invalid, DOM_NO_MEM_ERR on memory exhaustion.

The caller should make sure that ::name is a valid NCName.

::doc, ::name, ::namespace and ::prefix will have their reference counts increased.

The returned element will already be referenced.

_dom_element_is_default_namespace()

dom_exception _dom_element_is_default_namespace	(	dom_node_internal *	node,
		dom_string *	namespace,
		bool *	result
	)

Test whether certain namespace is the default namespace of some node.

Parameters

node	The Node to test
namespace	The namespace to test
result	true is the namespace is default namespace

Returns

DOM_NO_ERR on success, appropriate dom_exception on failure.

_dom_element_lookup_namespace()

dom_exception _dom_element_lookup_namespace	(	dom_node_internal *	node,
		dom_string *	prefix,
		dom_string **	result
	)

Look up the namespace with certain prefix.

Parameters

node	The current node in which we search for the prefix
prefix	The prefix to search
result	The result namespace if found

Returns

DOM_NO_ERR on success, appropriate dom_exception on failure.

_dom_element_lookup_prefix()

dom_exception _dom_element_lookup_prefix	(	dom_node_internal *	node,
		dom_string *	namespace,
		dom_string **	result
	)

Look up the prefix which matches the namespace.

Parameters

node	The current Node in which we search for
namespace	The namespace for which we search a prefix
result	The returned prefix

Returns

DOM_NO_ERR on success, appropriate dom_exception on failure.

_dom_element_normalize()

dom_exception _dom_element_normalize

(

dom_node_internal *

node

)

_dom_element_parse_attribute()

dom_exception _dom_element_parse_attribute	(	dom_element *	ele,
		dom_string *	name,
		dom_string *	value,
		dom_string **	parsed
	)

The virtual function to parse some dom attribute

Parameters

ele	The element object
name	The name of the attribute
value	The new value of the attribute
parsed	The parsed value of the attribute

Returns

DOM_NO_ERR on success.

Note

: This virtual method is provided to serve as a template method. When any attribute is set or added, the attribute's value should be checked to make sure that it is a valid one. And the child class of dom_element may to do some special stuff on the attribute is set. Take some integer attribute as example:

1. The client call dom_element_set_attribute("size", "10.1"), but the size attribute may only accept an integer, and only the specific dom_element know this. And the dom_attr_set_value method, which is called by dom_element_set_attribute should call the this virtual template method.
2. The overload virtual function of following one will truncate the "10.1" to "10" to make sure it is a integer. And of course, the overload method may also save the integer as a 'int' C type for later easy accessing by any client.

_dom_element_remove_attribute()

dom_exception _dom_element_remove_attribute	(	struct dom_element *	element,
		dom_string *	name
	)

Remove an attribute from an element by name

Parameters

element	The element to remove attribute from
name	The name of the attribute to remove

Returns

DOM_NO_ERR on success, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly.

_dom_element_remove_attribute_node()

dom_exception _dom_element_remove_attribute_node	(	struct dom_element *	element,
		struct dom_attr *	attr,
		struct dom_attr **	result
	)

Remove an attribute node from an element

Parameters

element	The element to remove attribute node from
attr	The attribute node to remove
result	Pointer to location to receive attribute node

Returns

DOM_NO_ERR on success, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_NOT_FOUND_ERR if ::attr is not an attribute of ::element.

The returned node will have its reference count increased. It is the responsibility of the caller to unref the node once it has finished with it.

_dom_element_remove_attribute_ns()

dom_exception _dom_element_remove_attribute_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	localname
	)

Remove an attribute from an element by namespace/localname

Parameters

element	The element to remove attribute from
namespace	The attribute's namespace URI
localname	The attribute's local name

Returns

DOM_NO_ERR on success, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

_dom_element_set_attribute()

dom_exception _dom_element_set_attribute	(	struct dom_element *	element,
		dom_string *	name,
		dom_string *	value
	)

Set an attribute on an element by name

Parameters

element	The element to set attribute on
name	The attribute's name
value	The attribute's value

Returns

DOM_NO_ERR on success, DOM_INVALID_CHARACTER_ERR if ::name is invalid, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly.

_dom_element_set_attribute_node()

dom_exception _dom_element_set_attribute_node	(	struct dom_element *	element,
		struct dom_attr *	attr,
		struct dom_attr **	result
	)

Set an attribute node on an element, replacing existing node, if present

Parameters

element	The element to add a node to
attr	The attribute node to add
result	Pointer to location to receive previous node

Returns

DOM_NO_ERR on success, DOM_WRONG_DOCUMENT_ERR if ::attr does not belong to the same document as ::element, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_INUSE_ATTRIBUTE_ERR if ::attr is already an attribute of another Element node.

The returned node will have its reference count increased. It is the responsibility of the caller to unref the node once it has finished with it.

_dom_element_set_attribute_node_ns()

dom_exception _dom_element_set_attribute_node_ns	(	struct dom_element *	element,
		struct dom_attr *	attr,
		struct dom_attr **	result
	)

Set an attribute node on an element, replacing existing node, if present

Parameters

element	The element to add a node to
attr	The attribute node to add
result	Pointer to location to recieve previous node

Returns

DOM_NO_ERR on success, DOM_WRONG_DOCUMENT_ERR if ::attr does not belong to the same document as ::element, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_INUSE_ATTRIBUTE_ERR if ::attr is already an attribute of another Element node. DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

The returned node will have its reference count increased. It is the responsibility of the caller to unref the node once it has finished with it.

_dom_element_set_attribute_ns()

dom_exception _dom_element_set_attribute_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	qname,
		dom_string *	value
	)

Set an attribute on an element by namespace/qualified name

Parameters

element	The element to set attribute on
namespace	The attribute's namespace URI
qname	The attribute's qualified name
value	The attribute's value

Returns

DOM_NO_ERR on success, DOM_INVALID_CHARACTER_ERR if ::qname is invalid, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_NAMESPACE_ERR if ::qname is malformed, or ::qname has a prefix and ::namespace is null, or ::qname has a prefix "xml" and ::namespace is not "http://www.w3.org/XML/1998/namespace", or ::qname has a prefix "xmlns" and ::namespace is not "http://www.w3.org/2000/xmlns", or ::namespace is "http://www.w3.org/2000/xmlns" and ::qname is not prefixed "xmlns", DOM_NOT_SUPPORTED_ERR if the implementation does not support the feature "XML" and the language exposed through the Document does not support Namespaces.

_dom_element_set_id_attribute()

dom_exception _dom_element_set_id_attribute	(	struct dom_element *	element,
		dom_string *	name,
		bool	is_id
	)

(Un)declare an attribute as being an element's ID by name

Parameters

element	The element containing the attribute
name	The attribute's name
is_id	Whether the attribute is an ID

Returns

DOM_NO_ERR on success, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_NOT_FOUND_ERR if the specified node is not an attribute of ::element.

Note

: The DOM spec does not say: how to deal with when there are two or more isId attribute nodes. Here, the implementation just maintain only one such attribute node.

_dom_element_set_id_attribute_node()

dom_exception _dom_element_set_id_attribute_node	(	struct dom_element *	element,
		struct dom_attr *	id_attr,
		bool	is_id
	)

(Un)declare an attribute node as being an element's ID

Parameters

element	The element containing the attribute
id_attr	The attribute node
is_id	Whether the attribute is an ID

Returns

DOM_NO_ERR on success, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_NOT_FOUND_ERR if the specified node is not an attribute of ::element.

_dom_element_set_id_attribute_ns()

dom_exception _dom_element_set_id_attribute_ns	(	struct dom_element *	element,
		dom_string *	namespace,
		dom_string *	localname,
		bool	is_id
	)

(Un)declare an attribute as being an element's ID by namespace/localname

Parameters

element	The element containing the attribute
namespace	The attribute's namespace URI
localname	The attribute's local name
is_id	Whether the attribute is an ID

Returns

DOM_NO_ERR on success, DOM_NO_MODIFICATION_ALLOWED_ERR if ::element is readonly, DOM_NOT_FOUND_ERR if the specified node is not an attribute of ::element.

Variable Documentation

_dom_element_vtable

const struct dom_element_vtable _dom_element_vtable

extern