--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/xmlsrv_plat/cxml_library_api/inc/nw_string_string.h Tue Aug 31 17:02:56 2010 +0300
@@ -0,0 +1,909 @@
+/*
+* 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
+
+#include <xml/cxml/cxml_proj.h>
+#include <xml/cxml/nw_string_char.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
+
+ @synopsis: Token to string.
+
+ @scope: public
+
+ @parameters:
+ [in] NW_Uint32 token
+ default
+
+ [in-out] NW_String_t* str
+ The string.
+
+ [in] NW_Uint32 encoding
+ default
+
+ @description: Token to string.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ String converted.
+
+ [NW_STAT_FAILURE]
+ Token not found in current dictionary.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Out of memory.
+
+ [NW_STAT_WBXML_ERROR_CHARSET_UNSUPPORTED]
+ Unsupported charset.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_tokenToString(NW_Uint32 token, NW_String_t* str, NW_Uint32 encoding);
+
+/* ----------------------------------------------------------------------- **
+ String manipulation functions
+** ----------------------------------------------------------------------- **/
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_copy
+
+ @synopsis: Copy string duplicating storage.
+
+ @scope: public
+
+ @parameters:
+ [out] NW_String_t* dest
+ The destination string.
+
+ [in] NW_String_t* source
+ The source string.
+
+ @description: If the source owns the storage (i.e. it can modify and/or
+ delete it) than performs a deep copy. This duplicates the
+ storage. Otherwise it performs a shallow copy.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ String copied.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+NW_Status_t
+NW_String_copy(NW_String_t* dest, NW_String_t* source);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_shallowCopy
+
+ @synopsis: Copies without duplicating storage.
+
+ @scope: public
+
+ @parameters:
+ [out] NW_String_t* dest
+ The destination string.
+
+ [in] NW_String_t* source
+ The source string.
+
+ @description: Performs a shallow copy. The storage is shared with
+ the copy, not duplicated.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ Always returns success.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_shallowCopy(NW_String_t* dest, NW_String_t* source);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_deepCopy
+
+ @synopsis: Copy string duplicating storage.
+
+ @scope: public
+
+ @parameters:
+ [out] NW_String_t* dest
+ The destination string.
+
+ [in] NW_String_t* source
+ The source string.
+
+ @description: Performs a deep copy. The storage is duplicated so it
+ is not shared with the original.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ String copied.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_deepCopy(NW_String_t* dest, NW_String_t* source);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_concatenate
+
+ @synopsis: Concatenates two strings together.
+
+ @scope: public
+
+ @parameters:
+ [in-out] NW_String_t* dest
+ The destination string.
+
+ [in] NW_String_t* source
+ The source string.
+
+ [in] NW_Uint32 encoding
+ Encoding both strings are assumed to have.
+
+ @description: Concatenated two strings together.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ String copied.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_concatenate(NW_String_t* dest, NW_String_t* source, NW_Uint32 encoding);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_findChar
+
+ @synopsis: Finds char in string.
+
+ @scope: public
+
+ @parameters:
+ [in] NW_String_t* string
+ The string.
+
+ [in] NW_Int32 character
+ Character to find.
+
+ @description: Find char in string.
+
+ @returns: NW_Byte*
+ Pointer to character if found, otherwise NULL.
+
+ ** ----------------------------------------------------------------------- **/
+NW_Byte*
+NW_String_findChar(NW_String_t* string, NW_Int32 character, NW_Uint32 encoding);
+
+
+/* ----------------------------------------------------------------------- **
+ Functions
+** ----------------------------------------------------------------------- **/
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_ucs2CharInit
+
+ @synopsis: Initialize UCS2 characters.
+
+ @scope: public
+
+ @parameters:
+ [out] NW_Ucs2** data
+ Allocated storage.
+
+ [in] NW_Uint32 length
+ The length.
+
+ @description: Allocates enough storage to hold the specified number
+ of characters.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ String copied.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+NW_Status_t
+NW_String_ucs2CharInit(NW_Ucs2** data, NW_Uint32 length);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_ucs2CharLength
+
+ @synopsis: Get character length.
+
+ @scope: public
+
+ @parameters:
+ [in] NW_Ucs2* data
+ Buffer to count.
+
+ @description: Get character length.
+
+ @returns: NW_Int32
+ Length of buffer in characters.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Int32
+NW_String_ucs2CharLength (NW_Ucs2* data);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_byteToUCS2Char
+
+ @synopsis: Convert byte to UCS2 characters.
+
+ @scope: public
+
+ @parameters:
+ [in] NW_Byte* b
+ default
+
+ [in] NW_Uint32 length
+ default
+
+ [out] NW_Ucs2** data
+ default
+
+ @description: Given an arbitrary NW_Byte array with no known character
+ encoding, convert it to a NW_Ucs2 string. Actually it
+ copies the bytes and assumes the source is UCS2 encoding.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ Bytes copied.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_byteToUCS2Char (NW_Byte* b, NW_Uint32 length, NW_Ucs2** data);
+
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_entityToUCS2Char
+
+ @synopsis: Convert entity to UCS2 character.
+
+ @scope: public
+
+ @parameters:
+ [in] NW_Uint32 entity
+ default
+
+ [out] NW_Ucs2** data
+ default
+
+ @description: Convert entity to UCS2 character.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ Bytes copied.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_entityToUCS2Char(NW_Uint32 entity, NW_Ucs2** data);
+
+/*
+ * Given an arbitrary NW_Byte array with no known character encoding,
+ * convert it to a NW_Ucs2 string.
+ *
+ */
+/* Not used. 8/14/01 */
+/*
+NW_Status_t
+NW_String_tokenToUCS2Char(NW_Uint32 token, NW_Ucs2** data);
+*/
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_stringToUCS2Char
+
+ @synopsis: default
+
+ @scope: public
+
+ @parameters:
+ [in] const string
+ default
+
+ [in] NW_Uint32 encoding
+ default
+
+ [out] NW_Ucs2 **data
+ default
+
+ @description: default
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ Bytes copied.
+
+ [NW_STAT_FAILURE]
+ No bytes to copy.
+
+ [NW_STAT_OUT_OF_MEMORY]
+ Ran out of memory.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_stringToUCS2Char(const NW_String_t* string, NW_Uint32 encoding, NW_Ucs2 **data);
+
+/** ----------------------------------------------------------------------- **
+ @function: NW_String_deleteStorage
+
+ @synopsis: Delete storage.
+
+ @scope: public
+
+ @parameters:
+ [in-out] NW_String_t* s
+ The string.
+
+ @description: Delete storage if user owns it otherwise does nothing.
+
+ @returns: NW_Status_t
+ Status of operation.
+
+ [NW_STAT_SUCCESS]
+ Always returns success.
+
+ ** ----------------------------------------------------------------------- **/
+IMPORT_C NW_Status_t
+NW_String_deleteStorage(NW_String_t* s);
+
+#ifdef __cplusplus
+} /*extern "C" { */
+#endif /* __cplusplus */
+
+#endif /* NW_STRING_STRING_H */