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

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.

********************************************************************/
/*************************************************************************/
/* module:          Encoder header file                                  */
/* file:            xltenc.h                                             */
/* target system:   All                                                  */
/* target OS:       All                                                  */   
/*************************************************************************/

/*************************************************************************/
/*  Definitions
/*************************************************************************/

#ifndef _XLT_ENC_H
#define _XLT_ENC_H


#include <smlerr.h>
#include <xltenccom.h>
#include <smldef.h>
#include <smldtd.h>
#include <xlttags.h>

#ifdef _cplusplus
extern "C" {
#endif

//Type for storing encoder information
typedef struct XltEncoder_s
{
  SmlEncoding_t enc;
  SmlPcdataExtension_t cur_ext;
  SmlPcdataExtension_t last_ext;
  Boolean_t final;
  XltSpaceEvaluationPtr_t space_evaluation;
  MemSize_t end_tag_size;
} XltEncoder_t, *XltEncoderPtr_t;


/**
 * FUNCTION: smlXltEncInit
 *
 * Initializes an XML buffer; Creates XML code for the SyncHdr
 * and appends it to the buffer.
 * Returns 0 if operation was successful.
 *
 * PRE-Condition:   no memory should be allocated for ppEncoder (should be NULL)
 *                  pHeader has to contain a valid SyncHdr structure
 *                  pBufEnd must point to the end of the (WB)XML buffer
 *                  ppBufPos has to be initialized to the start point of the
 *                  (WB)XML buffer.
 *                  
 *
 * POST-Condition:  After the function call ppBufPos points to the
 *                  first free byte in the buffer behind the (WB)XML document
 *
 * IN:              enc, the encoding constant (SML_WBXML or SML_XML)
 *                  pHeader, the SyncML header structure
 *                  pBufEnd, pointer to the end of the buffer to write on
 * 
 * IN/OUT:          ppBufPos, current position of the bufferpointer
 *                  ppEncoder, the encoder object       
 *
 * RETURN:          shows error codes of function, 
 *                  0, if OK
 *                  Possible Error Codes:
 *                  SML_ERR_XLT_MISSING_CONT            
 *                  SML_ERR_XLT_BUF_ERR                 
 *                  SML_ERR_XLT_INVAL_ELEM_TYPE         
 *                  SML_ERR_XLT_INVAL_LIST_TYPE         
 *                  SML_ERR_XLT_INVAL_TAG_TYPE          
 *                  SML_ERR_XLT_CONTENT_SIZE_LENGTH     
 *                  SML_ERR_XLT_ENC_UNK	               
 *                  SML_ERR_XLT_INVAL_PROTO_ELEM
 */
Ret_t xltEncInit(SmlEncoding_t enc, const SmlSyncHdrPtr_t pHeader, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltEncoderPtr_t *ppEncoder);

/**
 * FUNCTION: smlXltEncAppend
 *
 * Generates XML code and appends it to the XML buffer.
 *
 * PRE-Condition:   pEncoder holds the initialized encoder structure.
 *                  the initialization takes place in the xltEncAppend function
 *                  pContent has to contain a valid content structure structure
 *                  pBufEnd must point to the end of the (WB)XML buffer
 *                  ppBufPos has to be initialized to the start point of the
 *                  (WB)XML buffer.
 *                  
 *
 * POST-Condition:  After the function call ppBufPos points to the
 *                  first free byte in the buffer behind the (WB)XML document
 *
 * IN:              pEncoder, the encoder object
 *                  pe, the protocol element (PE_ADD, ...)    
 *                  pBufEnd, pointer to the end of the buffer to write on
 *                  pContent, the content to append to the SyncML document
 * 
 * IN/OUT:          ppBufPos, current position of the bufferpointer
 * 
 * RETURN:          shows error codes of function, 
 *                  0, if OK
 *                  Possible Error Codes:
 *                  SML_ERR_XLT_MISSING_CONT            
 *                  SML_ERR_XLT_BUF_ERR                 
 *                  SML_ERR_XLT_INVAL_ELEM_TYPE         
 *                  SML_ERR_XLT_INVAL_LIST_TYPE         
 *                  SML_ERR_XLT_INVAL_TAG_TYPE          
 *                  SML_ERR_XLT_CONTENT_SIZE_LENGTH     
 *                  SML_ERR_XLT_ENC_UNK	               
 *                  SML_ERR_XLT_INVAL_PROTO_ELEM
 */
 
Ret_t xltEncAppend(const XltEncoderPtr_t pEncoder, 
                   SmlProtoElement_t pe, 
                   const MemPtr_t pBufEnd,
                   const VoidPtr_t pContent,
                   MemPtr_t *ppBufPos);
/**
 * FUNCTION: smlXltEncTerminate_t pBufEnd, const VoidPtr_t pContent, MemPtr_t *ppBufPos,
 *
 * Finalizes the (WB)XML document and returns the size of written bytes to 
 * the workspace module
 *
 * PRE-Condition:   pEncoder holds the initialized encoder structure.
 *                  the initialization takes place in the xltEncAppend function
 *                  pBufEnd must point to the end of the (WB)XML buffer
 *                  ppBufPos has to be initialized to the start point of the
 *                  (WB)XML buffer.
 *                  
 * POST-Condition:  After the function call ppBufPos points to the
 *                  first free byte in the buffer behind the (WB)XML document
 *
 * IN:              pEncoder, the encoder object
 *                  pBufEnd, pointer to the end of the buffer to write on
 * 
 * IN/OUT:          ppBufPos, current position of the bufferpointer
 * 
 * RETURN:          shows error codes of function, 
 *                  0, if OK
 *                  Possible Error Codes:
 *                  SML_ERR_XLT_MISSING_CONT            
 *                  SML_ERR_XLT_BUF_ERR                 
 *                  SML_ERR_XLT_INVAL_ELEM_TYPE         
 *                  SML_ERR_XLT_INVAL_LIST_TYPE         
 *                  SML_ERR_XLT_INVAL_TAG_TYPE          
 *                  SML_ERR_XLT_CONTENT_SIZE_LENGTH     
 *                  SML_ERR_XLT_ENC_UNK	               
 *                  SML_ERR_XLT_INVAL_PROTO_ELEM
 */
Ret_t xltEncTerminate(const XltEncoderPtr_t pEncoder, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos);
Ret_t xltEncReset(XltEncoderPtr_t pEncoder);
Ret_t xltGenerateTag(XltTagID_t, XltTagType_t, SmlEncoding_t, BufferMgmtPtr_t, SmlPcdataExtension_t);
Ret_t xltStartEvaluation(XltEncoderPtr_t pEncoder);
Ret_t xltEndEvaluation(InstanceID_t id, XltEncoderPtr_t pEncoder, MemSize_t *freemem);
Ret_t xltEncBlock(XltTagID_t tagId, XltRO_t reqOptFlag, const VoidPtr_t pContent, SmlEncoding_t enc, BufferMgmtPtr_t pBufMgr, SmlPcdataExtension_t attFlag);
Ret_t xltBuildExtention(SmlPcdataExtension_t extId, XltRO_t reqOptFlag, VoidPtr_t pContent, SmlEncoding_t enc, BufferMgmtPtr_t pBufMgr);
Ret_t xltEncPcdata(XltTagID_t tagId, XltRO_t reqOptFlag, const VoidPtr_t pContent, SmlEncoding_t enc, BufferMgmtPtr_t pBufMgr, SmlPcdataExtension_t attFlag);
Ret_t subdtdEncWBXML(XltTagID_t tagId, XltRO_t reqOptFlag, const VoidPtr_t pContent, SmlEncoding_t enc, BufferMgmtPtr_t pBufMgr, SmlPcdataExtension_t attFlag);

/**
 * FUNCTION: xltEncDDFInit
 *
 * Initializes an XML buffer; Creates XML code for the TNDS
 * and appends it to the buffer.
 * Returns 0 if operation was successful.
 *
 * IN:              enc, the encoding constant (SML_WBXML or SML_XML)
 *                  pHeader, the SyncML header structure
 *                  pBufEnd, pointer to the end of the buffer to write on
 * 
 * IN/OUT:          ppBufPos, current position of the bufferpointer
 *                  ppEncoder, the encoder object       
 *
 * RETURN:          Ret_t
 */
Ret_t xltEncDDFInit(SmlEncoding_t enc, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltEncoderPtr_t *ppEncoder);


/**
 * FUNCTION: xltEncDDFTerminate
 *
 * Finalizes the (WB)XML document and returns the size of written bytes to 
 * the workspace module
 *
 * IN:              pEncoder, the encoder object
 *                  pBufEnd, pointer to the end of the buffer to write on
 * 
 * IN/OUT:          ppBufPos, current position of the bufferpointer
 * 
 * RETURN:          Ret_t
 */
Ret_t xltEncDDFTerminate(const XltEncoderPtr_t pEncoder, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos);

/**
 * FUNCTION: xltEncDDFAppend
 *
 * Generates XML code and appends it to the XML buffer.
 *
 * IN:              pEncoder, the encoder object
 *                  pe, the protocol element (PE_ADD, ...)    
 *                  pBufEnd, pointer to the end of the buffer to write on
 *                  pContent, the content to append to the SyncML document
 * 
 * IN/OUT:          ppBufPos, current position of the bufferpointer
 * 
 * RETURN:          Ret_t
 */
Ret_t xltEncDDFAppend(const XltEncoderPtr_t pEncoder, const MemPtr_t pBufEnd, const VoidPtr_t pContent, MemPtr_t *ppBufPos);

#ifdef _cplusplus
}
#endif

#endif
