/*

* 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_TinyTree

    @synopsis:    default

    @description: default

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

#ifndef NW_TINY_TREE_H

#define NW_TINY_TREE_H

#include <xml/cxml/cxml_proj.h>

#include <xml/cxml/nw_tinytree_treevector.h>

#include <xml/cxml/nw_tinytree_ebuffer.h>

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

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

   Tiny tree definitions   

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

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

    @typedef:     NW_TinyTree_Index

    @synopsis:    An index into the node array.

    @scope:       public

    @type:        CXML_Vector_Metric_t

    @description: An index into the node array.

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

typedef CXML_Vector_Metric_t NW_TinyTree_Index_t; 

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

    @typedef:     NW_TinyTree_Offset

    @synopsis:    An offset into the source buffer.

    @scope:       public

    @type:        NW_Uint32

    @description: An offset into the source buffer.

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

/*

typedef NW_Uint32 NW_TinyTree_Offset_t;

*/

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

   Node flags  

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

#define TNODE_FLAG_LASTSIBLING   0x8000 /* My next_sibling points to parent */

#define TNODE_FLAG_ROOT          0x4000 /* I'm the tree root */

#define TNODE_FLAG_TREE          0x2000 /* I'm a special sentinel node marking

                                           the beginning of a segment */

#define TNODE_FLAG_ORPHAN        0x1000 /* A node not part of a tree */

#define TNODE_USR_FLAGS          0x0FFF  /* 12 bits available to tree user */

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

    @struct:      NW_TinyTree_Node

    @synopsis:    Tiny tree node structure.

    @scope:       public

    @variables:

       NW_Uint16 flags

                  Node description flags.

       NW_TinyTree_Offset_t source_offset

                  Offset of node data into original buffer.

       NW_TinyTree_Index_t first_child

                  Index of first child of this node.

       NW_TinyTree_Index_t next_sibling

                  Index of next sibling of this node.

    @description: Tiny tree node structure.

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

typedef struct NW_TinyTree_Node_s NW_TinyTree_Node_t;

struct NW_TinyTree_Node_s {

  NW_Uint16 flags;

  NW_TinyTree_Offset_t source_offset;

  NW_TinyTree_Node_t* first_child;

  NW_TinyTree_Node_t* next_sibling;

  NW_TinyTree_t* tree;

  NW_Uint16 token;

};

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

    @struct:      NW_TinyTree_TinyTree

    @synopsis:    Tree structure. 

    @scope:       public

    @variables:

       NW_TinyTree_TreeVector_t* tree

                  Node data.

       NW_TinyTree_Index_t root_index

                  Node data.

       NW_TinyTree_EBuffer_t* ebuffer

                  Buffer data.

       void* context

                  Context accessible from tree (typically the parser that 

                  builds and reads the tree).

    @description: Tree structure. Provides access points for root 

                  and buffer data.

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

typedef struct NW_TinyTree_TinyTree_s {

  /* Node data */

  NW_TinyTree_TreeVector_t* tree;

  NW_TinyTree_Index_t root_index;

  /* Buffer data */

  NW_TinyTree_EBuffer_t* ebuffer;

  /* Context accessible from tree (typically the parser that builds and reads the tree) */

  void* context;

}NW_TinyTree_TinyTree_t;

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

    @struct:      NW_TinyTree_TreeNode

    @synopsis:    A sentinel node that resides at the start of 

                  every tree vector segment.

    @scope:       public

    @variables:

       NW_Uint16 flags

                  Node description flags.

       NW_TinyTree_t* tree

                  The tree.

    @description: A special sentinel node that resides at the start of 

                  every tree vector segment, pointing to the tree itself.

                  This is used by applications like the DOM api that do 

                  not have a reference to the tree when operating on nodes.

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

typedef struct NW_TinyTree_TreeNode_s{

  NW_Uint16 flags;

  NW_TinyTree_t* tree;

}NW_TinyTree_TreeNode_t;

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

    Public tiny tree API  

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

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

    @function:    NW_TinyTree_new

    @synopsis:    Initialize a tree.

    @scope:       public

    @description: Initialize a tree.Allocates memory and initializes variables.

    @returns:     NW_TinyTree_TinyTree_t*

                  The new tree.

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

NW_TinyTree_t*

NW_TinyTree_new();

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

    @function:    NW_TinyTree_construct

    @synopsis:    Constructor.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_TinyTree_t* tree

                  The tiny tree.

       [in] CXML_Vector_Metric_t initialNodeCount

                  Initiali size of vector of nodes.

       [in] void* buffer

                  Link buffer into ebuffer.

       [in] NW_TinyTree_Offset_t buffsz

                  Size of block of data.

       [in] void* context

                  Context (i.e. parser).

       [in] NW_Bool freeBuff

                  Buffer deallocation flag.

    @description: Constructor. Adds data to the structure returned 

                  by NW_TinyTree_new.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Tree created.

       [NW_STAT_FAILURE]

                  Out of memory or general error.

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

