/*

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

#define NW_DOM_ATTRIBUTE_H

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

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

    @struct:      NW_DOM_AttributeListIterator

    @synopsis:    Iterates over the list of attributes of an element.

    @scope:       public

    @variables:

       NW_TinyDom_AttrListHandle_t attrListHandle

                  this object

       NW_TinyTree_Node_t* node

                  default

    @description:

                  The NW_DOM_AttributeListIterator_t data type can be

                  thought of as a replacement for the NamedNodeMap

                  structure specified in the W3C DOM specification. In

                  this specification, performing getAttributes on an

                  element results in getting a readonly NamedNodeMap

                  structure, whereas in WAP DOM it results in getting a

                  pointer to the NW_DOM_AttributeListIterator_t data

                  type.

                  The main difference between the two is that

                  NamedNodeMap allows you to get items using an index,

                  whereas using NW_DOM_AttributeListIterator_t you can

                  iterate over a list of attributes.  Other

                  functionality available in NamedNodeMap, such as

                  getNamedItem, setNamedItem, removeNamedItem, is

                  already present in the APIs defined for an

                  ElementNode.

                  NW_DOM_AttributeListIterator_t is used to iterate over

                  the list of attributes of an element. Note that when a

                  tree is built by the parser, only the first attribute

                  of an element has a node of its own.  For example,

                  <card id="card1" title="example"> has 2 attributes,

                  but only 1 node is allocated, pointing to the first

                  attribute start. In a read-write tree, each added

                  attribute gets a new node.

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

typedef struct NW_DOM_AttributeListIterator_s {

  /* Used to iterate over the original attributes */

  NW_TinyDom_AttrListHandle_t attrListHandle;

  /* Used to iterate over added attributes */

  NW_TinyTree_Node_t* node;

}NW_DOM_AttributeListIterator_t;

/* An attribute value in the DOM API */

typedef NW_TinyDom_AttrVal_t NW_DOM_AttrVal_t;

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

    @struct:      NW_DOM_AttributeHandle

    @synopsis:    default

    @scope:       public

    @variables:

       NW_TinyDom_AttributeHandle_t tinyHandle

                  The attribute handle.

       NW_TinyTree_Node_t* node

                  default

    @description: NW_DOM_AttributeHandle_t is used as an extension to

                  support WBXML attributes. In WBXML, attibutes can

                  consist of an attribute start token and several value

                  components. Moreover, an attribute start token can

                  represent either the attribute name, the attribute

                  name and the initial part of the value (a so-called

                  value prefix), or the complete attribute name and

                  value.This type has methods that return these elements

                  and allow iteration over the values.  Attribute

                  handles are also supported for XML documents since

                  applications may wish to use the attribute list

                  iterator mechanism for these documents. Attribute list

                  iterators return attribute handles.

                  NW_DOM_AttributeHandle is used to iterate over the

                 values of an attribute.

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

typedef struct NW_DOM_AttributeHandle_s{

  NW_TinyDom_AttributeHandle_t tinyHandle;

  NW_TinyTree_Node_t* node;

}NW_DOM_AttributeHandle_t;

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

    @function:    NW_DOM_AttributeListIterator_new

    @synopsis:    Constructor.

    @scope:       public

    @description: Allocates memory for NW_DOM_AttributeListIterator.

                  Returns NULL in case of failure to do so.

    @returns:     NW_DOM_AttributeListIterator_t*

                  New iterator.

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

NW_DOM_AttributeListIterator_t*

NW_DOM_AttributeListIterator_new(void);

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

    @function:    NW_DOM_AttributeListIterator_initialize

    @synopsis:    Initialize the iterator.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeListIterator_t* handle

                  The attribute handle.

    @description: Initialize the iterator.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Always returns this value.

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

NW_Status_t

NW_DOM_AttributeListIterator_initialize(NW_DOM_AttributeListIterator_t* handle);

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

    @function:    NW_DOM_AttributeListIterator_delete

    @synopsis:    Delete the iterator.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeListIterator_t* handle

                  The attribute handle.

    @description: Delete the iterator.

    @returns:     NW_Status_t

                  Status of operation.

      [NW_STAT_SUCCESS]

                  Always returns this value.

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

NW_Status_t

NW_DOM_AttributeListIterator_delete(NW_DOM_AttributeListIterator_t* handle);

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

    @function:    NW_DOM_AttributeListIterator_getNextAttribute

    @synopsis:    Get next attribute.

    @scope:       public

    @parameters:

       [in] NW_DOM_AttributeListIterator_t* listIterator

                  Iterator for the attribute list.

       [out] NW_DOM_AttributeHandle_t* attributeHandle

                  A handle for an attribute.

    @description: Get next attribute.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_DOM_BAD_INPUT_PARAM_ERR]

                  Error on input.

       [NW_STAT_WBXML_ITERATE_MORE]

                  More attributes available.

       [NW_STAT_WBXML_ITERATE_DONE]

                  No more attributes available.

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

IMPORT_C NW_Status_t

NW_DOM_AttributeListIterator_getNextAttribute(NW_DOM_AttributeListIterator_t* listIterator, 

                                              NW_DOM_AttributeHandle_t* attributeHandle);

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

    @function:    NW_DOM_AttributeHandle_new

    @synopsis:    Create new handle.

    @scope:       public

    @description: Create new handle.

    @returns:     NW_DOM_AttributeHandle_t*

                  Allocates memory for new handle.

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

NW_DOM_AttributeHandle_t*

