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

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.

********************************************************************/
/**
 * Common header file for the WBXML and the XML scanner.
 */

/*************************************************************************/
/* Definitions                                                           */
/*************************************************************************/
#ifndef _XLT_DEC_COM_H
#define _XLT_DEC_COM_H

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

#define DEC_ID          XLT_DEC_ID + 0
#define WBXML_ID        XLT_DEC_ID + 200
#define XML_ID          XLT_DEC_ID + 400
#define STACK_ID        XLT_DEC_ID + 600

#ifdef _cplusplus
extern "C" {
#endif


/* Token types returned by the scanner */
typedef enum {
    TOK_UNDEF = 0,
    TOK_TAG_START,
    TOK_TAG_END,
    TOK_TAG_EMPTY,
    TOK_CONT
} XltTokType_t;

/**
 * Struct containing a token returned by the scanner
 */
typedef struct
{
    XltTokType_t type;       /* XLT_TOK_TAG_START, etc. */
    XltTagID_t tagid;        /* TN_SYNCHDR, etc. - valid for token of type
				XLT_TOK_TAG_xxx */
    SmlPcdataExtension_t ext;   /* type of extension this tag belongs to -
				valid for token of type XLT_TOK_TAG_xxx */
    SmlPcdataPtr_t pcdata;      /* valid for token of type XLT_TOK_CONT_xxx */
    MemPtr_t start;          /* pointer to the start of this token within
				the document - needed for pushback */
} XltDecToken_t, *XltDecTokenPtr_t;

/**
 * Public interface for the XML/WBXML scanner components.
 *
 * The struct used for holding the XML and WBXML scanner state information
 * are the same - function pointers are used to map the "objects" public
 * methods to the right functions for scanning XML and WBXML documents.
 * This object-oriented interface enables the parser component to use the
 * two scanners interchangeably.
 * The interface contains serveral public methods and attributes:
 *
 * FUNCTION: nextTok
 *
 * Decodes the next valid token at the current position within the
 * document. Information about this token is placed into the curtok
 * attribute of the scanner object.
 *
 * PRE-Condition:
 * 
 * POST-Condition:
 *                 curtok contains the last valid token.
 *
 * IN:
 *
 * OUT:
 *
 * IN/OUT:         the scanner
 *
 * RETURNS:        SML_ERR_OK or an appropriate error code
 *
 * 
 * FUNCTION: destroy
 *
* Free the memory allocated by the scanner.
*
* PRE-Condition:
* POST-Condition:
*
* IN:
*
* OUT:
*
* IN/OUT:         the scanner
*
* RETURNS:        SML_ERR_OK or an appropriate error code
*
*
* FUNCTION: pushTok
*
* Resets the scanner to the beginning position within the document of the
* last valid token stored in curtok. Only the last found token can be
* pushed back. It is not possible to go back more than one token.
*
* PRE-Condition:
*                 curtok contains a valid token.
*                 
* POST-Condition:
*                 the next call of nextTok will find the token that was
*                 pushed back.
*
* IN/OUT:         the scanner
*
* RETURNS:        SML_ERR_OK or an appropriate error code
*
* FUNCITON: setBuf
*
* Set the buffer the scanner works on.
*
* FUNCTION: getPos
*
* Get the current position of the scanner within the working buffer.
*
* ATTRIBUTE: curtok
*
* Contains the last valid token found by a call to nextTok.
*
* ATTRIBUTE: charset
*
* The charset information as specified in the XML/WBXML document. This is
* the IANA assigned MIBEnum value.

* ATTRIBUTE: charsetStr
*
* String representation of the charset. This attribute is valid only when
* charset equals zero. Otherwise charsetStr will be NULL.
*
* ATTRIBUTE: pubID
*
* The document public identifier as specified in the XML/WBXML document.
* This is the numeric identifier assigned by the WAP Forum. If this value
* is zero, the public ID is instead specified as a string contained in the
* pubIDStr public attribute.
*
* ATTRIBUTE: pubIDStr
*
* The string representation of the document public identifier as specified
* in the XML/WBXML document (e.g. "-//WAPFORUM//DTD WML 1.0//EN"). This
* attribute is valid only when pubID equals zero. Otherwise pubIDStr will
* be NULL.
*
* ATTRIBUTE: finished
*
* This flag is set by the nextTok method when the scanner reaches the end
* of the buffer.
*/
typedef struct XltDecScanner_s XltDecScanner_t, *XltDecScannerPtr_t;
struct XltDecScanner_s
{
    /* public methods */
    Ret_t (*nextTok)(XltDecScannerPtr_t pScanner);
    Ret_t (*destroy)(XltDecScannerPtr_t pScanner);
    Ret_t (*pushTok)(XltDecScannerPtr_t pScanner);
    void (*setBuf)(XltDecScannerPtr_t pScanner, const MemPtr_t pBufStart, const MemPtr_t pBufEnd); 
    MemPtr_t (*getPos)(XltDecScannerPtr_t pScanner); 

    /* public attributes */
    XltDecTokenPtr_t curtok;
    Long_t charset;
    String_t charsetStr;
    Long_t pubID;
    String_t pubIDStr;
    Flag_t finished;
};

/**
 * FUNCTION: xltDecWbxmlInit, xltDecXmlInit
 *
 * Initialize a new WBXML/XML scanner.
 *
 * PRE-Condition:
 *                 ppScanner is NULL
 *
 * POST-Condition:
 *                 ppScanner points to an initialized scanner status object
 *
 * IN:             pBufEnd, buffer containing the WBXML/XML document
 *
 * IN/OUT:         pBufPos, pointer to the current position within the
 *                     buffer
 *
 * OUT:            ppScanner, a new WBXML/XML scanner status object
 *
 * RETURNS:        SML_ERR_OK or an appropriate error code
 */
Ret_t xltDecWbxmlInit(const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltDecScannerPtr_t *ppScanner);
Ret_t xltDecXmlInit(const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltDecScannerPtr_t *ppScanner);


/**
 * FUNCTION: xltDecDDFXmlInit, xltDecDDFWbxmlInit
 *
 * Initialize a new WBXML/XML scanner for TNDS process.
 *
 * IN:             pBufEnd, buffer containing the WBXML/XML document
 *
 * IN/OUT:         pBufPos, pointer to the current position within the
 *                     buffer
 *
 * OUT:            ppScanner, a new WBXML/XML scanner status object
 *
 * RETURNS:        Ret_t
 */
Ret_t xltDecDDFXmlInit(const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltDecScannerPtr_t *ppScanner);
Ret_t xltDecDDFWbxmlInit(const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltDecScannerPtr_t *ppScanner);

#ifdef _cplusplus
}
#endif

#endif
