/*******************************************************************

Copyright (c) 2004 Open Mobile Alliance, Ltd.  All Rights Reserved.

This software is made available under the usage and distribution terms 
covered by the Common Public License 1.0 and by using this software you
are bound by the terms and conditions of the same.

EXCEPT AS EXPRESSLY SET FORTH IN THE COMMON PUBLIC LICENSE,
THIS PROGRAM IS PROVIDED ON AN "AS IS" BASIS, 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, 
ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, 
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
   
Each recipient is solely responsible for determining the 
appropriateness of using and distributing this program and assumes 
all risks associated with its exercise of rights under the Common 
Public License, including but not limited to the risks and 
costs of program errors, compliance with applicable laws, 
damage to or loss of data, programs or equipment, and 
unavailability or interruption of operations.

********************************************************************/
/**
 * Header file for a simple stack implementation used by the WBXML scanner
 * and the SyncML parser.
 */

/*************************************************************************/
/* Definitions                                                           */
/*************************************************************************/
#ifndef _XLT_UTIL_STACK_H
#define _XLT_UTIL_STACK_H

#include "xlttags.h"
#include <smldef.h>

/* type for stack elements */
typedef XltTagID_t XltUtilStackItem_t;

/**
 * XLTUtilStack interface
 *
 * Like the WBXML/XML scanner, this stack implementation tries to emulate
 * an object-oriented interface. It consist of one stack structure that
 * contains the public methods and attributes and another private stack
 * structure that is not visible to the users of the stack. A stack object
 * has the following public methods:
 *
 * FUNCTION: top
 *
 * Returns the top element of the stack.
 *
 * PRE-Condition:
 *                 the stack contains at least one element
 *
 * POST-Condition:
 *
 * IN:             the stack
 *
 * OUT:            the top element of the stack
 *
 * IN/OUT:
 *
 * RETURNS:        SML_ERR_WRONG_USAGE, if the stack is empty
 *                 SML_ERR_OK, else
 *
 * FUNCTION: pop
 *
 * Returns the top element and takes it off the stack.
 *
 * PRE-Condition:
*                 the stack contains at least one element
*
* POST-Condition:
*                 the top element of the stack is removed
*
* IN:
*
* OUT:            the top element of the stack
*
* IN/OUT:         the stack
*
* RETURNS:        SML_ERR_WRONG_USAGE, if the stack is empty
*                 SML_ERR_NOT_ENOUGH_SPACE, if memory reallocation failed
*                 SML_ERR_OK, else
*
* FUNCTION: push
*
* Put a new element on top of the stack.
*
* PRE-Condition:
*
* POST-Condition:
*                 popping the stack yields the same stack as before
*                 the push
*
* IN:             the new stack element
*
* OUT:
*
* IN/OUT:         the stack
*
* RETURNS:        SML_ERR_NOT_ENOUGH_SPACE, if memory reallocation failed
*                 SML_ERR_OK, else
*
* FUNCTION: destroy
*
* Free the memory used by the stack.
*
* PRE-Condition:
* POST-Condition:
*
* IN:
*
* OUT:
*
* IN/OUT:         the stack
*
* RETURNS:        SML_ERR_OK
*/
typedef struct XltUtilStack_s *XltUtilStackPtr_t, XltUtilStack_t;
struct XltUtilStack_s
{
        Ret_t (*top)(const XltUtilStackPtr_t, XltUtilStackItem_t *);
        Ret_t (*pop)(XltUtilStackPtr_t, XltUtilStackItem_t *);
        Ret_t (*push)(XltUtilStackPtr_t, const XltUtilStackItem_t);
        Ret_t (*destroy)(XltUtilStackPtr_t);
};

/**
 * FUNCTION: xltUtilCreateStack
 *
 * Creates a new stack. The size parameter indicates for how many elements
 * memory should be allocated initially. This does _not_ mean that you can
 * not push more than that many element onto the stack - in that case
 * memory for another size elements is allocated.
 *
 * PRE-Condition:
 * POST-Condition:
 *                 the stack pointer points to a new, empty stack
 *
 * IN:             size, the initial size of the stack
 *
 * OUT:            a new stack
 *
 * IN/OUT:
 *
 * RETURNS:        SML_ERR_NOT_ENOUGH_SPACE, if memory allocation failed
 *                 SML_ERR_OK, else
 */
Ret_t xltUtilCreateStack(XltUtilStackPtr_t *, const Long_t size);

#endif
