/*

* Copyright (c) 2000 - 2001 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/** ----------------------------------------------------------------------- **

    @package:     NW_DOM

    @synopsis:    default

    @description: default

 ** ----------------------------------------------------------------------- **/

#ifndef NW_DOM_NODE_H

#define NW_DOM_NODE_H

#include <xml/cxml/nw_tinytree.h>

#include <xml/cxml/nw_tinydom.h>

#include <xml/cxml/nw_string_string.h>

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

/** ----------------------------------------------------------------------- **

    @typedef:     NW_DOM_Node

    @synopsis:    Dom nodes are defined to be just tiny tree nodes.  

    @scope:       public

    @type:        NW_TinyTree_Node_t

    @description: Dom nodes are defined to be just tiny tree nodes.

                  This allows the Dom API to return the 32 bit pointers

                  it gets from the Tiny Tree and Tiny Dom APIs rather

                  than having to allocate any memory. This memory

                  savings comes at some cost, however: most Tiny Tree

                  API calls require a tree reference, and getting a tree

                  reference from an tiny dom node is an inefficient

                  operation (it requires a linear search of the node's

                  storage segment). We assume that this computation vs

                  memory tradeoff is worthwhile on small platforms.  One

                  alternative would be to require the tree as a

                  parameter to many Dom API calls, but this would be a

                  substantial departure from the standard Dom model.

 ** ----------------------------------------------------------------------- **/

typedef NW_TinyTree_Node_t NW_DOM_Node_t;

/* Specific node types used by the DOM API */

typedef NW_Uint16 NW_DOM_NodeType_t;

#define NW_DOM_ELEMENT_NODE                1

#define NW_DOM_TEXT_NODE                   2

#define NW_DOM_CDATA_SECTION_NODE          4 /* only for XML  */

#define NW_DOM_PROCESSING_INSTRUCTION_NODE 8

#define NW_DOM_COMMENT_NODE                16 /* only for XML  */

#define NW_DOM_DOCUMENT_NODE               32

typedef NW_DOM_Node_t NW_DOM_ElementNode_t;

/*typedef NW_DOM_Node_t NW_DOM_DocumentNode_t; */

/* Declared in nw_tiny_tree.h */

typedef NW_DOM_Node_t NW_DOM_TextNode_t;

typedef NW_DOM_Node_t NW_DOM_CommentNode_t;

typedef NW_DOM_Node_t NW_DOM_CDATASectionNode_t;

typedef NW_DOM_Node_t NW_DOM_ProcessingInstructionNode_t;

/*  ----------------------------------------------------------------------- **

    GENERAL NODE METHODS - applicable to all node types

    These methods will be repeated for other Node types also

 ** ----------------------------------------------------------------------- **/

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getNodeName

    @synopsis:    Get name of node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* elem

                  The node.

       [in-out] NW_String_t* name

                  The name of the node.

    @description: Get name of node.

    @returns:     NW_Status_t

                  Result of operation.

       [NW_STAT_SUCCESS]

                  Node name returned.

       [NW_STAT_DOM_NODE_TYPE_ERR]

                  Node type could not be determined.

       [NW_STAT_DOM_NO_STRING_RETURNED]

                  Node does not have name.

       [NW_STAT_DOM_NODE_TYPE_ERR]

                  It is not a NW_DOM_ELEMENT_NODE

       [NW_STAT_OUT_OF_MEMORY]

                  Ran out of memory trying to allocate string storage.

       [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]

                  Illegal character set.

       [NW_STAT_FAILURE]

                  String found but empty.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Status_t 

NW_DOM_Node_getNodeName(NW_DOM_Node_t* elem, NW_String_t* name); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getNodeType

    @synopsis:    Gets the type of DOM node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Gets the type of DOM node.

    @returns:     NW_DOM_NodeType_t

                  Node type or zero if not recognized node.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_NodeType_t

