/*

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

    @synopsis:    default

    @description: default

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

#ifndef NW_STRING_STRING_H

#define NW_STRING_STRING_H

#ifdef __cplusplus

extern "C"

{

#endif /* __cplusplus */

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

    @struct:      NW_String_String

    @synopsis:    The basic wbxml string type.

    @scope:       public

    @variables:

       NW_Uint32 length

                  In bytes.

       NW_Byte* storage

                  default

    @description: The basic wbxml string type.

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

typedef struct NW_String_String_s{

  NW_Uint32 length;

  NW_Byte* storage;

}NW_String_String_t;

/* Deprecated - Left in for backward compatibility */

typedef struct NW_String_String_s NW_String_t;

typedef struct NW_String_String_s NW_String_UCS2String_t;

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

    @function:    NW_String_new

    @synopsis:    Consructor.

    @scope:       public

    @description: Constructor.

    @returns:     NW_String_t*

                  New string or NULL if out of memory.

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

IMPORT_C NW_String_t*

NW_String_new (void);

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

    @function:    NW_String_initialize

    @synopsis:    Initialize.

    @scope:       public

    @parameters:

       [in] NW_String_t* string

                  The string.

       [in] void* storage

                  The storage.

       [in] NW_Uint32 encoding

                  The encoding.

    @description: Initialize the string by assigning length, encoding 

                  and storage. Note that the length is calculated.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  String initialized.

       [NW_STAT_FAILURE]

                  String not initialized.

       [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]

                  Unsupported charset.

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

IMPORT_C NW_Status_t 

NW_String_initialize (NW_String_t* string, void *storage, NW_Uint32 encoding);

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

    @function:    NW_String_delete

    @synopsis:    Delete.

    @scope:       public

    @parameters:

       [in-out] NW_String_t* string

                  The string.

    @description: Freeing a string may not free the storage. String storage 

                  is complicated by the fact that it can be allocated outside 

                  the bounds of the parser. If so, it is not freed here.

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

IMPORT_C void 

NW_String_delete(NW_String_t* string);

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

    @function:    NW_String_getByteCount

    @synopsis:    Returns number of bytes in the string including NULL 

                  terminator.

    @scope:       public

    @parameters:

       [in] NW_String_t* string

                  The string.

    @description: Returns number of bytes in the string including NULL 

                  terminator.

    @returns:     NW_Uint16

                  Length in bytes.

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

IMPORT_C NW_Uint32 

NW_String_getByteCount (NW_String_t* string);

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

    @function:    NW_String_getCharCount

    @synopsis:    Returns number of characters in the string excluding NULL 

                  terminator.

    @scope:       public

    @parameters:

       [in] NW_String_t* string

                  The string.

       [in] NW_Uint32 encoding

                  The encoding.

    @description: Returns number of characters in the string excluding NULL 

                  terminator.

    @returns:     NW_Uint16

                  Length of string in characters.

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

IMPORT_C NW_Uint16 

NW_String_getCharCount(NW_String_t* string, NW_Uint32 encoding);

/* 

 * The following function is a duplication of NW_String_getByteCount to

 * handle big files.  For not affecting the components other than

 * browser, this function is only called inside the browser.).

 *

 * INSTEAD OF CALLING NW_String_getByteCount, ALL THE BROWSER CODES SHOULD

 * CALL THIS DUPLICATE FUNCTION TO GET CHARACTER COUNTS.

 * 

 */

IMPORT_C NW_Uint32 

NW_String_getCharCount32(NW_String_t* string, NW_Uint32 encoding);

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

    @function:    NW_String_getStorage

    @synopsis:    Returns NULL or valid storage.

    @scope:       public

    @parameters:

       [in] NW_String_t* str

                  The string.

    @description: Returns the storage occupied by the string (in bytes).

    @returns:     NW_Byte*

                  String storage. 

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

IMPORT_C NW_Byte*

NW_String_getStorage(NW_String_t* str);

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

    @function:    NW_String_equals

    @synopsis:    Determines if strings are equal.

    @scope:       public

    @parameters:

       [in] const NW_String_t* string1

                  The string.

       [in] const NW_String_t* string2

                  The other string.

    @description: This function assumes the encoding of each string is 

                  the same. It does not attempt to convert strings of 

                  different encodings because encoding is regarded as 

                  implicit for XML strings. NOte that if both string 

                  pointers are NULL thay are considered unequal. 

    @returns:     NW_Int32

                  1 if the strings are equal; otherwise 0.

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

IMPORT_C NW_Int32 

NW_String_equals(const NW_String_t* string1, const NW_String_t* string2);

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

    @function:    NW_String_getUserOwnsStorage

    @synopsis:    Get user owns storage flag.

    @scope:       public

    @parameters:

       [in] NW_String_t* s

                  The string.

    @description: Get user owns storage flag. If the user owns the storage

                  it means that this string is the sole user of the storage

                  and can delete it when done.

    @returns:     NW_Bool

                  NW_TRUE if user owns storage, otherwise NW_FALSE.

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

IMPORT_C NW_Bool

