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

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.

********************************************************************/
#ifndef _SML_H
  #define _SML_H


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

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




/*************************************************************************
 *  External Functions
 *************************************************************************/



/**
 * ============================
 * General SyncML Functions
 * ============================
 **/
SML_API_DEF Ret_t smlInit(SmlOptionsPtr_t pOptions);
SML_API_DEF Ret_t smlSetSyncMLOptions (SmlOptionsPtr_t pOptions);
SML_API_DEF Ret_t smlTerminate(void);



/**
 * ============================
 * Workspace Handling Functions
 * ============================
 **/

SML_API_DEF Ret_t smlLockReadBuffer(InstanceID_t id, MemPtr_t *pReadPosition, MemSize_t *usedSize);
SML_API_DEF Ret_t smlUnlockReadBuffer(InstanceID_t id, MemSize_t processedBytes);
SML_API_DEF Ret_t smlLockWriteBuffer(InstanceID_t id, MemPtr_t *pWritePosition, MemSize_t *freeSize);
SML_API_DEF Ret_t smlUnlockWriteBuffer(InstanceID_t id, MemSize_t writtenBytes);



/**
 * ===========================================
 * Protocol Element Building Functions (for Originator)
 * ===========================================
 **/

/* Protocol Management */
SML_API_DEF Ret_t smlStartMessage(InstanceID_t id, SmlSyncHdrPtr_t pContent);
SML_API_DEF Ret_t smlEndMessage(InstanceID_t id, Boolean_t final);
SML_API_DEF Ret_t smlStartSync(InstanceID_t id, SmlSyncPtr_t pContent);
SML_API_DEF Ret_t smlEndSync(InstanceID_t id);

#ifdef ATOMIC_SEND  /* these API calls are NOT included in the Toolkit lite version */
  SML_API_DEF Ret_t smlStartAtomic(InstanceID_t id, SmlAtomicPtr_t pContent);
  SML_API_DEF Ret_t smlEndAtomic(InstanceID_t id);
#endif
#ifdef SEQUENCE_SEND
  SML_API_DEF Ret_t smlStartSequence(InstanceID_t id, SmlSequencePtr_t pContent);
  SML_API_DEF Ret_t smlEndSequence(InstanceID_t id);
#endif

/* Sync Commands */
#ifdef ADD_SEND
  SML_API_DEF Ret_t smlAddCmd(InstanceID_t id, SmlAddPtr_t pContent);
#endif
SML_API_DEF Ret_t smlAlertCmd(InstanceID_t id, SmlAlertPtr_t pContent);
SML_API_DEF Ret_t smlDeleteCmd(InstanceID_t id, SmlDeletePtr_t pContent);
#ifdef GET_SEND
  SML_API_DEF Ret_t smlGetCmd(InstanceID_t id, SmlGetPtr_t pContent);
#endif
SML_API_DEF Ret_t smlPutCmd(InstanceID_t id, SmlPutPtr_t pContent);
SML_API_DEF Ret_t smlMapCmd(InstanceID_t id, SmlMapPtr_t pContent);
SML_API_DEF Ret_t smlResultsCmd(InstanceID_t id, SmlResultsPtr_t pContent);
SML_API_DEF Ret_t smlStatusCmd(InstanceID_t id, SmlStatusPtr_t pContent);
SML_API_DEF Ret_t smlReplaceCmd(InstanceID_t id, SmlReplacePtr_t pContent);

#ifdef COPY_SEND  /* these API calls are NOT included in the Toolkit lite version */
  SML_API_DEF Ret_t smlCopyCmd(InstanceID_t id, SmlCopyPtr_t pContent);
#endif
#ifdef EXEC_SEND
  SML_API_DEF Ret_t smlExecCmd(InstanceID_t id, SmlExecPtr_t pContent);
#endif
#ifdef SEARCH_SEND
  SML_API_DEF Ret_t smlSearchCmd(InstanceID_t id, SmlSearchPtr_t pContent);
#endif
SML_API_DEF Ret_t smlStartEvaluation(InstanceID_t id);
SML_API_DEF Ret_t smlEndEvaluation(InstanceID_t id, MemSize_t *freemem);


/**
 * ============================================
 * Command Dispatching Functions (for Receiver)
 * ============================================
 **/

SML_API_DEF Ret_t smlProcessData(InstanceID_t id, SmlProcessMode_t mode);

/**
 * FUNCTION:  smlProcessMgmtTree
 *
 * Build the subtree from SyncML TNDS. 
 *
 * IN:              enc
 *                  The XML encoding
 *
 * IN:              pBufEnd
 *                  The SyncML buffer end boundry
 *
 * IN:              pBufPos
 *                  The SyncML buffer begin boundry
 *
 * OUT:             ppMgmtTree
 *                  The subtree
 *
 * RETURN:          Ret_t
 */
