Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DOM_Document(3m)	     Document Object Model	      DOM_Document(3m)

NAME
       DOM_Document - the Document Object Model	(DOM) DOM_Document interface

SYNOPSIS
       #include	<domc.h>

       int DOM_DocumentLS_load(DOM_DocumentLS *this, const char	*uri);
       int DOM_DocumentLS_save(DOM_DocumentLS *this, const char	*uri, const DOM_Node *node);
       int DOM_DocumentLS_fread(DOM_DocumentLS *this, FILE *stream);
       int DOM_DocumentLS_fwrite(const DOM_DocumentLS *this, FILE *stream);

       DOM_Element *DOM_Document_getDocumentElement(DOM_Document *doc);
       void DOM_Document_destroyNode(DOM_Document *doc,	DOM_Node *node);
       void DOM_Document_destroyNodeList(DOM_Document *doc, DOM_NodeList *nl, int free_nodes);
       DOM_Element *DOM_Document_createElement(DOM_Document *this, DOM_String *tagName);
       DOM_DocumentFragment *DOM_Document_createDocumentFragment(DOM_Document *this);
       DOM_Text	*DOM_Document_createTextNode(DOM_Document *this, DOM_String *data);
       DOM_Comment *DOM_Document_createComment(DOM_Document *this, DOM_String *data);
       DOM_CDATASection	*DOM_Document_createCDATASection(DOM_Document *this, DOM_String	*data);
       DOM_ProcessingInstruction *DOM_Document_createProcessingInstruction(DOM_Document	*this,
		   DOM_String *target,
		   DOM_String *data);
       DOM_Attr	*DOM_Document_createAttribute(DOM_Document *this, DOM_String *name);
       DOM_EntityReference *DOM_Document_createEntityReference(DOM_Document *this, DOM_String *name);
       DOM_NodeList *DOM_Document_getElementsByTagName(DOM_Document *this, DOM_String *tagname);

