/*

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

#define NW_DOM_DOCUMENT_H

#include <xml/cxml/cxml_proj.h>

#include <xml/cxml/nw_dom_node.h>

#include <xml/cxml/nw_dom_text.h>

#include <xml/cxml/nw_dom_element.h>

#include <xml/cxml/nw_wbxml_dictionary.h>

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

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

    @function:    NW_DOM_DocumentNode_getPublicIdAsNumber

    @synopsis:    Gets the public id of the document as an integer.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* d

                  The document node.

    @description: Gets the public id of the document as an integer.

    @returns:     NW_Uint32

                  publicID or 0

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

IMPORT_C NW_Uint32 

NW_DOM_DocumentNode_getPublicIdAsNumber(NW_DOM_DocumentNode_t* d);

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

    @function:    NW_DOM_DocumentNode_getPublicId

    @synopsis:    Gets the publicid of the document as string (docType).

    @scope:       public      

    @parameters: 

       [in]  NW_DOM_DocumentNode_t* d

                  The document node.

       [out] NW_String_t* str

                  The public id as a string.

    @description: The document type declaration associated with this 

                  document is returned.

    @returns:     NW_Status_t 

                  Status of operation.

       [NW_STAT_DOM_NODE_TYPE_ERR]

                  Error reading node.

       [NW_STAT_SUCCESS]

                  Success.

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

IMPORT_C NW_Status_t 

NW_DOM_DocumentNode_getPublicId(NW_DOM_DocumentNode_t* d, 

                                NW_String_t* str);

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

    @function:    NW_DOM_DocumentNode_getVersion

    @synopsis:    Returns the version of the document, 

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

    @description: Returns the version of the document. Returns 0 if this

                  is not valid.

    @returns:     NW_Uint8 

                  Version number or 0.

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

IMPORT_C NW_Uint8 

NW_DOM_DocumentNode_getVersion(NW_DOM_DocumentNode_t* doc);

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

    @function:    NW_DOM_DocumentNode_getCharacterEncoding

    @synopsis:    Returns the supported encoding of the document.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

    @description: Returns the supported encoding of the document or 0 

                  for invalid document.

    @returns:     NW_Uint32  

                  Encoding or 0.

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

IMPORT_C NW_Uint32 

NW_DOM_DocumentNode_getCharacterEncoding(NW_DOM_DocumentNode_t* doc);

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

    @function:    NW_DOM_DocumentNode_getDocumentElement

    @synopsis:    Returns child node that is the root of this document

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

    @description: Returns child node that is the root of this document

    @returns:     NW_DOM_DocumentNode_t* 

                  Child node that is the root element of the document; 

                  NULL if doc is not a document node.

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

IMPORT_C NW_DOM_ElementNode_t* 

NW_DOM_DocumentNode_getDocumentElement(NW_DOM_DocumentNode_t* doc);

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

    @function:    NW_DOM_DocumentNode_getElementIteratorByTagName

    @synopsis:    Gets the handle to iterate over elements of a given name.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_String_t* tagName

                  Name of the element.

       [out] NW_DOM_NodeIterator_t* handle

                  Iterator to iterate over nodes of same name)

    @description: Gets the handle to iterate over elements of a given name.

    @returns:     NW_Status_t                  

                  Status of operation.

       [NW_STAT_SUCCESS] 

                  Success

       [NW_STAT_FAILURE] 

                  Failure

       [NW_STAT_DOM_NODE_TYPE_ERR]

                  Not NW_DOM_DOCUMENT_NODE.

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

NW_Status_t 

NW_DOM_DocumentNode_getElementIteratorByTagName(NW_DOM_DocumentNode_t* doc, 

                                                NW_String_t* tagName,

                                                NW_DOM_NodeIterator_t* handle);

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

    @function:   NW_DOM_DocumentNode_getElementIteratorByTagToken

    @synopsis:    Gets the iterator to iterate over elements of a given token.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_Uint16 token

                  Token of the element to be found.

       [out] NW_DOM_NodeIterator_t* handle

                  Iterator to iterate over nodes of same name.

    @description: Gets the iterator to iterate over elements of a given token.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS] 

                  Success

       [NW_STAT_DOM_NODE_TYPE_ERR]

                  Not NW_DOM_DOCUMENT_NODE.

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

NW_Status_t 

NW_DOM_DocumentNode_getElementIteratorByTagToken(NW_DOM_DocumentNode_t* doc, 

                                                 NW_Uint16 token,

                                                 NW_DOM_NodeIterator_t* handle);

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

    @function:    NW_DOM_DocumentNode_getDictionary

    @synopsis:    Returns dictionary used by this document   

    @scope:       public

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                 The document node.

    @description: Returns dictionary used by this document   

    @returns:     NW_WBXML_Dictionary_t*

                  Dictionary or null if not found.

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

IMPORT_C NW_WBXML_Dictionary_t* 

NW_DOM_DocumentNode_getDictionary(NW_DOM_DocumentNode_t* doc);

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

    @function:    NW_DOM_DocumentNode_createElementNode

    @synopsis:    Creates a new element with the given name.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_String_t* name

                  Name of the element to be created.

    @description: Creates a new element with the given name.

    @returns:     NW_DOM_ElementNode_t*                  

                  New element with the given name; NULL if doc is not a 

                  document node.

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

IMPORT_C NW_DOM_ElementNode_t* 

NW_DOM_DocumentNode_createElementNode(NW_DOM_DocumentNode_t* doc, NW_String_t* name);

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

    @function:   NW_DOM_DocumentNode_createElementNodeByToken

    @synopsis:    Creates a new element with the given token.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                 The document node.

       [in] NW_Uint16 token

                 Token of the element to be created.

    @description: Creates a new element with the given token. 

    @returns:     NW_DOM_ElementNode_t*  

                  New element with the given token; NULL if doc is not a 

                  document node or token is an invalid token.

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

IMPORT_C NW_DOM_ElementNode_t* 

NW_DOM_DocumentNode_createElementNodeByToken(

  NW_DOM_DocumentNode_t* doc, NW_Uint16 token);

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

    @function:    NW_DOM_DocumentNode_createTextNodeWithTextItem

    @synopsis:    Returns a pointer to the created Text Node.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_DOM_TextItem_t* data

                  The value for the new text node.

    @description: Returns a pointer to the created Text Node.

    @returns:     NW_DOM_TextNode_t*

                  New text node; NULL if if doc is not a document node.

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

IMPORT_C NW_DOM_TextNode_t* 

NW_DOM_DocumentNode_createTextNodeWithTextItem(

  NW_DOM_DocumentNode_t* doc, NW_DOM_TextItem_t* data);

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

    @function:    NW_DOM_DocumentNode_createTextNode

    @synopsis:    Creates a text node.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_String_t* data

                  The value for the new text node.

    @description: Creates a text node with the given data.

    @returns:     NW_DOM_TextNode_t*

                  New text node; NULL if if doc is not a document node.

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

IMPORT_C NW_DOM_TextNode_t* 

NW_DOM_DocumentNode_createTextNode(NW_DOM_DocumentNode_t* doc, NW_String_t* data);

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

    @function:     NW_DOM_DocumentNode_createCommentNode

    @synopsis:     Creates a comment node with the given data.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_String_t* data

                  Value for the new comment node.

    @description: Creates a comment node with the given data.

    @returns:     NW_DOM_CommentNode_t*

                  New comment node; NULL if doc is not a document node.

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

NW_DOM_CommentNode_t* 

NW_DOM_DocumentNode_createCommentNode(NW_DOM_DocumentNode_t* doc, 

                                      NW_String_t* data);

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

    @function:    NW_DOM_DocumentNode_createCDATASectionNode

    @synopsis:    Creates a CDATA section.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

      [in] NW_String_t* data

                  The value for the new CDATA section node.

    @description: Creates a CDATA section node with the given data.

    @returns:     NW_DOM_CDATASectionNode_t*

                  New CData section node; NULL if doc is not a document node.

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

NW_DOM_CDATASectionNode_t* 

NW_DOM_DocumentNode_createCDATASectionNode(NW_DOM_DocumentNode_t* doc, 

                                           NW_String_t* data);

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

    @function:    NW_DOM_DocumentNode_createProcessingInstructionNodeByAttrVal

    @synopsis:    Creates a processing instruction node.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_String_t* target

                  The target for the processing instruction.

       [in] NW_DOM_AttrVal_t* data

                  Data for the processing instruction.

    @description: Creates a processing instruction node with the given data.

                  In WBXML, a processing instruction node can have a combination 

                  of opaque, string, token, extension, and entity as the data.

    @returns:     NW_DOM_ProcessingInstructionNode_t*

                  New processing instruction node; NULL if this is a node 

                  type mismatch.

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

NW_DOM_ProcessingInstructionNode_t* 

NW_DOM_DocumentNode_createProcessingInstructionNodeByAttrVal(

 NW_DOM_DocumentNode_t* doc, NW_String_t* target, NW_DOM_AttrVal_t* data);

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

    @function:    NW_DOM_DocumentNode_createProcessingInstructionNodeByToken

    @synopsis:    Creates a processing instruction node.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_Uint16 token

                  Token identifying the target.

       [in] NW_DOM_AttrVal_t* data

                  Data for the processing instruction.

    @description: Creates a processing instruction node with the given data.

                  In WBXML, a processing instruction node can have a combination 

                  of opaque, string, token, extension, and entity as the data.

    @returns:     NW_DOM_ProcessingInstructionNode_t*

                  New processing instruction node; NULL if this is a node type 

                  mismatch.

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

NW_DOM_ProcessingInstructionNode_t* 

NW_DOM_DocumentNode_createProcessingInstructionNodeByToken(

  NW_DOM_DocumentNode_t* doc, NW_Uint16 token, NW_DOM_AttrVal_t* data);

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

    @function:    NW_DOM_DocumentNode_createProcessingInstructionNode

    @synopsis:    Creates a processing instruction node.

    @scope:       public      

    @parameters: 

       [in] NW_DOM_DocumentNode_t* doc

                  The document node.

       [in] NW_String_t* target

                  The target for the processing instruction.

       [in] NW_String_t* data

                  Data for the processing instruction.

    @description: Creates a processing instruction node with the given data.

    @returns:     NW_DOM_ProcessingInstructionNode_t*

                  New processing instruction node; NULL if doc is not a document 

                  node.

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

NW_DOM_ProcessingInstructionNode_t* 

NW_DOM_DocumentNode_createProcessingInstructionNode(

  NW_DOM_DocumentNode_t* doc, NW_String_t* target, NW_String_t* data);

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

    @struct:       NW_TinyDom_Handle

    @synopsis:    A handle to hold all the state required to build a tree.

    @scope:       public

    @variables:

       NW_WBXML_Parser_t wbxmlParser

                  WBXML parser

       NW_TinyDom_Parser_t tinyParser

                  Tiny parser

       NW_TinyDom_Tree_t tinyDOMTree

                  Tiny DOM tree

       NW_WBXML_Writer_t writer

                  WBXML writer

       NW_WBXML_Document_t document

                  WBXML document

    @description: A handle to hold all the state required to build a tree.

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

typedef struct NW_TinyDom_Handle_s{

  NW_WBXML_Parser_t   wbxmlParser;

  NW_TinyDom_Parser_t tinyParser;

  NW_TinyDom_Tree_t   tinyDOMTree;

  NW_WBXML_Writer_t writer;

  NW_WBXML_Document_t document;

} NW_TinyDom_Handle_t;

/* "Factory methods" that generate a dom tree and return the tree

 * root as a document node