SML_API_DEF Ret_t smlProcessMgmtTree(int enc, char *pBufEnd, char *pBufPos, SmlSubTreePtr_t *ppMgmtTree);

/**
 * FUNCTION:  smlMarshalMgmtTree
 *
 * Build the SyncML TNDS from subtree. 
 *
 * IN:              enc
 *                  The XML encoding
 *
 * IN:              pBufEnd
 *                  The SyncML buffer end boundry
 *
 * IN OUT:          ppBufPos
 *                  The SyncML buffer begin boundry, also point to the message boundry
 *
 * IN:              pMgmtTree
 *                  The subtree
 *
 * RETURN:          Ret_t
 */SML_API_DEF Ret_t smlMarshalMgmtTree(int enc, char *pBufEnd, char **ppBufPos, SmlSubTreePtr_t pMgmtTree);



/**
 * ====================================================
 * Callback Functions to be implemented by the Receiver
 * ====================================================
 **/

/* Protocol Management */
typedef Ret_t (*smlStartMessageFunc) (InstanceID_t id, VoidPtr_t userData, SmlSyncHdrPtr_t pContent);
typedef Ret_t (*smlEndMessageFunc) (InstanceID_t id, VoidPtr_t userData, Boolean_t final);
typedef Ret_t (*smlStartSyncFunc) (InstanceID_t id, VoidPtr_t userData, SmlSyncPtr_t pContent);
typedef Ret_t (*smlEndSyncFunc) (InstanceID_t id, VoidPtr_t userData);

#ifdef ATOMIC_RECEIVE  /* these callbacks are NOT included in the Toolkit lite version */
  typedef Ret_t (*smlStartAtomicFunc) (InstanceID_t id, VoidPtr_t userData, SmlAtomicPtr_t pContent);
  typedef Ret_t (*smlEndAtomicFunc) (InstanceID_t id, VoidPtr_t userData);
#endif
#ifdef SEQUENCE_RECEIVE
  typedef Ret_t (*smlStartSequenceFunc) (InstanceID_t id, VoidPtr_t userData, SmlSequencePtr_t pContent);
  typedef Ret_t (*smlEndSequenceFunc) (InstanceID_t id, VoidPtr_t userData);
#endif

/* Sync Commands */
typedef Ret_t (*smlAddCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlAddPtr_t pContent);
typedef Ret_t (*smlAlertCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlAlertPtr_t pContent);
typedef Ret_t (*smlDeleteCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlDeletePtr_t pContent);
typedef Ret_t (*smlGetCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlGetPtr_t pContent);
typedef Ret_t (*smlPutCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlPutPtr_t pContent);
#ifdef MAP_RECEIVE
  typedef Ret_t (*smlMapCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlMapPtr_t pContent);
#endif
#ifdef RESULT_RECEIVE
  typedef Ret_t (*smlResultsCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlResultsPtr_t pContent);
#endif
typedef Ret_t (*smlStatusCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlStatusPtr_t pContent);
typedef Ret_t (*smlReplaceCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlReplacePtr_t pContent);

#ifdef COPY_RECEIVE  /* these callbacks are NOT included in the Toolkit lite version */
  typedef Ret_t (*smlCopyCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlCopyPtr_t param);
#endif
#ifdef EXEC_RECEIVE
  typedef Ret_t (*smlExecCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlExecPtr_t pContent);
#endif
#ifdef SEARCH_RECEIVE
  typedef Ret_t (*smlSearchCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlSearchPtr_t pContent);
#endif


/* Other Callbacks */
typedef Ret_t (*smlHandleErrorFunc) (InstanceID_t id, VoidPtr_t userData);
typedef Ret_t (*smlTransmitChunkFunc) (InstanceID_t id, VoidPtr_t userData);




/**
 * Structure defining references to the applications callback implementations
 **/