NW_DOM_AttributeHandle_new(void);

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

    @function:    NW_DOM_AttributeHandle_delete

    @synopsis:    Delete handle.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

    @description: Delete handle.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STATUS_SUCCESS]

                  Always returns NW_STATUS_SUCCESS.

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

NW_Status_t

NW_DOM_AttributeHandle_delete(NW_DOM_AttributeHandle_t* handle);

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

    @function:    NW_DOM_AttributeHandle_initWithNode

    @synopsis:    Initializes and Attribute Handle with an attribute node.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [in] NW_TinyDom_Parser_t* parser

                  Parser to assign.

       [in] NW_TinyTree_Node_t* node

                  Node to attach to handle.

    @description: Initializes and Attribute Handle with an attribute node.

                  Note that only some attributes have nodes of their own.

                  Such attributes are initilized by this method.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Always returned.

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

NW_Status_t

NW_DOM_AttributeHandle_initWithNode(NW_DOM_AttributeHandle_t* handle,

                                    NW_TinyDom_Parser_t* parser,

                                    NW_TinyTree_Node_t* node);

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

    @function:    NW_DOM_AttributeHandle_initWithOffset

    @synopsis:    Initializes and Attribute Handle with a offset.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [in] NW_TinyDom_Parser_t* parser

                  Parser to use.

       [in] NW_TinyTree_Offset_t offset

                  Offset to use.

    @description: Initializes and Attribute Handle with a offset.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Always returned.

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

NW_Status_t

NW_DOM_AttributeHandle_initWithOffset(NW_DOM_AttributeHandle_t* handle,

                                      NW_TinyDom_Parser_t* parser,

                                      NW_TinyTree_Offset_t offset);

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

    @function:    NW_DOM_AttributeHandle_initWithStartToken

    @synopsis:    Initializes an Attribute Handle with a WBXML start token.

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [in] NW_TinyDom_Parser_t* parser

                  Parser to use.

       [in] NW_Uint16 token

                  The attribute start token with page.

    @description: Initializes an Attribute Handle with WBXML start token.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Success

       [NW_STAT_OUT_OF_MEMORY]

                  Out of memory.

       [NW_STAT_FAILURE]

                  Failure

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

IMPORT_C NW_Status_t

NW_DOM_AttributeHandle_initWithStartToken(NW_DOM_AttributeHandle_t* handle,

                                          NW_TinyDom_Parser_t* parser,

                                          NW_Uint16 fqToken);

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

    @function:    NW_DOM_AttributeHandle_addVal

    @synopsis:    Appends an attribute value to an existing attribute handle

    @scope:       public

    @parameters:

       [in-out] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [in] NW_DOM_AttrVal_t* value

                  The attribute value to append to handle

    @description: Appends an attribute value to an existing attribute handle

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Success

       [NW_STAT_OUT_OF_MEMORY]

                  Out of memory.

       [NW_STAT_FAILURE]

                  Failure

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

IMPORT_C NW_Status_t

NW_DOM_AttributeHandle_addVal(NW_DOM_AttributeHandle_t* handle,

                              NW_DOM_AttrVal_t* value);

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

    @function:    NW_DOM_AttributeHandle_getName

    @synopsis:    Gets attribute name.

    @scope:       public

    @parameters:

       [in] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [out] NW_String_t* name

                  Attribute name without prefix.

    @description: Returns the attribute name (without prefix if any)

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Name returned.

       [NW_STAT_OUT_OF_MEMORY]

                  Ran out of memory.

       [NW_STAT_DOM_NO_STRING_RETURNED]

                  Name not found.

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

IMPORT_C NW_Status_t

NW_DOM_AttributeHandle_getName(NW_DOM_AttributeHandle_t* handle, 

                               NW_String_t* name);

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

    @function:    NW_DOM_AttributeHandle_getToken

    @synopsis:    Gets the token for the Attribute.

    @scope:       public

    @parameters:

       [in] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

    @description: Returns the token for the Attribute.

    @returns:     An attribute start token represented as two bytes: the

                  high order 8 bits represent the code page, the remaining

                  bits represent the token; returns 0 if the handle is

                  invalid or the document is not a WBXML document.

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

IMPORT_C NW_Uint16 

NW_DOM_AttributeHandle_getToken(NW_DOM_AttributeHandle_t* handle);

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

    @function:    NW_DOM_AttributeHandle_getValuePrefix

    @synopsis:    Gets attribute prefix.

    @scope:       public

    @parameters:

       [in] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [out] NW_String_t* prefix

                  Value prefix for the attribute.

    @description: Returns the attribute prefix (for e.g. href="http://"

                  will return "http://". This is a WBXML-specific extension.

                  Behavior is undefined for non-WBXML attributes.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Got prefix.

       [NW_STAT_DOM_NO_VALUE_PREFIX]

                  Error

       [NW_STAT_OUT_OF_MEMORY]

                  Error

       [NW_STAT_DOM_NO_STRING_RETURNED]

                  Error

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

IMPORT_C NW_Status_t

NW_DOM_AttributeHandle_getValuePrefix(NW_DOM_AttributeHandle_t* handle, 

                                      NW_String_t* prefix);

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

    @function:    NW_DOM_AttributeHandle_getNameWithPrefix

    @synopsis:    Gets the attribute name.

    @scope:       public

    @parameters:

       [in] NW_DOM_AttributeHandle_t* handle

                  The attribute handle.

       [out] NW_String_t* name

                  Attribute name.

    @description: Returns the attribute name (with prefix if any).

                  This is a WBXML-specific extension. Behavior is undefined

                  for non-WBXML attributes.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Name returned.

       [NW_STAT_DOM_NO_STRING_RETURNED]

                  Error

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