1 /*************************************************************************/ 2 /* module: SyncML WorkSpace Manager */ 3 /* */ 4 /* file: WSM_SM.h */ 5 /* target system: All */ 6 /* target OS: All */ 7 /* */ 8 /* Description */ 9 /* Storage Management for Workspace Manager API <BR> */ 10 /* Encapsulates OS dependent parts of WSM. */ 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 /** 52 * @version @label 53 */ 54 55 #ifndef _WSM_SM_H 56 #define _WSM_SM_H 57 58 #include <smldef.h> 59 60 61 #ifdef __ANSI_C__ 62 /* sbuffer list */ 63 typedef struct smWinList_s { 64 char *memName; // name of buffer 65 char *winH; // reference to memory block 66 MemHandle_t memH; // handle of memory block 67 Byte_t locked; // is handle locked? 68 MemSize_t memSize; // size of memory block 69 struct smWinList_s *next; // next list item 70 } smWinList_t; 71 typedef smWinList_t *WsmSmGlobals_t; 72 #endif 73 74 #ifdef __PALM_OS__ 75 #include <Pilot.h> 76 /* dynamic buffer array */ 77 typedef struct smPalm_s { 78 Handle smPalmH; // reference to only memory block 79 MemHandle_t smMemH; // handle of only memory block 80 Byte_t smLocked; // is handle locked? 81 } WsmSmGlobals_t; 82 #endif 83 84 #ifdef __EPOC_OS__ 85 /* sbuffer list */ 86 typedef struct smWinList_s { 87 char *memName; // name of buffer 88 char *winH; // reference to memory block 89 MemHandle_t memH; // handle of memory block 90 Byte_t locked; // is handle locked? 91 MemSize_t memSize; // size of memory block 92 struct smWinList_s *next; // next list item 93 } smWinList_t; 94 typedef smWinList_t *WsmSmGlobals_t; 95 #endif 96 97 98 /** 99 * FUNCTION: smCreate 100 * 101 * Creates a new memory block with name memName and size memSize. 102 * 103 * PRE-Condition: OS does not know memName; memSize > 0 104 * 105 * POST-Condition: memName exists with size memSize; 106 * memH refers to new memory block. 107 * 108 * IN: memName 109 * Name of new memory block 110 * IN: memSize 111 * Size of new memory block 112 * 113 * OUT: memH 114 * Handle to new memory block 115 * 116 * RETURN: SML_ERR_OK, if O.K. 117 * SML_ERR_WRONG_USAGE, if memName is already known to the OS 118 * SML_ERR_INVALID_SIZE, if memSize <= 0 119 * SML_ERR_NOT_ENOUGH_SPACE, if available memory < memSize 120 * 121 * @see smDestroy 122 */ 123 Ret_t smCreate (String_t memName, MemSize_t memSize, MemHandle_t *memH); 124 125 126 /** 127 * FUNCTION: smOpen 128 * 129 * Open connection to memory block with name memName. 130 * 131 * PRE-Condition: OS does know memName 132 * 133 * POST-Condition: memH refers to memory block memName 134 * 135 * IN: memName 136 * Name of memory block to open 137 * 138 * OUT: memH 139 * Handle to opened memory block 140 * 141 * RETURN: SML_ERR_OK, if O.K. 142 * SML_ERR_WRONG_PARAM, if memName is unknown 143 * 144 * @see smClose 145 */ 146 Ret_t smOpen (String_t memName, MemHandle_t *memH); 147 148 149 /** 150 * FUNCTION: smClose 151 * 152 * Close link to memory block. 153 * 154 * PRE-Condition: memH is a valid memory block handle; memH is unlocked; 155 * no pointers to records are in use 156 * 157 * POST-Condition: memH is not valid anymore 158 * 159 * IN: memH 160 * Handle to close 161 * 162 * RETURN: SML_ERR_OK, if O.K. 163 * SML_ERR_WRONG_USAGE, if memH is locked 164 * 165 * @see smOpen 166 */ 167 Ret_t smClose (MemHandle_t memH); 168 169 170 /** 171 * FUNCTION: smDestroy 172 * 173 * Remove memory block memName within OS. 174 * 175 * PRE-Condition: memName is a valid memory block name; 176 * memory block is not in use (i.e. no handles and 177 * pointers to this memory block are in use) 178 * 179 * POST-Condition: memName is not a valid memory block name anymore 180 * 181 * IN: memName 182 * Name of memory block to remove 183 * 184 * RETURN: SML_ERR_OK, if O.K. 185 * SML_ERR_WRONG_PARAM, if memName is unknown 186 * SML_ERR_WRONG_USAGE, if memory block is still locked 187 * 188 * @see smCreate 189 */ 190 Ret_t smDestroy (String_t memName); 191 192 193 /** 194 * FUNCTION: smLock 195 * 196 * Map memory block memH to local address space. 197 * 198 * PRE-Condition: memH is a valid handle; memory block is not locked 199 * 200 * POST-Condition: pMem points to memory block memH; 201 * memory block is locked 202 * 203 * IN: memH 204 * Handle to memory block 205 * 206 * OUT: pMem 207 * Pointer to memory block memH mapped in local address space 208 * 209 * RETURN: SML_ERR_OK, if O.K. 210 * SML_ERR_WRONG_PARAM, if memH is unknown 211 * SML_ERR_WRONG_USAGE, if memH was already locked 212 * SML_ERR_UNSPECIFIC, if lock failed 213 * 214 * @see smUnlock 215 */ 216 Ret_t smLock (MemHandle_t memH, MemPtr_t *pMem); 217 218 219 /** 220 * FUNCTION: smUnlock 221 * 222 * Free pointer mapped to memH memory block. 223 * 224 * PRE-Condition: memH is a valid handle; memory block is locked 225 * 226 * POST-Condition: memory block is unlocked 227 * 228 * IN: memH 229 * Handle to memory block 230 * 231 * RETURN: SML_ERR_OK, if O.K. 232 * SML_ERR_WRONG_PARAM, if memH is unknown 233 * SML_ERR_WRONG_USAGE, if memH was already unlocked 234 * SML_ERR_UNSPECIFIC, if unlock failed 235 * 236 * @see smLock 237 */ 238 Ret_t smUnlock (MemHandle_t memH); 239 240 241 /** 242 * FUNCTION: smSetSize 243 * 244 * Set size of memory block memH to newSize. 245 * 246 * PRE-Condition: memH is a valid handle; newSize > 0; 247 * memory block is unlocked 248 * 249 * POST-Condition: memory block size = newSize 250 * 251 * IN: memH 252 * Handle to memory block 253 * IN: newSize 254 * New size of memory block 255 * 256 * RETURN: SML_ERR_OK, if O.K. 257 * SML_ERR_WRONG_PARAM, if memH is unknown 258 * SML_ERR_WRONG_USAGE, if memH is locked 259 * SML_ERR_INVALID_SIZE, if newSize <= 0 260 * SML_ERR_NOT_ENOUGH_SPACE, if available memory < newSize 261 * 262 * @see smGetSize 263 */ 264 Ret_t smSetSize (MemHandle_t memH, MemSize_t newSize); 265 266 267 /** 268 * FUNCTION: smGetSize 269 * 270 * Get size of memory block memH. 271 * 272 * PRE-Condition: memH is a valid handle 273 * 274 * POST-Condition: actSize = memory block size 275 * 276 * IN: memH 277 * Handle to memory block 278 * 279 * OUT: actSize 280 * Actual size of memory block 281 * 282 * RETURN: SML_ERR_OK, if O.K. 283 * SML_ERR_WRONG_PARAM, if memH is unknown 284 * 285 * @see smSetSize 286 */ 287 Ret_t smGetSize (MemHandle_t memH, MemSize_t *actSize); 288 289 #endif 290 291
