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