--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/webengine/wmlengine/src/utils/include/nw_nvpair.h Wed Sep 01 12:28:30 2010 +0100
@@ -0,0 +1,264 @@
+/*
+* 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:
+*
+*/
+
+#ifndef NW_NVPAIR_H
+#define NW_NVPAIR_H
+
+/*
+** Includes
+*/
+#include "nwx_defs.h"
+#include "BrsrStatusCodes.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Identifier validation according WMLScript 6.1.6 */
+NW_Bool NW_CheckName(const NW_Ucs2* name);
+
+/*
+ Description:
+ The NW_NVPair_t abstract data type is for storing name value string
+ pairs. It is implemented to be created and accessed
+ sequencially, and to use as little memory as possible. A typical
+ calling sequence is:
+
+
+ Typical calling sequence to create and populate an object:
+ postFields = NW_NVPair_New();
+ while () {
+ status = NW_NVPair_CalSize(postFields, name, value);
+ }
+ status = NW_NVPair_AllocStorage( postFields );
+
+ while () {
+ status = NW_NVPair_Add(postFields, name, value);
+ }
+
+ (void) NW_NVPair_ResetIter( postFields );
+
+ Typical calling sequence to interate through a created object:
+ (void) NW_NVPair_ResetIter( postfields );
+
+ status = NW_NVPair_GetNext( postfields, &name, &value );
+ while ( status == KBrsrSuccess ) {
+ ** code that uses name-value pairs **
+ status = NW_NVPair_GetNext( postfields, &name, &value );
+ }
+ if ( status != KBrsrNotFound ) {
+ return status;
+ }
+*/
+
+/*
+** Type Declarations
+*/
+/* Holds name-value pairs as ucs2 strings. */
+typedef struct {
+ NW_Ucs2* iterPtr; /* Used to keep place with iterating over pairs. */
+ NW_Ucs2* strTable; /* Array of null-terminated ucs2 strings. */
+ NW_Uint32 size; /* Total # of ucs2 chars of string space. */
+} NW_NVPair_t;
+
+/* a function type for passing a name value string pair */
+typedef TBrowserStatusCode (NW_NVPair_NVFunction_t)(NW_NVPair_t* thisObj,
+ const NW_Ucs2* name,
+ const NW_Ucs2* value);
+/*
+** Preprocessor Macro Definitions
+*/
+
+
+/*
+** Global Function Declarations
+*/
+
+/*****************************************************************
+
+ Name: NW_NVPair_New
+
+ Description: Allocates a NW_Pair_t object.
+
+ Parameters: none
+
+ Return Value: pointer to newly create object. If fails, NULL.
+
+******************************************************************/
+NW_NVPair_t* NW_NVPair_New (void);
+
+/*****************************************************************
+
+ Name: NW_NVPair_Delete
+
+ Description:
+ Dellocates a NW_Pair_t object. Allows thisObj == NULL.
+
+
+ Parameters:
+ thisObj - in: Object to deallocate.
+
+ Return Value: none
+
+******************************************************************/
+void NW_NVPair_Delete (NW_NVPair_t* thisObj);
+
+/*****************************************************************
+
+ Name: NW_NVPair_IsEmpty
+
+ Description:
+ Returns NW_TRUE if the object is NULL or it does not contain
+ any value-pairs.
+
+ Parameters:
+ thisObj - in: Object to deallocate.
+
+ Return Value:
+ NW_TRUE - if object contains 1 or more name-value pairs.
+ NW_FALSE - if object is null or it is empty (no name-value pairs).
+
+******************************************************************/
+NW_Bool NW_NVPair_IsEmpty (NW_NVPair_t* thisObj);
+
+
+/*****************************************************************
+
+ Name: NW_NVPair_CalSize
+
+ Description:
+ Records the storage requirements for the name-value
+ pair. Counts string plus null-terminater. Used when AddFirst is
+ called to allocate all the necessary storage at once.
+
+ Parameters:
+ thisObj - in/out: NW_NV_Pair_t object.
+ name - in: name string
+ value - in: value string
+
+ Requires:
+ (name != NULL) && (name[0] != '\0')
+ thisObj != NULL
+
+ Return Value:
+ KBrsrSuccess
+
+******************************************************************/
+NW_NVPair_NVFunction_t NW_NVPair_CalSize;
+
+
+/*****************************************************************
+
+ Name: NW_NVPair_AllocStorage
+
+ Description:
+ This routine allocates the storage to all the name-value pairs
+ this object will hold.
+
+ Parameters:
+ thisObj - in/out: NW_NV_Pair_t object.
+
+ Requires:
+ thisObj != NULL
+ thisObj->size >= 3 (minimum to hold 1 name-value pair)
+
+ Return Value:
+ KBrsrSuccess
+ KBrsrOutOfMemory - unable to allocate storage for name-value
+ pairs.
+
+******************************************************************/
+TBrowserStatusCode NW_NVPair_AllocStorage (NW_NVPair_t* thisObj);
+
+/*****************************************************************
+
+ Name: NW_NVPair_Add
+
+ Description:
+ Adds a name-value pair to the object. Must be called after
+ NW_NVPair_AllocStorage is called to allocate memory.
+
+ Parameters:
+ thisObj - in/out: NW_NV_Pair_t object.
+ name - in: name string.
+ value - in: value string.
+
+ Requires:
+ thisObj != NULL
+ (name != NULL) && (name[0] != '\0')
+
+ Return Value:
+ KBrsrSuccess
+ KBrsrBufferTooSmall - name-value will not fit in allocated
+ storage.
+
+******************************************************************/
+NW_NVPair_NVFunction_t NW_NVPair_Add;
+
+
+/*****************************************************************
+
+ Name: NW_NVPair_ResetIter
+
+ Description:
+ Sets the iterator for NW_NVPair_GetNext to start at the first
+ name-value pair. Allows thisObj == NULL;
+
+ Parameters:
+ thisObj - in/out: NW_NV_Pair_t object.
+
+ Return Value:
+ KBrsrSuccess
+
+******************************************************************/
+TBrowserStatusCode NW_NVPair_ResetIter (NW_NVPair_t* thisObj);
+
+/*****************************************************************
+
+ Name: NW_NVPair_GetNext
+
+ Description:
+ Returns subsequent name-value pair in the order they have been
+ inserted. Returns KBrsrNotFound when no more name-value
+ pairs to return. Allows thisObj == NULL;
+
+ Parameters:
+ thisObj - in/out: NW_NV_Pair_t object.
+ name - out: name string.
+ value - out: value string. Returns NULL pointer for empty string ("").
+
+ Return Value:
+ KBrsrSuccess
+ KBrsrNotFound - returned if there is not a name-value
+ pair to return.
+
+******************************************************************/
+TBrowserStatusCode NW_NVPair_GetNext (NW_NVPair_t* thisObj, NW_Ucs2** name,
+ NW_Ucs2** value);
+
+
+/*
+** Global Variable Declarations
+*/
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* NW_NVPAIR_H */
+
+