NW_Status_t

NW_TinyTree_construct(NW_TinyTree_t* tree,

                      CXML_Vector_Metric_t initialNodeCount,

                      void* buffer,

                      NW_TinyTree_Offset_t buffsz,

                      void* context,

                      NW_Bool freeBuff);

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

    @function:    NW_TinyTree_destruct

    @synopsis:    Clean up tree resources.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  default

    @description: Clean up tree resources.

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

void

NW_TinyTree_destruct(NW_TinyTree_t* tree);

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

    @function:    NW_TinyTree_createNode

    @synopsis:    Create an unattached node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Offset_t offset

                  Offset into buffer.

    @description: Create an unattached node which references the source 

                  buffer at offset.

    @returns:     NW_TinyTree_Node_t*

                  Node or NULL if memory could not be allocated.

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

NW_TinyTree_Node_t*

NW_TinyTree_createNode(NW_TinyTree_t* tree, 

                       NW_TinyTree_Offset_t offset);

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

    @function:    NW_TinyTree_setRoot

    @synopsis:    Create a root node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Offset_t offset

                  Offset into buffer.

    @description: Create a root node which references the source buffer 

                  at offset. Returns a pointer to the root node.

    @returns:     NW_TinyTree_Node_t*

                  Pointer to the root node.

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

NW_TinyTree_Node_t*

NW_TinyTree_setRoot(NW_TinyTree_t* tree, 

                    NW_TinyTree_Offset_t offset);

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

    @function:    NW_TinyTree_getRoot

    @synopsis:    Get the root node of the tree.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

    @description: Get the root node of the tree.

    @returns:     NW_TinyTree_Node_t*

                  The root node or NULL if it is not valid.

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

NW_TinyTree_Node_t*

NW_TinyTree_getRoot(NW_TinyTree_t* tree);

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

    @function:    NW_TinyTree_findNextSibling

    @synopsis:    Find the next sibling of a node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

    @description: Find the next sibling of a node.

    @returns:     NW_TinyTree_Node_t*

                  The next sibling node or NULL if it is not valid.

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

NW_TinyTree_Node_t*

NW_TinyTree_findNextSibling(NW_TinyTree_Node_t* node);

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

    @function:    NW_TinyTree_findLastSibling

    @synopsis:    Find last sibling of a node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

    @description: Find last sibling of a node.

    @returns:     NW_TinyTree_Node_t*

                  The last sibling node or NULL if it is not valid.

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

NW_TinyTree_Node_t*

NW_TinyTree_findLastSibling(NW_TinyTree_Node_t* node);

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

    @function:    NW_TinyTree_findPreviousSibling

    @synopsis:    Find the previous sibling of a node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

    @description: Find the previous sibling of a node.

    @returns:     NW_TinyTree_Node_t*

                  The previous sibling node or NULL if it is not valid.

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

NW_TinyTree_Node_t*

NW_TinyTree_findPreviousSibling(NW_TinyTree_Node_t* node);

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

    @function:    NW_TinyTree_findFirstChild

    @synopsis:    Find the first child of a node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

    @description: Find the first child of a node.

    @returns:     NW_TinyTree_Node_t*

                  The first child node or NULL if it is not valid.

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

NW_TinyTree_Node_t*

NW_TinyTree_findFirstChild(NW_TinyTree_Node_t* node);

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

    @function:    NW_TinyTree_findLastChild

    @synopsis:    Find a node's last child.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

    @description: Find a node's last child.

    @returns:     NW_TinyTree_Node_t*

                  The last child node or NULL if it is not valid.

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

NW_TinyTree_Node_t*

NW_TinyTree_findLastChild(NW_TinyTree_Node_t* node);

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

    @function:    NW_TinyTree_findParent

    @synopsis:    Find a node's parent.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

    @description: Find a node's parent.

    @returns:     NW_TinyTree_Node_t*

                  The parent node of this node or NULL if it is not valid.

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

NW_TinyTree_Node_t* 

NW_TinyTree_findParent(NW_TinyTree_Node_t* node);

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

    @function:    NW_TinyTree_attachAfter

    @synopsis:    Attach a sibling after a node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node

                  The reference node.

       [in] NW_TinyTree_Node_t* sibling

                  Sibling node to attach.

    @description: Attach a sibling after a node.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Always returns success.

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

NW_Status_t 

NW_TinyTree_attachAfter(NW_TinyTree_Node_t* node, 

                        NW_TinyTree_Node_t* sibling);

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

    @function:    NW_TinyTree_attachBefore

    @synopsis:    Attach a sibling before another node.

    @scope:       public

    @parameters:

       [in] NW_TinyTree_t* tree

                  The tiny tree.

       [in] NW_TinyTree_Node_t* node