NW_String_getUserOwnsStorage(NW_String_t* s);

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

    @function:    NW_String_setUserOwnsStorage

    @synopsis:    Set user owns storage flag.

    @scope:       public

    @parameters:

       [in-out] NW_String_t* s

                  The string.

    @description: Set user owns storage flag. (see NW_String_getUserOwnsStorage)

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Always returns success.

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

IMPORT_C NW_Status_t

NW_String_setUserOwnsStorage(NW_String_t* s);

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

    @function:    NW_String_clearUserOwnsStorage

    @synopsis:    Clear user owns storage flag.

    @scope:       public

    @parameters:

       [in-out] NW_String_t* s

                  The string.

    @description: Clear user owns storage flag. This means that someone

                  else may own the storage.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  Always returns success.

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

IMPORT_C NW_Status_t

NW_String_clearUserOwnsStorage(NW_String_t* s);

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

   Conversion routines   

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

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

    @function:    NW_String_stringToUCS2

    @synopsis:    Convert string to UCS2.

    @scope:       public

    @parameters:

       [out] NW_String_UCS2String_t** u

                  The converted string.

       [in] NW_String_t* string

                  The string to convert.

       [in] NW_Uint32 encoding

                  The encoding of the string to be converted

    @description: Converts a string of a given encoding to ucs2_char.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  String converted.

       [NW_STAT_FAILURE]

                  String not converted.

       [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]

                  Unsupported charset.

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

NW_Status_t 

NW_String_stringToUCS2(NW_String_UCS2String_t** u, NW_String_t* string, NW_Uint32 encoding);

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

    @function:    NW_String_UCS2BuffToString

    @synopsis:    Convert UCS2 buffer to string.

    @scope:       public

    @parameters:

       [in] NW_String_UCS2Buff_t* u

                  Source of data to convert.

       [out] NW_String_t* string

                  The converted string.

       [in] NW_Uint32 encoding

                  default

    @description: Convert UCS2 buffer to string.

    @returns:     NW_Status_t

                  Status of operation.

       [NW_STAT_SUCCESS]

                  String converted.

       [NW_STAT_OUT_OFMEMORY]

                  Out of memory.

       [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]

                  Unsupported charset.

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

IMPORT_C NW_Status_t 

NW_String_UCS2BuffToString(NW_String_UCS2Buff_t* u, NW_String_t* string, NW_Uint32 encoding);

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

    @function:    NW_String_stringToUCS2Buff

    @synopsis:    Convert string to UCS2 buffer.

    @scope:       public

    @parameters:

       [in] NW_String_t* string

                  The string.

       [in] NW_Uint32 encoding

                  Initial encoding.

    @description: Convert a NW_String_t (in any of the supported character

                  set encodings) to a UCS2Buff string. Caller is responsible

                  for freeing the pointer returned by this function. Returned

                  array is null-terminated.

    @returns:     NW_String_UCS2Buff_t* 

                  USC2 buffer or NULL if it fails.

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

NW_String_UCS2Buff_t* 

NW_String_stringToUCS2Buff(NW_String_t* string, NW_Uint32 encoding);

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

    @function:    NW_String_ucs2CharToString

    @synopsis:    Convert UCS2 characters to string.

    @scope:       public

    @parameters:

       [in-out] NW_String_t* string

                  The string.

       [in] NW_Ucs2* u

                  The characters to convert.

       [in] NW_Uint32 encoding

                  Target encoding.

    @description: Convert UCS2 characters to string.

    @returns:     NW_Status_t

                  The status of the operation.

       [NW_STAT_SUCCESS]

                  String filled with chars.

       [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]

                  Unsupported encoding.

       [NW_STAT_OUT_OF_MEMORY]

                  String storage could not be allocated.

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

IMPORT_C NW_Status_t 

NW_String_ucs2CharToString (NW_String_t* string, NW_Ucs2* u, NW_Uint32 encoding);

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

    @function:    NW_String_entityToString

    @synopsis:    Convert entity to string.

    @scope:       public

    @parameters:

       [in] NW_Uint32 entity

                  default

       [in-out] NW_String_t* str

                  The string.

       [in] NW_Uint32 encoding

                  Target encoding.

    @description: Convert entity to string.

    @returns:     NW_Status_t

                  The status of the operation.

       [NW_STAT_SUCCESS]

                  String initialized from entity.

       [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]

                  Unsupported encoding.

       [NW_STAT_OUT_OF_MEMORY]

                  String storage could not be allocated.

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

IMPORT_C NW_Status_t 

NW_String_entityToString(NW_Uint32 entity, NW_String_t* str, NW_Uint32 encoding);

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

    @function:    NW_String_byteToString

    @synopsis:    Convert byte array to string.

    @scope:       public

    @parameters:

       [in] NW_Byte* s

                  Bytes to initialize string with.

       [in-out] NW_String_t* str

                  The string.

       [in] NW_Uint32 encoding

                  The encoding.

    @description: Convert byte to string.

    @returns:     NW_Status_t

                  The status of the operation.

       [NW_STAT_SUCCESS]

                  String initialized from bytes.

       [NW_STAT_FAILURE]

                  String not initialized.

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

NW_Status_t 

NW_String_byteToString(NW_Byte* s, NW_String_t* str, NW_Uint32 encoding);

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

    @function:    NW_String_tokenToString