typedef struct sml_callbacks_s {
  /* Protocol Management Callbacks */
  smlStartMessageFunc    startMessageFunc;
  smlEndMessageFunc      endMessageFunc;
  smlStartSyncFunc       startSyncFunc;
  smlEndSyncFunc         endSyncFunc;
#ifdef ATOMIC_RECEIVE  /* these callbacks are NOT included in the Toolkit lite version */
    smlStartAtomicFunc     startAtomicFunc;
    smlEndAtomicFunc       endAtomicFunc;
#endif
#ifdef SEQUENCE_RECEIVE
    smlStartSequenceFunc   startSequenceFunc;
    smlEndSequenceFunc     endSequenceFunc;
#endif
  /* Sync Command callbacks */
  smlAddCmdFunc          addCmdFunc;
  smlAlertCmdFunc        alertCmdFunc;
  smlDeleteCmdFunc       deleteCmdFunc;
  smlGetCmdFunc          getCmdFunc;
  smlPutCmdFunc          putCmdFunc;
#ifdef MAP_RECEIVE
  smlMapCmdFunc          mapCmdFunc;
#endif
#ifdef RESULT_RECEIVE
  smlResultsCmdFunc      resultsCmdFunc;
#endif
  smlStatusCmdFunc       statusCmdFunc;
  smlReplaceCmdFunc      replaceCmdFunc;
#ifdef COPY_RECEIVE  /* these callbacks are NOT included in the Toolkit lite version */
    smlCopyCmdFunc         copyCmdFunc;
#endif
#ifdef EXEC_RECEIVE
    smlExecCmdFunc         execCmdFunc;
#endif
#ifdef SEARCH_RECEIVE
    smlSearchCmdFunc       searchCmdFunc;
#endif
  /* Other Callbacks */
  smlHandleErrorFunc     handleErrorFunc;
  smlTransmitChunkFunc   transmitChunkFunc;
  //smlPrintFunc           printFunc;
} *SmlCallbacksPtr_t, SmlCallbacks_t;



/**
 * ============================
 * Instance Management Functions
 * ============================
 **/

SML_API_DEF Ret_t smlInitInstance(SmlCallbacksPtr_t pCallbacks, SmlInstanceOptionsPtr_t pOptions, VoidPtr_t pUserData, InstanceID_t *pId);
SML_API_DEF Ret_t smlTerminateInstance (InstanceID_t id);
SML_API_DEF Ret_t smlSetCallbacks (InstanceID_t id, SmlCallbacksPtr_t pCallbacks);
SML_API_DEF Ret_t smlSetUserData (InstanceID_t id, VoidPtr_t pUserData);

#ifndef __SML_LITE__  /* these API calls are NOT included in the Toolkit lite version */
  SML_API_DEF Ret_t smlSetEncoding (InstanceID_t id, SmlEncoding_t encoding);
#endif



/**
 * ===================================
 * Some Helper Functions and Utilities
 * ===================================
 **/

SML_API_DEF Ret_t smlFreeProtoElement(VoidPtr_t pProtoElement);
SML_API_DEF void smlFreePcdata(SmlPcdataPtr_t pPcdata);
#ifndef __SML_LITE__  /* these API calls are NOT included in the Toolkit lite version */
  SML_API_DEF String_t smlPcdata2String( SmlPcdataPtr_t pcdata );
  SML_API_DEF SmlPcdataPtr_t smlString2Pcdata( String_t str );
  SML_API_DEF SmlPcdataPtr_t smlPcdataDup(SmlPcdataPtr_t pcdata); 
  SML_API_DEF MemSize_t	smlGetFreeBuffer(InstanceID_t id);
#endif

#ifndef __PALM_OS__  /* these API calls are NOT exported in the Palm OS version */
SML_API_DEF void 	*smlLibMemset(void *pObject, int value, MemSize_t count);
SML_API_DEF void 	*smlLibMemcpy(void *pTarget, const void *pSource, MemSize_t count);
SML_API_DEF int		smlLibMemcmp(const void *pTarget, const void *pSource, MemSize_t count);
SML_API_DEF void	*smlLibMalloc(MemSize_t size);
SML_API_DEF void	smlLibFree(void *pObject);
SML_API_DEF MemSize_t	smlLibMemsize(const void *pObject);

SML_API_DEF String_t 	smlLibStrdup (const char *constStringP);
SML_API_DEF String_t	smlLibStrcpy(const char *pTarget, const char *pSource);
SML_API_DEF int		smlLibStrcmp(const char *pTarget, const char *pSource);
SML_API_DEF int		smlLibStrlen(const char *pString);
SML_API_DEF String_t	smlLibStrncpy(const char *pTarget, const char *pSource, int count);
SML_API_DEF int		smlLibStrncmp(const char *pTarget, const char *pSource, int count);
SML_API_DEF String_t	smlLibStrcat(const char *pTarget, const char *pSource);
SML_API_DEF String_t	smlLibStrchr(const char *pString, char character);
#ifndef __SML_LITE__  /* these API calls are NOT included in the Toolkit lite version */
  SML_API_DEF void 	smlLibPrint(const char *text, ...);
  SML_API_DEF void 	*smlLibMemmove(void *pTarget, const void *pSource, MemSize_t count);
  SML_API_DEF void	*smlLibRealloc(void *pObject, MemSize_t size);
  SML_API_DEF String_t	smlLibStrncat(const char *pTarget, const char *pSource, int count);
  SML_API_DEF String_t	smlLibStrstr(const char *pString, const char *pSubString);
#endif
#endif



#endif
