1 /*************************************************************************/ 2 /* module: SyncML WorkSpace Manager */ 3 /* file: WSM.h */ 4 /* target system: All */ 5 /* target OS: All */ 6 /*************************************************************************/ 7 8 9 /* 10 * Copyright Notice 11 * Copyright (c) Ericsson, IBM, Lotus, Matsushita Communication 12 * Industrial Co., Ltd., Motorola, Nokia, Openwave Systems, Inc., 13 * Palm, Inc., Psion, Starfish Software, Symbian, Ltd. (2001). 14 * All Rights Reserved. 15 * Implementation of all or part of any Specification may require 16 * licenses under third party intellectual property rights, 17 * including without limitation, patent rights (such a third party 18 * may or may not be a Supporter). The Sponsors of the Specification 19 * are not responsible and shall not be held responsible in any 20 * manner for identifying or failing to identify any or all such 21 * third party intellectual property rights. 22 * 23 * THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN ARE PROVIDED 24 * ON AN "AS IS" BASIS WITHOUT WARRANTY OF ANY KIND AND ERICSSON, IBM, 25 * LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO. LTD, MOTOROLA, 26 * NOKIA, PALM INC., PSION, STARFISH SOFTWARE AND ALL OTHER SYNCML 27 * SPONSORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 28 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 29 * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 30 * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT 31 * SHALL ERICSSON, IBM, LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO., 32 * LTD, MOTOROLA, NOKIA, PALM INC., PSION, STARFISH SOFTWARE OR ANY 33 * OTHER SYNCML SPONSOR BE LIABLE TO ANY PARTY FOR ANY LOSS OF 34 * PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF 35 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 36 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH 37 * THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED 38 * OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. 39 * 40 * The above notice and this paragraph must be included on all copies 41 * of this document that are made. 42 * 43 */ 44 45 46 /** 47 * Workspace Manager API <BR> 48 * Manages the SyncML document in memory. 49 * 50 * @version @label 51 * 52 */ 53 54 #ifndef _WSM_H 55 #define _WSM_H 56 57 #include "smlerr.h" 58 #include "smldef.h" 59 60 #ifndef NOWSM 61 62 #include "wsm_sm.h" 63 64 65 typedef struct WsmOptions_s { 66 MemSize_t maxAvailMem; // maximum amount of memory available for all wsm buffers 67 } WsmOptions_t; 68 69 70 #ifdef __SML_LITE__ 71 #ifdef MAX_WSM_BUFFERS 72 #error "for __SML_LITE__, MAX_WSM_BUFFERS must not be predefined!" 73 #endif 74 #define MAX_WSM_BUFFERS 1 75 #else 76 #ifndef MAX_WSM_BUFFERS 77 // use default value of 4 (not much for a multi-connection server) 78 #define MAX_WSM_BUFFERS 4 79 #endif 80 #endif 81 82 83 /** WSM internal buffer structure */ 84 typedef struct WsmBuf_s { 85 String_t bufName; // external name of buffer 86 MemHandle_t memH; // memory handle 87 MemPtr_t pFirstFree; // pointer to first free element in buffer 88 MemPtr_t pFirstData; // pointer to first data element in buffer 89 MemSize_t size; // size of buffer 90 MemSize_t usedBytes; // used bytes in buffer 91 Byte_t flags; 92 } WsmBuf_t; 93 94 95 /** WSM globals for use with global Anchor */ 96 typedef struct WsmGlobals_s { 97 Ret_t wsmRet; // last WSM return code 98 Byte_t initWasCalled; // was wsmInit() called? 99 WsmBuf_t wsmBuf[MAX_WSM_BUFFERS]; 100 Short_t wsmIndex; // Index of actual buffer 101 WsmSmGlobals_t wsmSm; // WSM_SM global; device dependent! 102 } *WsmGlobalsPtr_t, WsmGlobals_t; 103 104 105 /** 106 * FUNCTION: wsmInit 107 * 108 * Initializes all Workspace Manager related resources.<BR> 109 * Should only be called once! 110 * 111 * PRE-Condition: This is the first function call to WSM 112 * 113 * POST-Condition: All WSM resources are initialized 114 * 115 * IN: wsmOpts 116 * WSM options, valid options are: 117 * <UL> 118 * <LI> tbd 119 * </UL> 120 * 121 * OUT: wsmH 122 * Handle to new buffer 123 * 124 * RETURN: SML_ERR_OK, if O.K. 125 * SML_ERR_INVALID_OPTIONS, if wsmOpts is not valid 126 * SML_ERR_NOT_ENOUGH_SPACE, if not enough available memory 127 * SML_ERR_WRONG_USAGE, if wsmInit was already called 128 */ 129 Ret_t wsmInit (const WsmOptions_t *wsmOpts); 130 131 132 /** 133 * FUNCTION: wsmCreate 134 * 135 * Creates and opens a new buffer with name bufName and size bufSize.<BR> 136 * If a buffer with name bufName already exists, the existing buffer 137 * is resized to bufSize. 138 * 139 * PRE-Condition: bufSize > 0 140 * 141 * POST-Condition: handle refers to buffer bufName; BufferSize = size 142 * 143 * IN: bufName 144 * Name of buffer to be created 145 * IN: bufSize 146 * Size of buffer to be created 147 * 148 * OUT: wsmH 149 * Handle to new buffer 150 * 151 * RETURN: SML_ERR_OK, if O.K. 152 * SML_ERR_INVALID_SIZE, if bufSize <= 0 153 * SML_ERR_NOT_ENOUGH_SPACE, if available memory < bufSize 154 * SML_ERR_WSM_BUF_TABLE_FULL, if buffer table is full 155 * SML_ERR_WRONG_USAGE, if wsmInit wasn't called before 156 * 157 * @see wsmDestroy 158 */ 159 Ret_t wsmCreate (String_t bufName, MemSize_t bufSize, MemHandle_t *wsmH); 160 161 162 /** 163 * FUNCTION: wsmOpen 164 * 165 * Open existing buffer with name bufName. 166 * 167 * PRE-Condition: WSM knows bufName 168 * 169 * POST-Condition: wsmH refers to buffer bufName 170 * 171 * IN: bufName 172 * Name of buffer to be opened 173 * 174 * OUT: wsmH 175 * Handle to new buffer 176 * 177 * RETURN: SML_ERR_OK, if O.K. 178 * SML_WRONG_PARAM, if bufName is unknown 179 * 180 * @see wsmClose 181 */ 182 Ret_t wsmOpen (String_t bufName, MemHandle_t *wsmH); 183 184 185 /** 186 * FUNCTION: wsmClose 187 * 188 * Close an open buffer. 189 * 190 * PRE-Condition: handle is valid; handle is unlocked 191 * 192 * POST-Condition: handle is not known to WSM any more 193 * 194 * IN: wsmH 195 * Handle to the open buffer 196 * 197 * RETURN: SML_ERR_OK, if O.K. 198 * SML_ERR_INVALID_HANDLE, if handle was invalid 199 * SML_ERR_WRONG_USAGE, if handle was still locked 200 * 201 * @see wsmOpen 202 */ 203 Ret_t wsmClose (MemHandle_t wsmH); 204 205 206 /** 207 * FUNCTION: wsmDestroy 208 * 209 * Destroy existing buffer with name bufName. 210 * 211 * PRE-Condition: WSM knows bufName; handle is unlocked 212 * 213 * POST-Condition: buffer is not known to WSM any more; all resources 214 * connected to this buffer are freed 215 * 216 * IN: bufName 217 * Name of buffer to be opened 218 * 219 * RETURN: SML_ERR_OK, if O.K. 220 * SML_ERR_WRONG_PARAM, if bufName is unknown to WSM 221 * SML_ERR_WRONG_USAGE, if handle was still locked 222 * 223 * @see wsmCreate 224 */ 225 Ret_t wsmDestroy (String_t bufName); 226 227 228 /** 229 * FUNCTION: wsmTerminate 230 * 231 * Terminate WSM; free all buffers and resources. 232 * 233 * PRE-Condition: all handles must be unlocked 234 * 235 * POST-Condition: all resources are freed 236 * 237 * RETURN: SML_ERR_OK, if O.K. 238 * SML_ERR_WRONG_USAGE, if a handle was still locked 239 * 240 */ 241 Ret_t wsmTerminate (void); 242 243 /** 244 * FUNCTION: wsmProcessedBytes 245 * 246 * Tell Workspace Manager the number of bytes already processed. 247 * 248 * PRE-Condition: handle is locked; handle is valid; 249 * noBytes <= wsmGetUsedSize 250 * 251 * POST-Condition: noBytes starting at wsmGetPtr() position are deleted; 252 * remaining bytes are copied to 253 * wsmGetPtr(SML_FIRST_FREE_ITEM) position; 254 * wsmGetUsedSize -= noBytes; wsmGetFreeSize += noBytes 255 * 256 * IN: wsmH 257 * Handle to the open buffer 258 * IN: noBytes 259 * Number of bytes already processed from buffer. 260 * 261 * RETURN: SML_ERR_OK, if O.K. 262 * SML_ERR_INVALID_HANDLE, if handle was invalid 263 * SML_ERR_WRONG_USAGE, if handle was not locked 264 * SML_ERR_INVALID_SIZE, if noBytes > wsmGetUsedSize 265 * 266 * @see wsmGetFreeSize 267 */ 268 Ret_t wsmProcessedBytes (MemHandle_t wsmH, MemSize_t noBytes); 269 270 271 /** 272 * FUNCTION: wsmLockH 273 * 274 * Locks handle wsmH and get a pointer to the contents of wsmH. <BR> 275 * RequestedPos describes the position in the buffer to which the returned 276 * pointer should point to. Valid values are: 277 * <UL> 278 * <LI> SML_FIRST_DATA_ITEM 279 * <LI> SML_FIRST_FREE_ITEM 280 * </UL> 281 * 282 * PRE-Condition: handle is unlocked; handle is valid 283 * 284 * POST-Condition: handle is locked; points to first data item, 285 * or first free item. 286 * 287 * IN: wsmH 288 * Handle to the open buffer 289 * IN: requestedPos 290 * Requested position of the returned pointer 291 * <UL> 292 * <LI> SML_FIRST_DATA_ITEM : points to first data entry 293 * <LI> SML_FIRST_FREE_ITEM : points to first free entry 294 * </UL> 295 * 296 * OUT: pMem 297 * Pointer to requested memory 298 * 299 * RETURN: SML_ERR_OK, if O.K. 300 * SML_ERR_INVALID_HANDLE, if handle was invalid 301 * SML_ERR_WRONG_USAGE, if handle was still locked 302 * SML_ERR_UNSPECIFIC, if requested position is unknown, or lock failed 303 * 304 * @see wsmUnlockH 305 */ 306 Ret_t wsmLockH (MemHandle_t wsmH, SmlBufPtrPos_t requestedPos, 307 MemPtr_t *pMem); 308 309 310 /** 311 * FUNCTION: wsmGetFreeSize 312 * 313 * Returns the remaining unused bytes in the buffer. 314 * 315 * PRE-Condition: handle is valid 316 * 317 * POST-Condition: wsmGetFreeSize = BufferSize - wsmGetUsedSize 318 * 319 * IN: wsmH 320 * Handle to the open buffer 321 * 322 * OUT: freeSize 323 * Number of bytes which are unused in this buffer 324 * 325 * RETURN: SML_ERR_OK, if O.K. 326 * SML_ERR_INVALID_HANDLE, if handle was invalid 327 * 328 * @see wsmGetUsedSize 329 * @see wsmProcessedBytes 330 */ 331 Ret_t wsmGetFreeSize(MemHandle_t wsmH, MemSize_t *freeSize); 332 333 334 /** 335 * FUNCTION: wsmGetUsedSize 336 * 337 * Returns the number of bytes used in the buffer. 338 * 339 * PRE-Condition: handle is valid 340 * 341 * POST-Condition: usedSize = BufferSize - wsmGetFreeSize 342 * 343 * IN: wsmH 344 * Handle to the open buffer 345 * 346 * OUT: usedSize 347 * Number of bytes which are already used in this buffer 348 * 349 * RETURN: SML_ERR_OK, if O.K. 350 * SML_ERR_INVALID_HANDLE, if handle was invalid 351 * 352 * @see wsmGetFreeSize 353 * @see wsmSetUsedSize 354 */ 355 Ret_t wsmGetUsedSize(MemHandle_t wsmH, MemSize_t *usedSize); 356 357 358 /** 359 * FUNCTION: wsmUnlockH 360 * 361 * Unlock handle wsmH. <BR> 362 * After this call all pointers to this memory handle are invalid 363 * and should no longer be used. 364 * 365 * PRE-Condition: handle is locked; handle is valid 366 * 367 * POST-Condition: handle is unlocked 368 * 369 * OUT: wsmH 370 * Handle to unlock 371 * 372 * RETURN: SML_ERR_OK, if O.K. 373 * SML_ERR_INVALID_HANDLE, if handle was invalid 374 * SML_ERR_WRONG_USAGE, if handle was not locked 375 * SML_ERR_UNSPECIFIC, unlock failed 376 * 377 * @see wsmLockH 378 */ 379 Ret_t wsmUnlockH (MemHandle_t wsmH); 380 381 382 /** 383 * FUNCTION: wsmSetUsedSize 384 * 385 * Tell Workspace how many data were written into buffer. 386 * 387 * PRE-Condition: handle is valid; usedSize <= wsmGetFreeSize; handle is 388 * locked 389 * 390 * POST-Condition: wsmGetUsedSize += usedSize; wsmGetFreeSize -= usedSize; 391 * instancePtr += usedSize; 392 * 393 * IN: wsmH 394 * Handle to the open buffer 395 * IN: usedSize 396 * Number of bytes which were written into buffer 397 * 398 * RETURN: SML_ERR_OK, if O.K. 399 * SML_ERR_INVALID_HANDLE, if handle was invalid 400 * SML_ERR_INVALID_SIZE, if usedSize <= wsmGetFreeSize 401 * 402 * @see wsmGetUsedSize 403 */ 404 Ret_t wsmSetUsedSize (MemHandle_t wsmH, MemSize_t usedSize); 405 406 /** 407 * FUNCTION: wsmReset 408 * 409 * Reset the Workspace 410 * 411 * PRE-Condition: - 412 * 413 * POST-Condition: all data is lost. The FirstFree Position equals 414 * the First Data position 415 * 416 * IN: wsmH 417 * Handle to the open buffer 418 * 419 * RETURN: SML_ERR_OK, if O.K. 420 * 421 */ 422 Ret_t wsmReset (MemHandle_t wsmH) ; 423 424 #endif // !defined(NOWSM) 425 426 427 #endif 428
