From: Kidong L. <bri...@us...> - 2004-05-24 01:34:34
|
Update of /cvsroot/syncml-ctoolkit/toolkit/src/sml/wsm/inc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10631/src/sml/wsm/inc Modified Files: wsm.h wsm_sm.h Log Message: Modified comments to doxygen-readable Removed duplicated comments Index: wsm_sm.h =================================================================== RCS file: /cvsroot/syncml-ctoolkit/toolkit/src/sml/wsm/inc/wsm_sm.h,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** wsm_sm.h 6 Aug 2002 20:42:51 -0000 1.1 --- wsm_sm.h 24 May 2004 01:33:38 -0000 1.2 *************** *** 1,13 **** ! /*************************************************************************/ ! /* module: SyncML WorkSpace Manager */ ! /* */ ! /* file: WSM_SM.h */ ! /* target system: All */ ! /* target OS: All */ ! /* */ ! /* Description */ ! /* Storage Management for Workspace Manager API <BR> */ ! /* Encapsulates OS dependent parts of WSM. */ ! /*************************************************************************/ --- 1,11 ---- ! /** ! * @file ! * SyncML WorkSpace Manager ! * ! * @target_system All ! * @target_os All ! * @description Storage Management for Workspace Manager API ! * Encapsulates OS dependent parts of WSM. ! */ *************** *** 49,55 **** - /** - * @version @label - */ #ifndef _WSM_SM_H --- 47,50 ---- *************** *** 60,71 **** #ifdef __ANSI_C__ ! /* sbuffer list */ typedef struct smWinList_s { ! char *memName; // name of buffer ! char *winH; // reference to memory block ! MemHandle_t memH; // handle of memory block ! Byte_t locked; // is handle locked? ! MemSize_t memSize; // size of memory block ! struct smWinList_s *next; // next list item } smWinList_t; typedef smWinList_t *WsmSmGlobals_t; --- 55,66 ---- #ifdef __ANSI_C__ ! /** sbuffer list */ typedef struct smWinList_s { ! char *memName; /**< name of buffer */ ! char *winH; /**< reference to memory block */ ! MemHandle_t memH; /**< handle of memory block */ ! Byte_t locked; /**< is handle locked? */ ! MemSize_t memSize; /**< size of memory block */ ! struct smWinList_s *next; /**< next list item */ } smWinList_t; typedef smWinList_t *WsmSmGlobals_t; *************** *** 74,94 **** #ifdef __PALM_OS__ #include <Pilot.h> ! /* dynamic buffer array */ typedef struct smPalm_s { ! Handle smPalmH; // reference to only memory block ! MemHandle_t smMemH; // handle of only memory block ! Byte_t smLocked; // is handle locked? } WsmSmGlobals_t; #endif #ifdef __EPOC_OS__ ! /* sbuffer list */ typedef struct smWinList_s { ! char *memName; // name of buffer ! char *winH; // reference to memory block ! MemHandle_t memH; // handle of memory block ! Byte_t locked; // is handle locked? ! MemSize_t memSize; // size of memory block ! struct smWinList_s *next; // next list item } smWinList_t; typedef smWinList_t *WsmSmGlobals_t; --- 69,89 ---- #ifdef __PALM_OS__ #include <Pilot.h> ! /** dynamic buffer array */ typedef struct smPalm_s { ! Handle smPalmH; /**< reference to only memory block */ ! MemHandle_t smMemH; /**< handle of only memory block */ ! Byte_t smLocked; /**< is handle locked? */ } WsmSmGlobals_t; #endif #ifdef __EPOC_OS__ ! /** sbuffer list */ typedef struct smWinList_s { ! char *memName; /**< name of buffer */ ! char *winH; /**< reference to memory block */ ! MemHandle_t memH; /**< handle of memory block */ ! Byte_t locked; /**< is handle locked? */ ! MemSize_t memSize; /**< size of memory block */ ! struct smWinList_s *next; /**< next list item */ } smWinList_t; typedef smWinList_t *WsmSmGlobals_t; *************** *** 96,288 **** - /** - * FUNCTION: smCreate - * - * Creates a new memory block with name memName and size memSize. - * - * PRE-Condition: OS does not know memName; memSize > 0 - * - * POST-Condition: memName exists with size memSize; - * memH refers to new memory block. - * - * IN: memName - * Name of new memory block - * IN: memSize - * Size of new memory block - * - * OUT: memH - * Handle to new memory block - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_USAGE, if memName is already known to the OS - * SML_ERR_INVALID_SIZE, if memSize <= 0 - * SML_ERR_NOT_ENOUGH_SPACE, if available memory < memSize - * - * @see smDestroy - */ Ret_t smCreate (String_t memName, MemSize_t memSize, MemHandle_t *memH); - - - /** - * FUNCTION: smOpen - * - * Open connection to memory block with name memName. - * - * PRE-Condition: OS does know memName - * - * POST-Condition: memH refers to memory block memName - * - * IN: memName - * Name of memory block to open - * - * OUT: memH - * Handle to opened memory block - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if memName is unknown - * - * @see smClose - */ Ret_t smOpen (String_t memName, MemHandle_t *memH); - - - /** - * FUNCTION: smClose - * - * Close link to memory block. - * - * PRE-Condition: memH is a valid memory block handle; memH is unlocked; - * no pointers to records are in use - * - * POST-Condition: memH is not valid anymore - * - * IN: memH - * Handle to close - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_USAGE, if memH is locked - * - * @see smOpen - */ Ret_t smClose (MemHandle_t memH); - - - /** - * FUNCTION: smDestroy - * - * Remove memory block memName within OS. - * - * PRE-Condition: memName is a valid memory block name; - * memory block is not in use (i.e. no handles and - * pointers to this memory block are in use) - * - * POST-Condition: memName is not a valid memory block name anymore - * - * IN: memName - * Name of memory block to remove - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if memName is unknown - * SML_ERR_WRONG_USAGE, if memory block is still locked - * - * @see smCreate - */ Ret_t smDestroy (String_t memName); - - - /** - * FUNCTION: smLock - * - * Map memory block memH to local address space. - * - * PRE-Condition: memH is a valid handle; memory block is not locked - * - * POST-Condition: pMem points to memory block memH; - * memory block is locked - * - * IN: memH - * Handle to memory block - * - * OUT: pMem - * Pointer to memory block memH mapped in local address space - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if memH is unknown - * SML_ERR_WRONG_USAGE, if memH was already locked - * SML_ERR_UNSPECIFIC, if lock failed - * - * @see smUnlock - */ Ret_t smLock (MemHandle_t memH, MemPtr_t *pMem); - - - /** - * FUNCTION: smUnlock - * - * Free pointer mapped to memH memory block. - * - * PRE-Condition: memH is a valid handle; memory block is locked - * - * POST-Condition: memory block is unlocked - * - * IN: memH - * Handle to memory block - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if memH is unknown - * SML_ERR_WRONG_USAGE, if memH was already unlocked - * SML_ERR_UNSPECIFIC, if unlock failed - * - * @see smLock - */ Ret_t smUnlock (MemHandle_t memH); - - - /** - * FUNCTION: smSetSize - * - * Set size of memory block memH to newSize. - * - * PRE-Condition: memH is a valid handle; newSize > 0; - * memory block is unlocked - * - * POST-Condition: memory block size = newSize - * - * IN: memH - * Handle to memory block - * IN: newSize - * New size of memory block - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if memH is unknown - * SML_ERR_WRONG_USAGE, if memH is locked - * SML_ERR_INVALID_SIZE, if newSize <= 0 - * SML_ERR_NOT_ENOUGH_SPACE, if available memory < newSize - * - * @see smGetSize - */ Ret_t smSetSize (MemHandle_t memH, MemSize_t newSize); - - - /** - * FUNCTION: smGetSize - * - * Get size of memory block memH. - * - * PRE-Condition: memH is a valid handle - * - * POST-Condition: actSize = memory block size - * - * IN: memH - * Handle to memory block - * - * OUT: actSize - * Actual size of memory block - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if memH is unknown - * - * @see smSetSize - */ Ret_t smGetSize (MemHandle_t memH, MemSize_t *actSize); --- 91,101 ---- Index: wsm.h =================================================================== RCS file: /cvsroot/syncml-ctoolkit/toolkit/src/sml/wsm/inc/wsm.h,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -d -r1.2 -r1.3 *** wsm.h 2 May 2003 22:05:08 -0000 1.2 --- wsm.h 24 May 2004 01:33:38 -0000 1.3 *************** *** 1,8 **** ! /*************************************************************************/ ! /* module: SyncML WorkSpace Manager */ ! /* file: WSM.h */ ! /* target system: All */ ! /* target OS: All */ ! /*************************************************************************/ --- 1,11 ---- ! /** ! * @file ! * SyncML WorkSpace Manager ! * ! * @target_system All ! * @target_os All ! * @description Workspace Manager API ! * Manages the SyncML document in memory. ! */ *************** *** 44,54 **** - /** - * Workspace Manager API <BR> - * Manages the SyncML document in memory. - * - * @version @label - * - */ #ifndef _WSM_H --- 47,50 ---- *************** *** 64,68 **** typedef struct WsmOptions_s { ! MemSize_t maxAvailMem; // maximum amount of memory available for all wsm buffers } WsmOptions_t; --- 60,64 ---- typedef struct WsmOptions_s { ! MemSize_t maxAvailMem; /**< maximum amount of memory available for all wsm buffers */ } WsmOptions_t; *************** *** 83,92 **** /** WSM internal buffer structure */ typedef struct WsmBuf_s { ! String_t bufName; // external name of buffer ! MemHandle_t memH; // memory handle ! MemPtr_t pFirstFree; // pointer to first free element in buffer ! MemPtr_t pFirstData; // pointer to first data element in buffer ! MemSize_t size; // size of buffer ! MemSize_t usedBytes; // used bytes in buffer Byte_t flags; } WsmBuf_t; --- 79,88 ---- /** WSM internal buffer structure */ typedef struct WsmBuf_s { ! String_t bufName; /**< external name of buffer */ ! MemHandle_t memH; /**< memory handle */ ! MemPtr_t pFirstFree; /**< pointer to first free element in buffer */ ! MemPtr_t pFirstData; /**< pointer to first data element in buffer */ ! MemSize_t size; /**< size of buffer */ ! MemSize_t usedBytes; /**< used bytes in buffer */ Byte_t flags; } WsmBuf_t; *************** *** 95,427 **** /** WSM globals for use with global Anchor */ typedef struct WsmGlobals_s { ! Ret_t wsmRet; // last WSM return code ! Byte_t initWasCalled; // was wsmInit() called? WsmBuf_t wsmBuf[MAX_WSM_BUFFERS]; ! Short_t wsmIndex; // Index of actual buffer ! WsmSmGlobals_t wsmSm; // WSM_SM global; device dependent! } *WsmGlobalsPtr_t, WsmGlobals_t; - - /** - * FUNCTION: wsmInit - * - * Initializes all Workspace Manager related resources.<BR> - * Should only be called once! - * - * PRE-Condition: This is the first function call to WSM - * - * POST-Condition: All WSM resources are initialized - * - * IN: wsmOpts - * WSM options, valid options are: - * <UL> - * <LI> tbd - * </UL> - * - * OUT: wsmH - * Handle to new buffer - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_OPTIONS, if wsmOpts is not valid - * SML_ERR_NOT_ENOUGH_SPACE, if not enough available memory - * SML_ERR_WRONG_USAGE, if wsmInit was already called - */ Ret_t wsmInit (const WsmOptions_t *wsmOpts); - - - /** - * FUNCTION: wsmCreate - * - * Creates and opens a new buffer with name bufName and size bufSize.<BR> - * If a buffer with name bufName already exists, the existing buffer - * is resized to bufSize. - * - * PRE-Condition: bufSize > 0 - * - * POST-Condition: handle refers to buffer bufName; BufferSize = size - * - * IN: bufName - * Name of buffer to be created - * IN: bufSize - * Size of buffer to be created - * - * OUT: wsmH - * Handle to new buffer - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_SIZE, if bufSize <= 0 - * SML_ERR_NOT_ENOUGH_SPACE, if available memory < bufSize - * SML_ERR_WSM_BUF_TABLE_FULL, if buffer table is full - * SML_ERR_WRONG_USAGE, if wsmInit wasn't called before - * - * @see wsmDestroy - */ Ret_t wsmCreate (String_t bufName, MemSize_t bufSize, MemHandle_t *wsmH); - - - /** - * FUNCTION: wsmOpen - * - * Open existing buffer with name bufName. - * - * PRE-Condition: WSM knows bufName - * - * POST-Condition: wsmH refers to buffer bufName - * - * IN: bufName - * Name of buffer to be opened - * - * OUT: wsmH - * Handle to new buffer - * - * RETURN: SML_ERR_OK, if O.K. - * SML_WRONG_PARAM, if bufName is unknown - * - * @see wsmClose - */ Ret_t wsmOpen (String_t bufName, MemHandle_t *wsmH); - - - /** - * FUNCTION: wsmClose - * - * Close an open buffer. - * - * PRE-Condition: handle is valid; handle is unlocked - * - * POST-Condition: handle is not known to WSM any more - * - * IN: wsmH - * Handle to the open buffer - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_HANDLE, if handle was invalid - * SML_ERR_WRONG_USAGE, if handle was still locked - * - * @see wsmOpen - */ Ret_t wsmClose (MemHandle_t wsmH); - - - /** - * FUNCTION: wsmDestroy - * - * Destroy existing buffer with name bufName. - * - * PRE-Condition: WSM knows bufName; handle is unlocked - * - * POST-Condition: buffer is not known to WSM any more; all resources - * connected to this buffer are freed - * - * IN: bufName - * Name of buffer to be opened - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_PARAM, if bufName is unknown to WSM - * SML_ERR_WRONG_USAGE, if handle was still locked - * - * @see wsmCreate - */ Ret_t wsmDestroy (String_t bufName); - - - /** - * FUNCTION: wsmTerminate - * - * Terminate WSM; free all buffers and resources. - * - * PRE-Condition: all handles must be unlocked - * - * POST-Condition: all resources are freed - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_WRONG_USAGE, if a handle was still locked - * - */ Ret_t wsmTerminate (void); - - /** - * FUNCTION: wsmProcessedBytes - * - * Tell Workspace Manager the number of bytes already processed. - * - * PRE-Condition: handle is locked; handle is valid; - * noBytes <= wsmGetUsedSize - * - * POST-Condition: noBytes starting at wsmGetPtr() position are deleted; - * remaining bytes are copied to - * wsmGetPtr(SML_FIRST_FREE_ITEM) position; - * wsmGetUsedSize -= noBytes; wsmGetFreeSize += noBytes - * - * IN: wsmH - * Handle to the open buffer - * IN: noBytes - * Number of bytes already processed from buffer. - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_HANDLE, if handle was invalid - * SML_ERR_WRONG_USAGE, if handle was not locked - * SML_ERR_INVALID_SIZE, if noBytes > wsmGetUsedSize - * - * @see wsmGetFreeSize - */ Ret_t wsmProcessedBytes (MemHandle_t wsmH, MemSize_t noBytes); ! ! ! /** ! * FUNCTION: wsmLockH ! * ! * Locks handle wsmH and get a pointer to the contents of wsmH. <BR> ! * RequestedPos describes the position in the buffer to which the returned ! * pointer should point to. Valid values are: ! * <UL> ! * <LI> SML_FIRST_DATA_ITEM ! * <LI> SML_FIRST_FREE_ITEM ! * </UL> ! * ! * PRE-Condition: handle is unlocked; handle is valid ! * ! * POST-Condition: handle is locked; points to first data item, ! * or first free item. ! * ! * IN: wsmH ! * Handle to the open buffer ! * IN: requestedPos ! * Requested position of the returned pointer ! * <UL> ! * <LI> SML_FIRST_DATA_ITEM : points to first data entry ! * <LI> SML_FIRST_FREE_ITEM : points to first free entry ! * </UL> ! * ! * OUT: pMem ! * Pointer to requested memory ! * ! * RETURN: SML_ERR_OK, if O.K. ! * SML_ERR_INVALID_HANDLE, if handle was invalid ! * SML_ERR_WRONG_USAGE, if handle was still locked ! * SML_ERR_UNSPECIFIC, if requested position is unknown, or lock failed ! * ! * @see wsmUnlockH ! */ ! Ret_t wsmLockH (MemHandle_t wsmH, SmlBufPtrPos_t requestedPos, ! MemPtr_t *pMem); ! ! ! /** ! * FUNCTION: wsmGetFreeSize ! * ! * Returns the remaining unused bytes in the buffer. ! * ! * PRE-Condition: handle is valid ! * ! * POST-Condition: wsmGetFreeSize = BufferSize - wsmGetUsedSize ! * ! * IN: wsmH ! * Handle to the open buffer ! * ! * OUT: freeSize ! * Number of bytes which are unused in this buffer ! * ! * RETURN: SML_ERR_OK, if O.K. ! * SML_ERR_INVALID_HANDLE, if handle was invalid ! * ! * @see wsmGetUsedSize ! * @see wsmProcessedBytes ! */ Ret_t wsmGetFreeSize(MemHandle_t wsmH, MemSize_t *freeSize); - - - /** - * FUNCTION: wsmGetUsedSize - * - * Returns the number of bytes used in the buffer. - * - * PRE-Condition: handle is valid - * - * POST-Condition: usedSize = BufferSize - wsmGetFreeSize - * - * IN: wsmH - * Handle to the open buffer - * - * OUT: usedSize - * Number of bytes which are already used in this buffer - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_HANDLE, if handle was invalid - * - * @see wsmGetFreeSize - * @see wsmSetUsedSize - */ Ret_t wsmGetUsedSize(MemHandle_t wsmH, MemSize_t *usedSize); - - - /** - * FUNCTION: wsmUnlockH - * - * Unlock handle wsmH. <BR> - * After this call all pointers to this memory handle are invalid - * and should no longer be used. - * - * PRE-Condition: handle is locked; handle is valid - * - * POST-Condition: handle is unlocked - * - * OUT: wsmH - * Handle to unlock - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_HANDLE, if handle was invalid - * SML_ERR_WRONG_USAGE, if handle was not locked - * SML_ERR_UNSPECIFIC, unlock failed - * - * @see wsmLockH - */ Ret_t wsmUnlockH (MemHandle_t wsmH); - - - /** - * FUNCTION: wsmSetUsedSize - * - * Tell Workspace how many data were written into buffer. - * - * PRE-Condition: handle is valid; usedSize <= wsmGetFreeSize; handle is - * locked - * - * POST-Condition: wsmGetUsedSize += usedSize; wsmGetFreeSize -= usedSize; - * instancePtr += usedSize; - * - * IN: wsmH - * Handle to the open buffer - * IN: usedSize - * Number of bytes which were written into buffer - * - * RETURN: SML_ERR_OK, if O.K. - * SML_ERR_INVALID_HANDLE, if handle was invalid - * SML_ERR_INVALID_SIZE, if usedSize <= wsmGetFreeSize - * - * @see wsmGetUsedSize - */ Ret_t wsmSetUsedSize (MemHandle_t wsmH, MemSize_t usedSize); - - /** - * FUNCTION: wsmReset - * - * Reset the Workspace - * - * PRE-Condition: - - * - * POST-Condition: all data is lost. The FirstFree Position equals - * the First Data position - * - * IN: wsmH - * Handle to the open buffer - * - * RETURN: SML_ERR_OK, if O.K. - * - */ Ret_t wsmReset (MemHandle_t wsmH) ; #endif // !defined(NOWSM) - #endif --- 91,116 ---- /** WSM globals for use with global Anchor */ typedef struct WsmGlobals_s { ! Ret_t wsmRet; /**< last WSM return code */ ! Byte_t initWasCalled; /**< was wsmInit() called? */ WsmBuf_t wsmBuf[MAX_WSM_BUFFERS]; ! Short_t wsmIndex; /**< Index of actual buffer */ ! WsmSmGlobals_t wsmSm; /**< WSM_SM global; device dependent! */ } *WsmGlobalsPtr_t, WsmGlobals_t; Ret_t wsmInit (const WsmOptions_t *wsmOpts); Ret_t wsmCreate (String_t bufName, MemSize_t bufSize, MemHandle_t *wsmH); Ret_t wsmOpen (String_t bufName, MemHandle_t *wsmH); Ret_t wsmClose (MemHandle_t wsmH); Ret_t wsmDestroy (String_t bufName); Ret_t wsmTerminate (void); Ret_t wsmProcessedBytes (MemHandle_t wsmH, MemSize_t noBytes); ! Ret_t wsmLockH (MemHandle_t wsmH, SmlBufPtrPos_t requestedPos, MemPtr_t *pMem); Ret_t wsmGetFreeSize(MemHandle_t wsmH, MemSize_t *freeSize); Ret_t wsmGetUsedSize(MemHandle_t wsmH, MemSize_t *usedSize); Ret_t wsmUnlockH (MemHandle_t wsmH); Ret_t wsmSetUsedSize (MemHandle_t wsmH, MemSize_t usedSize); Ret_t wsmReset (MemHandle_t wsmH) ; #endif // !defined(NOWSM) #endif |