DESCRIPTION
       A  DOM_Document	represents an entire XML document and acts as the root
       of the DOM tree.	Because	nodes cannot exist outside of the context of a
       DOM_Document this interface provides the	factory	methods	needed to cre-
       ate individual nodes to compose and modify DOM trees. The ownerDocument
       member  of  a DOM_Node points to	the document from which	it was created
       (except DOM_DocumentType	and DOM_Document which may have	a NULL	owner-
       Document	member). This interface	also provides the DOM_Document_getEle-
       mentsByTagName function for retriving all  elements  with  a  specified
       name.

       To  build  a  document  from scratch use	the expression DOM_Implementa-
       tion_createDocument(NULL, NULL, NULL) to	create an empty	 document  and
       add new nodes using DOM_Document_createElement, DOM_Document_createCom-
       ment, etc with DOM_Node_appendChild, DOM_Node_insertBefore or  similar.
       See the DOM_Implementation and DOM_Node interface documentation for de-
       tails.

       Memory Management

       The DOM_DocumentLS_load,	 DOM_DocumentLS_read,  and  DOM_Document_crea-
       teXxx  functions	 allocate memory that must at some point be freed with
       DOM_Document_destoryNode.  The

       DOM_Document_destroyNode	function may be	used to	released nodes of  all
       types such as DOM_Element, DOM_Text, DOM_Attr, DOM_Document.  All chil-
       dren of a node are freed	when the parent	is freed. An  entire  document
       may  be	free  with  the	expression DOM_Document_destroyNode(doc, doc).
       Beware that freeing a node that is still	a decendant  of	 another  node
       will  result in a tree with invalid pointers and	will cause the program
       to crash	when freed again. There	are only two other  special  cases  to
       consider.  First,  the  DOM_Document_destroyNodeList  function  must be
       called for each DOM_NodeList returned by	 DOM_Element_getElementsByTag-
       Name  and DOM_Document_getElementsByTagName.  Second, the DOM_Document-
       Fragment	node cannot be a child of another  node.  When	added  to  the
       tree,  it's children are	actually moved into the	target node leaving an
       empty  DOM_DocumentFragment.   This  empty  node	 must  be  freed  with
       DOM_Document_destroyNode	 if  it	 will no longer	be used. For complete-
       ness, the DOM_DocumentEvent_destroyEvent	function  must	be  called  to
       free  DOM_Event objects however that non-core API is not	yet documented
       here.

       DOM_DocumentLS_load
	      The DOM_DocumentLS_load function builds a	DOM tree from the com-
	      plete well formed	XML document specified by the uri parameter.

       DOM_DocumentLS_save
	      The  DOM_DocumentLS_save	function serializes the	DOM_DocumentLS
	      object to	a file specified by the	uri parameter.	Normally  this
	      object is	a complete DOM_Document	node however any DOM_Node type
	      such as a	DOM_Element will be accepted (although only a complete
	      well formed XML document may be loaded).

       DOM_DocumentLS_fread
	      The  DOM_DocumentLS_fread	 function  builds  a DOM tree from the
	      complete well formed XML document	read from the stream specified
	      by the stream parameter.

       DOM_DocumentLS_fwrite
	      The DOM_DocumentLS_fwrite	function serializes the	DOM_DocumentLS
	      object to	the stream specified by	the stream parameter. Normally
	      this object is a complete	DOM_Document node however any DOM_Node
	      type such	as a DOM_Element will be  accepted  (although  only  a
	      complete well formed XML document	may be read).

       getDocumentElement
	      Returns  the root	element	of the document	tree. The root element
	      is also accessable through the  childNodes  DOM_NodeList	member
	      however  the  children  of a DOM_Document	may also be processing
	      instructions, document type nodes, and comments which  may  pre-
	      ceed  the	 document element in the list. Therefore this function
	      is provied as a convienience.

       destroyNode
	      The DOM_Document_destroyNode function frees  the	node  node  as
	      well  as	it's  children if any. An entire DOM tree may be freed
	      using the	expression  DOM_Document_destroyNode(doc,  doc).   See
	      the section above	entitledMemory Management.

       destroyNodeList
	      The DOM_Document_destroyNodeList function	frees the DOM_NodeList
	      object nl.  The free_nodes parameter should be 0 indicating that
	      nodes  in	 the  list should not be freed as they are almost cer-
	      tainly members of	a DOM tree and will be freed when the tree  is
	      freed.  This  function  must be called for each list returned by
	      the  DOM_Element_getElementsByTagName  and  DOM_Document_getEle-
	      mentsByTagName functions.

       createElement
	      Create  a	DOM_Element object with	the name tagName with no chil-
	      dren.

	      Note: currently DOMC does	not populate default attributes	speci-
	      fied in a	DTD as it should.

       createDocumentFragment
	      Create  an  empty	 DOM_DocumentFragment  object into which other
	      nodes may	be  placed.  Subsequently  inserting  or  appending  a
	      DOM_DocumentFragment  into  another  node	 will  move all	of the
	      fragments	children into the target node.	After  doing  this  an
	      empty  DOM_DocumentFragment  object  is  left behind and must be
	      freed with DOM_Document_destroyNode  if  it  will	 not  be  used
	      again.

       createTextNode
	      Creates  a  DOM_Text node	given the specified string represented
	      by the data parameter.

       createComment
	      Creates a	DOM_Comment node with the  specified  data  parameter.
	      The  '<--' and '-->' comment delimiters are not part of the com-
	      ment and should not be included in the data string.

       createCDATASection
	      Creates a	DOM_CDATASection node from the specified string	 data.
	      Only  the	 text  inside the '<[['	and ']]>' brackets consititute
	      the CDATA	section	content.

       createProcessingInstruction
	      Creates a	DOM_ProcessingInstruction  node	 given	the  specified
	      target  and data string parameters. The '<?' and '?>' processing
	      instruction delimiters are not part of the data string.

       createAttribute
	      Creates a	DOM_Attr with the given	name parameter.	 The  DOM_Attr
	      object  may then be assigned to a	DOM_Element using the DOM_Ele-
	      ment_setAttributeNode function. All  attributes  of  an  element
	      will be freed if the element is freed.

       createEntityReference
	      Creates a	DOM_EntityReference object.

	      Note:  currently	DOMC  does  not	 resolve entities, meaning the
	      child list of a DOM_EntityReference will not be populated	if the
	      entity  is  known	as it would in a full featured DOM implementa-
	      tion.

       getElementsByTagName
	      The DOM_Document_getElementsByTagName function performs  a  pre-
	      order  traversal	of the entire document and returns a DOM_Node-
	      List of the elements with	the name tagname in the	order in which
	      they were	encountered.

	      After  the DOM_NodeList object will no longer to be used it must
	      be freed with the	DOM_Document_destroyNodeList function  with  a
	      free_nodes  parameter of 0 (the nodes in this list should	not be
	      freed or all other references to them will be invalid).

RETURNS
       createElement
	      The new DOM_Element object or NULL if the	 operation  failed  in
	      which case DOM_Exception will be set appropriately.

       createDocumentFragment
	      An  empty	 DOM_DocumentFragment  object or NULL if the operation
	      failed in	which case DOM_Exception will be set appropriately.

       createTextNode
	      The new DOM_Text object or NULL of the operation failed in which
	      case DOM_Exception will be set appropriately.

       createComment
	      The  new	DOM_Comment  object or NULL of the operation failed in
	      which case DOM_Exception will be set appropriately.

       createCDATASection
	      The new DOM_CDATASection object or NULL of the operation	failed
	      in which case DOM_Exception is set appropriately.

       createProcessingInstruction
	      The  new	DOM_ProcessingInstruction object or NULL of the	opera-
	      tion failed in which case	DOM_Exception will  be	set  appropri-
	      ately.

       createAttribute
	      The new DOM_Attr object or NULL of the operation failed in which
	      case DOM_Exception will be set appropriately.

       createEntityReference
	      The new DOM_EntityReference object  or  NULL  of	the  operation
	      failed in	which case DOM_Exception will be set appropriately.

       getElementsByTagName
	      A	 new  DOM_NodeList  object containing pointers to the matching
	      DOM_Elements.

domc-0.8.0			  Sep 9, 2004		      DOM_Document(3m)

NAME | SYNOPSIS | DESCRIPTION | RETURNS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DOM_Document&sektion=3m&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help