NW_DOM_Node_getNodeType(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getNodeToken

    @synopsis:    Gets the token associated with the node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Returns fully qualified node token. This includes the 

                  token, codepage and a attribute/element flag.

    @returns:     NW_Uint16

                  The 8 bit token and 8 bit codepage which includes an 

                  attribute/elent flag.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Uint16 

NW_DOM_Node_getNodeToken(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_isWBXML

    @synopsis:    Checks if the node was created by parsing WBXML content.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Checks if the node was created by parsing WBXML content.

    @returns:     NW_Bool

                  NW_TRUE if WBXML type, otherwise NW_FALSE.

 ** ----------------------------------------------------------------------- **/

NW_Bool 

NW_DOM_Node_isWBXML(NW_DOM_Node_t* node);

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getParentNode

    @synopsis:    Gets the parent of the node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Finds parent node of the given node. All nodes except 

                  DocumentNode have a parentNode.

    @returns:     NW_DOM_Node_t*

                  Parent or NULL if invalid operation or if parent node 

                  is a DocumentNode.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_Node_t* 

NW_DOM_Node_getParentNode(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getFirstChild

    @synopsis:    Finds the first child of the node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Returns valid values only for ELEMENT_NODE and DOCUMENT_NODE.

                  These are the only nodes that have children. For other nodes

                  the value is NULL.

    @returns:     NW_DOM_Node_t*

                  The first child of this node or NULL if the node has no child.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_Node_t* 

NW_DOM_Node_getFirstChild(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getLastChild

    @synopsis:    Finds the last child of the node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Returns valid values only for ELEMENT_NODE and DOCUMENT_NODE.

                  These are the only nodes that have children. For other nodes

                  the value is either NULL or 0.

    @returns:     NW_DOM_Node_t*

                  The last child of this node or NULL if the node has no child.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_Node_t* 

NW_DOM_Node_getLastChild(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_hasChildNodes

    @synopsis:    Checks if the node has any child nodes.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Returns valid values only for ELEMENT_NODE and DOCUMENT_NODE.

                  These are the only nodes that have children. For other nodes

                  the value is NULL.

    @returns:     NW_Bool

                  NW_TRUE if the node has child nodes, otherwise NW_FALSE.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Bool 

NW_DOM_Node_hasChildNodes(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getNextSibling

    @synopsis:    Gets the next sibling of the node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Gets the next sibling of the node.

    @returns:     NW_DOM_Node_t*

                  The node immediately following this node, NULL if there 

                  is no next sibling or this node is NULL.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_Node_t* 

NW_DOM_Node_getNextSibling(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getPreviousSibling

    @synopsis:    Gets the previous sibling of the node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Gets the previous sibling of the node.

    @returns:     NW_DOM_Node_t*

                  The node immediately preceding this node in the DOM tree,

                  NULL if there is no previous sibling or the node is NULL.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_Node_t* 

NW_DOM_Node_getPreviousSibling(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_getOwnerDocument

    @synopsis:    Gets the owner document node of this node.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

    @description: Gets the owner document node of this node.

    @returns:     NW_DOM_DocumentNode_t*

                  The owner document node (NW_DOM_DocumentNode_t) associated

                  with this node, NULL if the node is NULL or is a DocumentNode.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_DOM_DocumentNode_t* 

NW_DOM_Node_getOwnerDocument(NW_DOM_Node_t* node); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_insertBefore

    @synopsis:    Inserts newChild before the refChild.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_Node_t* node

                  The parent node.

       [in] NW_DOM_Node_t* newChild

                  The node to be inserted.

       [in] NW_DOM_Node_t* refChild

                  The node before which the newChild node should be inserted.

    @description: Inserts the newChild node before the existing refChild 

                  node; and if refChild is NULL, inserts it at the end of

                  the list of children.

    @returns:     NW_Status_t

                  Result of operation.

       [NW_STAT_SUCCESS]

                  Inserted successfully.

       [NW_STAT_BAD_INPUT_PARAM]

                  One of the input parameters was null.

       [NW_STAT_NOT_FOUND]

                  Reference child is not a child of given node.

       [NW_STAT_DOM_WRONG_DOC_ERR]

                  New child was created from a different document than the 

                  one that created the node.

       [NW_STAT_DOM_HEIRARCHY_REQ_ERR] 

                  Node is of the type that does not allow children of the 

                  type of newChild node.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Status_t

NW_DOM_Node_insertBefore(NW_DOM_Node_t* node, 

                         NW_DOM_Node_t* newChild, 

                         NW_DOM_Node_t* refChild);

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_replaceChild

    @synopsis:    Replaces oldChild with the newChild.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

       [in] NW_DOM_Node_t* newChild

                  The node that will replace oldChild.

       [in] NW_DOM_Node_t* oldChild

                  The node to be replaced.

    @description: Replaces oldChild with the newChild.

    @returns:     NW_Status_t

                  Result of operation.

       [NW_STAT_SUCCESS]

                  Child replaced.

       [NW_STAT_BAD_INPUT_PARAM]

                  Bad data.

       [NW_STAT_NOT_FOUND]

                  oldChild is not a child of given node.

       [NW_STAT_DOM_WRONG_DOC_ERR]

                  newChild was created from a different document than the 

                  one that created the node.

       [NW_STAT_DOM_HEIRARCHY_REQ_ERR]

                  Node is of the type that does not allow children of the 

                  type of newChild node.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Status_t

NW_DOM_Node_replaceChild(NW_DOM_Node_t* node, 

                         NW_DOM_Node_t* newChild, 

                         NW_DOM_Node_t* oldChild);

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_removeChild

    @synopsis:    Removes the oldChild node as a child of the node.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_Node_t* node

                  The parent node.

       [in] NW_DOM_Node_t* oldChild

                  The child node to be removed.

    @description: Removes the oldChild, and deletes the node and its child nodes.

    @returns:     NW_Status_t

                  Result of operation.

       [NW_STAT_SUCCESS]

                  Nodes deleted.

       [NW_STAT_BAD_INPUT_PARAM]

                  Bad data.

       [NW_STAT_NOT_FOUND]

                  oldChild is not a child of given node.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Status_t

NW_DOM_Node_removeChild(NW_DOM_Node_t* node, 

                        NW_DOM_Node_t* oldChild); 

/** ----------------------------------------------------------------------- **

    @function:    NW_DOM_Node_appendChild

    @synopsis:    Appends a new child.

    @scope:       public

    @parameters:

       [in] NW_DOM_Node_t* node

                  The node.

       [in] NW_DOM_Node_t* newChild

                  The node to be added.

    @description: Appends a new child.

    @returns:     NW_Status_t

                  Result of operation.

       [NW_STAT_SUCCESS]

                  Child node appended.

       [NW_STAT_BAD_INPUT_PARAM]

                  An input parameter was null.

       [NW_STAT_DOM_WRONG_DOC_ERR]

                  newChild was created from a different document than the 

                  one that created the node.

       [NW_STAT_DOM_HEIRARCHY_REQ_ERR]

                  Node is of the type that does not allow children of the type

                  of the newChild node.

 ** ----------------------------------------------------------------------- **/

IMPORT_C NW_Status_t

NW_DOM_Node_appendChild(NW_DOM_Node_t* node, 

                        NW_DOM_Node_t* newChild);

/** ----------------------------------------------------------------------- **

    @struct:      NW_DOM_NodeIterator

    @synopsis:    Iterator for walking node list.