/*
* Copyright (c) 2003 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:  Provides a single header for the cXML Parser
*
*/



#ifndef _CXML_ENTITY_H_
#define _CXML_ENTITY_H_

#include "cxml_proj.h"

#ifdef __cplusplus
extern "C" {
#endif

/* As per WBXML Format Specification (WAP-192-WBXML-20010725-a), 
 * section 5.8.4.3, the entities in WBXML can be represented either 
 * as String token (STR_I) or the ENTITY Token. The numeric character 
 * entities are reprented as ENTITY token and all other as STR_I.
 * 
 * In our implementation, all XML/HTML is represented as the numeric 
 * character entities. The numeric character entities is allocated four
 * bytes (NW_Uint32). The highest order byte will distinguish between the
 * different types of entities e.g. between predefined or character numeric 
 * entities.
 *
 */

  
// The maximum length of the entities can't exceed than 
// 9 bytes in current implementation. Provides safty
// for the infinite loop.
	
enum { CXML_ATTR_VAL_STR = 512,
       CXML_ENTITY_VAL_LEN =4
};

typedef struct CXML_EntitySet_Entry_s {
   CXML_Uint8* name;
   CXML_Ucs2 value;
}CXML_EntitySet_Entry_t;




/** ----------------------------------------------------------------------- **
    @function:    CXML_XML_Handle_entity
    @synopsis:    Resolve the entities.
    @scope:       public      

    @parameters: 
        [in] NW_XML_Reader_t* pT
                  

        [in] NW_XML_Reader_Interval_t* pI_entityData
                  Entity name 


        [out] NW_Uint32* entityVal
                       If it is Character hex entry, Character decimal entry or
                       Prefined entry then it contains the hex value of entity.
                       In case of Internal entities it is zero.
                        
		[out] CXML_Uint8** entityStr
                       In case of Internal Entities, it is string corresponding 
                       to the entity name defined in 
                       NW_XML_Reader_Interval_t* pI_entityData. 

        [out] NW_Bool* entityFound 
                       NW_TRUE: If valid type of entity is defined.
        [in] RPointerArray <CXML_Internal_Entity_t>  internalEntityList 
                       List of Internal Entities for search. This is
                       casted to (void*) to avoid c++ related error in
                       <e32std.h>

    @description:  * The following type of entities are handled
                 * 1) Character hex entry
                 * 2) Character decimal entry
                 * 3) Prefined entry
                 * 4) Internal Entities defined in the DTD.
                 *
                 * 
                 


    @returns:   
                  In case of file  related failures:  Error codes is returned defined in 
				                                      nwx_status.h
                  NW_STAT_FAILURE : For any general error and entity is not predefined 
                                    entity.
                  NW_STAT_SUCCESS: For success
 -----------------------------------------------------------------------------------**/

NW_Status_t CXML_XML_Handle_entity(NW_XML_Reader_t* pT,
								   NW_XML_Reader_Interval_t* pI_entityData,
								   NW_Uint32* entityVal,
                                   CXML_Uint8** entityStr,
								   NW_Bool* entityFound,
                                   void* internalEntityList);




NW_Status_t CXML_XML_Parser_Entity(NW_XML_Reader_t* pT,
							    NW_XML_Reader_Interval_t* I_entityData,
							    NW_Bool* entityFound);

/** ----------------------------------------------------------------------- **
    @function:    CXML_XML_Get_Entity
    @synopsis:    Converts the entity value from CXML_Uint32 to CXML_Byte string.
    @scope:       public      

    @parameters: 
        [in] entityVal
                  

        [out] CXML_Byte* entityStr
                  Entity value in the string.


        [out] CXML_Uint32* strLen
                       Length of the entity string. 
					   0: In case of error.

    @description: Converts the entity value from CXML_Uint32 to CXML_Byte string.

    @returns:   
                  In case of file  related failures:  Error codes is returned defined in 
				                                      nwx_status.h
                  NW_STAT_FAILURE : For any general error and entity is not predefined 
                                    entity.
                  NW_STAT_SUCCESS: For success
 -----------------------------------------------------------------------------------**/

IMPORT_C
NW_Status_t CXML_XML_Get_Entity(CXML_Uint32 entityVal,
								CXML_Byte* entityStr,
								CXML_Uint32* strLen);

#ifdef __cplusplus 
} // extern "C" {
#endif /* __cplusplus */

#endif //_CXML_ENTITY_H_