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