1/*************************************************************************/ 2/* module: External SyncML API */ 3/* */ 4/* file: sml.h */ 5/* target system: all */ 6/* target OS: all */ 7/* */ 8/* Description: */ 9/* Platform independent definition of the SyncML API functions */ 10/* This is the external API exposed to applications using SyncML */ 11/*************************************************************************/ 12 13 14/* 15 * Copyright Notice 16 * Copyright (c) Ericsson, IBM, Lotus, Matsushita Communication 17 * Industrial Co., Ltd., Motorola, Nokia, Openwave Systems, Inc., 18 * Palm, Inc., Psion, Starfish Software, Symbian, Ltd. (2001). 19 * All Rights Reserved. 20 * Implementation of all or part of any Specification may require 21 * licenses under third party intellectual property rights, 22 * including without limitation, patent rights (such a third party 23 * may or may not be a Supporter). The Sponsors of the Specification 24 * are not responsible and shall not be held responsible in any 25 * manner for identifying or failing to identify any or all such 26 * third party intellectual property rights. 27 * 28 * THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN ARE PROVIDED 29 * ON AN "AS IS" BASIS WITHOUT WARRANTY OF ANY KIND AND ERICSSON, IBM, 30 * LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO. LTD, MOTOROLA, 31 * NOKIA, PALM INC., PSION, STARFISH SOFTWARE AND ALL OTHER SYNCML 32 * SPONSORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 33 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 34 * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 35 * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT 36 * SHALL ERICSSON, IBM, LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO., 37 * LTD, MOTOROLA, NOKIA, PALM INC., PSION, STARFISH SOFTWARE OR ANY 38 * OTHER SYNCML SPONSOR BE LIABLE TO ANY PARTY FOR ANY LOSS OF 39 * PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF 40 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 41 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH 42 * THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED 43 * OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. 44 * 45 * The above notice and this paragraph must be included on all copies 46 * of this document that are made. 47 * 48 */ 49 50 51#ifndef _SML_H 52 #define _SML_H 53 54 55/************************************************************************* 56 * Definitions 57 *************************************************************************/ 58 59#include <smldef.h> 60#include <smldtd.h> 61#include <string.h> 62#include <stdlib.h> 63 64 65/************************************************************************* 66 * External Functions 67 *************************************************************************/ 68 69#if !defined(NOWSM) || !__LINK_TOOLKIT_STATIC__ 70 71/** 72 * ============================ 73 * General SyncML Functions 74 * ============================ 75 **/ 76SML_API_DEF Ret_t smlInit(SmlOptionsPtr_t pOptions); 77SML_API_DEF Ret_t smlSetSyncMLOptions (SmlOptionsPtr_t pOptions); 78SML_API_DEF Ret_t smlTerminate(void); 79 80#endif 81 82 83/** 84 * ============================ 85 * Workspace Handling Functions 86 * ============================ 87 **/ 88 89SML_API_DEF Ret_t smlLockReadBuffer(InstanceID_t id, MemPtr_t *pReadPosition, MemSize_t *usedSize); 90SML_API_DEF Ret_t smlUnlockReadBuffer(InstanceID_t id, MemSize_t processedBytes); 91#ifdef NOWSM 92SML_API Ret_t smlSetMaxOutgoingSize(InstanceID_t id, MemSize_t maxOutgoingSize); 93SML_API Ret_t smlSetOutgoingBegin(InstanceID_t id); 94#endif 95SML_API_DEF Ret_t smlLockWriteBuffer(InstanceID_t id, MemPtr_t *pWritePosition, MemSize_t *freeSize); 96SML_API_DEF Ret_t smlUnlockWriteBuffer(InstanceID_t id, MemSize_t writtenBytes); 97 98 99 100/** 101 * =========================================== 102 * Protocol Element Building Functions (for Originator) 103 * =========================================== 104 **/ 105 106/* Protocol Management */ 107SML_API_DEF Ret_t smlStartMessage(InstanceID_t id, SmlSyncHdrPtr_t pContent); 108SML_API_DEF Ret_t smlStartMessageExt(InstanceID_t id, SmlSyncHdrPtr_t pContent, SmlVersion_t vers); /* %%% added by luz 2003-08-06) */ 109SML_API_DEF Ret_t smlEndMessage(InstanceID_t id, Boolean_t final); 110SML_API_DEF Ret_t smlStartSync(InstanceID_t id, SmlSyncPtr_t pContent); 111SML_API_DEF Ret_t smlEndSync(InstanceID_t id); 112 113#ifdef ATOMIC_SEND /* these API calls are NOT included in the Toolkit lite version */ 114 SML_API_DEF Ret_t smlStartAtomic(InstanceID_t id, SmlAtomicPtr_t pContent); 115 SML_API_DEF Ret_t smlEndAtomic(InstanceID_t id); 116#endif 117#ifdef SEQUENCE_SEND 118 SML_API_DEF Ret_t smlStartSequence(InstanceID_t id, SmlSequencePtr_t pContent); 119 SML_API_DEF Ret_t smlEndSequence(InstanceID_t id); 120#endif 121 122/* Sync Commands */ 123#ifdef ADD_SEND 124 SML_API_DEF Ret_t smlAddCmd(InstanceID_t id, SmlAddPtr_t pContent); 125#endif 126SML_API_DEF Ret_t smlAlertCmd(InstanceID_t id, SmlAlertPtr_t pContent); 127SML_API_DEF Ret_t smlDeleteCmd(InstanceID_t id, SmlDeletePtr_t pContent); 128#ifdef GET_SEND 129 SML_API_DEF Ret_t smlGetCmd(InstanceID_t id, SmlGetPtr_t pContent); 130#endif 131SML_API_DEF Ret_t smlPutCmd(InstanceID_t id, SmlPutPtr_t pContent); 132SML_API_DEF Ret_t smlMapCmd(InstanceID_t id, SmlMapPtr_t pContent); 133SML_API_DEF Ret_t smlResultsCmd(InstanceID_t id, SmlResultsPtr_t pContent); 134SML_API_DEF Ret_t smlStatusCmd(InstanceID_t id, SmlStatusPtr_t pContent); 135SML_API_DEF Ret_t smlReplaceCmd(InstanceID_t id, SmlReplacePtr_t pContent); 136 137#ifdef COPY_SEND /* these API calls are NOT included in the Toolkit lite version */ 138 SML_API_DEF Ret_t smlCopyCmd(InstanceID_t id, SmlCopyPtr_t pContent); 139#endif 140#ifdef EXEC_SEND 141 SML_API_DEF Ret_t smlExecCmd(InstanceID_t id, SmlExecPtr_t pContent); 142#endif 143#ifdef SEARCH_SEND 144 SML_API_DEF Ret_t smlSearchCmd(InstanceID_t id, SmlSearchPtr_t pContent); 145#endif 146SML_API_DEF Ret_t smlStartEvaluation(InstanceID_t id); 147SML_API_DEF Ret_t smlEndEvaluation(InstanceID_t id, MemSize_t *freemem); 148 149 150/** 151 * ============================================ 152 * Command Dispatching Functions (for Receiver) 153 * ============================================ 154 **/ 155 156SML_API_DEF Ret_t smlProcessData(InstanceID_t id, SmlProcessMode_t mode); 157 158 159 160/** 161 * ==================================================== 162 * Callback Functions to be implemented by the Receiver 163 * ==================================================== 164 **/ 165 166/* Protocol Management */ 167typedef Ret_t (*smlStartMessageFunc) (InstanceID_t id, VoidPtr_t userData, SmlSyncHdrPtr_t pContent); 168typedef Ret_t (*smlEndMessageFunc) (InstanceID_t id, VoidPtr_t userData, Boolean_t final); 169typedef Ret_t (*smlStartSyncFunc) (InstanceID_t id, VoidPtr_t userData, SmlSyncPtr_t pContent); 170typedef Ret_t (*smlEndSyncFunc) (InstanceID_t id, VoidPtr_t userData); 171 172#ifdef ATOMIC_RECEIVE /* these callbacks are NOT included in the Toolkit lite version */ 173 typedef Ret_t (*smlStartAtomicFunc) (InstanceID_t id, VoidPtr_t userData, SmlAtomicPtr_t pContent); 174 typedef Ret_t (*smlEndAtomicFunc) (InstanceID_t id, VoidPtr_t userData); 175#endif 176#ifdef SEQUENCE_RECEIVE 177 typedef Ret_t (*smlStartSequenceFunc) (InstanceID_t id, VoidPtr_t userData, SmlSequencePtr_t pContent); 178 typedef Ret_t (*smlEndSequenceFunc) (InstanceID_t id, VoidPtr_t userData); 179#endif 180 181/* Sync Commands */ 182typedef Ret_t (*smlAddCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlAddPtr_t pContent); 183typedef Ret_t (*smlAlertCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlAlertPtr_t pContent); 184typedef Ret_t (*smlDeleteCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlDeletePtr_t pContent); 185typedef Ret_t (*smlGetCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlGetPtr_t pContent); 186typedef Ret_t (*smlPutCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlPutPtr_t pContent); 187#ifdef MAP_RECEIVE 188 typedef Ret_t (*smlMapCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlMapPtr_t pContent); 189#endif 190#ifdef RESULT_RECEIVE 191 typedef Ret_t (*smlResultsCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlResultsPtr_t pContent); 192#endif 193typedef Ret_t (*smlStatusCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlStatusPtr_t pContent); 194typedef Ret_t (*smlReplaceCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlReplacePtr_t pContent); 195 196#ifdef COPY_RECEIVE /* these callbacks are NOT included in the Toolkit lite version */ 197 typedef Ret_t (*smlCopyCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlCopyPtr_t param); 198#endif 199#ifdef EXEC_RECEIVE 200 typedef Ret_t (*smlExecCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlExecPtr_t pContent); 201#endif 202#ifdef SEARCH_RECEIVE 203 typedef Ret_t (*smlSearchCmdFunc) (InstanceID_t id, VoidPtr_t userData, SmlSearchPtr_t pContent); 204#endif 205 206 207/* Other Callbacks */ 208typedef Ret_t (*smlHandleErrorFunc) (InstanceID_t id, VoidPtr_t userData); 209typedef Ret_t (*smlTransmitChunkFunc) (InstanceID_t id, VoidPtr_t userData); 210 211 212 213 214/** 215 * Structure defining references to the applications callback implementations 216 **/ 217typedef struct sml_callbacks_s { 218 /* Protocol Management Callbacks */ 219 smlStartMessageFunc startMessageFunc; 220 smlEndMessageFunc endMessageFunc; 221 smlStartSyncFunc startSyncFunc; 222 smlEndSyncFunc endSyncFunc; 223#ifdef ATOMIC_RECEIVE /* these callbacks are NOT included in the Toolkit lite version */ 224 smlStartAtomicFunc startAtomicFunc; 225 smlEndAtomicFunc endAtomicFunc; 226#endif 227#ifdef SEQUENCE_RECEIVE 228 smlStartSequenceFunc startSequenceFunc; 229 smlEndSequenceFunc endSequenceFunc; 230#endif 231 /* Sync Command callbacks */ 232 smlAddCmdFunc addCmdFunc; 233 smlAlertCmdFunc alertCmdFunc; 234 smlDeleteCmdFunc deleteCmdFunc; 235 smlGetCmdFunc getCmdFunc; 236 smlPutCmdFunc putCmdFunc; 237#ifdef MAP_RECEIVE 238 smlMapCmdFunc mapCmdFunc; 239#endif 240#ifdef RESULT_RECEIVE 241 smlResultsCmdFunc resultsCmdFunc; 242#endif 243 smlStatusCmdFunc statusCmdFunc; 244 smlReplaceCmdFunc replaceCmdFunc; 245#ifdef COPY_RECEIVE /* these callbacks are NOT included in the Toolkit lite version */ 246 smlCopyCmdFunc copyCmdFunc; 247#endif 248#ifdef EXEC_RECEIVE 249 smlExecCmdFunc execCmdFunc; 250#endif 251#ifdef SEARCH_RECEIVE 252 smlSearchCmdFunc searchCmdFunc; 253#endif 254 /* Other Callbacks */ 255 smlHandleErrorFunc handleErrorFunc; 256 smlTransmitChunkFunc transmitChunkFunc; 257 //smlPrintFunc printFunc; 258} *SmlCallbacksPtr_t, SmlCallbacks_t; 259 260 261 262/** 263 * ============================ 264 * Instance Management Functions 265 * ============================ 266 **/ 267 268SML_API_DEF Ret_t smlInitInstance(SmlCallbacksPtr_t pCallbacks, SmlInstanceOptionsPtr_t pOptions, VoidPtr_t pUserData, InstanceID_t *pId); 269SML_API_DEF Ret_t smlTerminateInstance (InstanceID_t id); 270SML_API_DEF Ret_t smlSetCallbacks (InstanceID_t id, SmlCallbacksPtr_t pCallbacks); 271SML_API_DEF Ret_t smlSetUserData (InstanceID_t id, VoidPtr_t pUserData); 272// added by luz %%%: 273SML_API Ret_t smlGetUserData(InstanceID_t id, VoidPtr_t *ppUserData); 274SML_API Ret_t smlGetEncoding(InstanceID_t id, SmlEncoding_t *pEncoding); 275 276#ifndef __SML_LITE__ /* these API calls are NOT included in the Toolkit lite version */ 277 SML_API_DEF Ret_t smlSetEncoding (InstanceID_t id, SmlEncoding_t encoding); 278#endif 279 280 281 282/** 283 * =================================== 284 * Some Helper Functions and Utilities 285 * =================================== 286 **/ 287 288SML_API_DEF Ret_t smlFreeProtoElement(VoidPtr_t pProtoElement); 289SML_API_DEF void smlFreePcdata(SmlPcdataPtr_t pPcdata); 290#ifndef __SML_LITE__ /* these API calls are NOT included in the Toolkit lite version */ 291 SML_API_DEF String_t smlPcdata2String( SmlPcdataPtr_t pcdata ); 292 SML_API_DEF SmlPcdataPtr_t smlString2Pcdata( String_t str ); 293 SML_API_DEF SmlPcdataPtr_t smlPcdataDup(SmlPcdataPtr_t pcdata); 294 SML_API_DEF MemSize_t smlGetFreeBuffer(InstanceID_t id); 295#endif 296 297#ifndef __PALM_OS__ /* these API calls are NOT exported in the Palm OS version */ 298SML_API_DEF void *smlLibMemset(void *pObject, int value, MemSize_t count); 299SML_API_DEF void *smlLibMemcpy(void *pTarget, const void *pSource, MemSize_t count); 300SML_API_DEF int smlLibMemcmp(const void *pTarget, const void *pSource, MemSize_t count); 301/*SML_API_DEF void *smlLibMalloc(MemSize_t size);*/ 302 #define smlLibMalloc DmAllocMem 303#include "dmMemory.h" 304 305SML_API_DEF void smlLibFree(void *pObject); 306SML_API_DEF MemSize_t smlLibMemsize(const void *pObject); 307 308SML_API_DEF String_t smlLibStrdup (const char *constStringP); 309SML_API_DEF String_t smlLibStrcpy(const char *pTarget, const char *pSource); 310SML_API_DEF int smlLibStrcmp(const char *pTarget, const char *pSource); 311SML_API_DEF int smlLibStrlen(const char *pString); 312SML_API_DEF String_t smlLibStrncpy(const char *pTarget, const char *pSource, int count); 313SML_API_DEF int smlLibStrncmp(const char *pTarget, const char *pSource, int count); 314SML_API_DEF String_t smlLibStrcat(const char *pTarget, const char *pSource); 315SML_API_DEF String_t smlLibStrchr(const char *pString, char character); 316#ifndef __SML_LITE__ /* these API calls are NOT included in the Toolkit lite version */ 317 SML_API_DEF void smlLibPrint(const char *text, ...); 318 SML_API_DEF void *smlLibMemmove(void *pTarget, const void *pSource, MemSize_t count); 319 SML_API_DEF void *smlLibRealloc(void *pObject, MemSize_t size); 320 SML_API_DEF String_t smlLibStrncat(const char *pTarget, const char *pSource, int count); 321 SML_API_DEF String_t smlLibStrstr(const char *pString, const char *pSubString); 322#endif 323#endif 324 325//#define MOT_OTK_DEBUG 326#ifdef MOT_OTK_DEBUG 327#include <stdarg.h> 328 329void __kcdbg__(char *fmt, ...); 330#define KCDBG(EXP, args...) __kcdbg__("(%s:%s:%d) " #EXP " %s", "", __FUNCTION__, __LINE__, ##args, "\n") 331#else 332#define KCDBG(EXP, args...) 333#endif 334 335#endif 336