syncml-ctoolkit-cvs

[Kidong L. <bri...@us...>]

Update of /cvsroot/syncml-ctoolkit/toolkit/src/sml/xlt/inc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10631/src/sml/xlt/inc

Modified Files:
	xltdec.h xltenc.h 
Log Message:
Modified comments to doxygen-readable
Removed duplicated comments



Index: xltenc.h
===================================================================
RCS file: /cvsroot/syncml-ctoolkit/toolkit/src/sml/xlt/inc/xltenc.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** xltenc.h	14 Aug 2003 12:49:35 -0000	1.2
--- xltenc.h	24 May 2004 01:33:39 -0000	1.3
***************
*** 1,8 ****
! /*************************************************************************/
! /* module:          Encoder header file                                  */
! /* file:            xltenc.h                                             */
! /* target system:   All                                                  */
! /* target OS:       All                                                  */   
! /*************************************************************************/
  
  /*
--- 1,9 ----
! /**
!  * @file 
!  * Encoder header file
!  *
!  * @target_system   All
!  * @target_os       All
!  */
  
  /*
***************
*** 60,64 ****
  #endif
  
! //Type for storing encoder information
  typedef struct XltEncoder_s
  {
--- 61,65 ----
  #endif
  
! /** Type for storing encoder information */
  typedef struct XltEncoder_s
  {
***************
*** 73,188 ****
  
  
- /**
-  * FUNCTION: smlXltEncInit
-  *
-  * Initializes an XML buffer; Creates XML code for the SyncHdr
-  * and appends it to the buffer.
-  * Returns 0 if operation was successful.
-  *
-  * PRE-Condition:   no memory should be allocated for ppEncoder (should be NULL)
-  *                  pHeader has to contain a valid SyncHdr structure
-  *                  pBufEnd must point to the end of the (WB)XML buffer
-  *                  ppBufPos has to be initialized to the start point of the
-  *                  (WB)XML buffer.
-  *                  
-  *
-  * POST-Condition:  After the function call ppBufPos points to the
-  *                  first free byte in the buffer behind the (WB)XML document
-  *
-  * IN:              enc, the encoding constant (SML_WBXML or SML_XML)
-  *                  pHeader, the SyncML header structure
-  *                  pBufEnd, pointer to the end of the buffer to write on
-  *                  %%% luz:2003-07-31: vers must be the SyncML version (for namespaces and FPI's)
-  * 
-  * IN/OUT:          ppBufPos, current position of the bufferpointer
-  *                  ppEncoder, the encoder object       
-  *
-  * RETURN:          shows error codes of function, 
-  *                  0, if OK
-  *                  Possible Error Codes:
-  *                  SML_ERR_XLT_MISSING_CONT            
-  *                  SML_ERR_XLT_BUF_ERR                 
-  *                  SML_ERR_XLT_INVAL_ELEM_TYPE         
-  *                  SML_ERR_XLT_INVAL_LIST_TYPE         
-  *                  SML_ERR_XLT_INVAL_TAG_TYPE          
-  *                  SML_ERR_XLT_CONTENT_SIZE_LENGTH     
-  *                  SML_ERR_XLT_ENC_UNK	               
-  *                  SML_ERR_XLT_INVAL_PROTO_ELEM
-  */
  Ret_t xltEncInit(SmlEncoding_t enc, const SmlSyncHdrPtr_t pHeader, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltEncoderPtr_t *ppEncoder, SmlVersion_t vers);
! 
! /**
!  * FUNCTION: smlXltEncAppend
!  *
!  * Generates XML code and appends it to the XML buffer.
!  *
!  * PRE-Condition:   pEncoder holds the initialized encoder structure.
!  *                  the initialization takes place in the xltEncAppend function
!  *                  pContent has to contain a valid content structure structure
!  *                  pBufEnd must point to the end of the (WB)XML buffer
!  *                  ppBufPos has to be initialized to the start point of the
!  *                  (WB)XML buffer.
!  *                  
!  *
!  * POST-Condition:  After the function call ppBufPos points to the
!  *                  first free byte in the buffer behind the (WB)XML document
!  *
!  * IN:              pEncoder, the encoder object
!  *                  pe, the protocol element (PE_ADD, ...)    
!  *                  pBufEnd, pointer to the end of the buffer to write on
!  *                  pContent, the content to append to the SyncML document
!  * 
!  * IN/OUT:          ppBufPos, current position of the bufferpointer
!  * 
!  * RETURN:          shows error codes of function, 
!  *                  0, if OK
!  *                  Possible Error Codes:
!  *                  SML_ERR_XLT_MISSING_CONT            
!  *                  SML_ERR_XLT_BUF_ERR                 
!  *                  SML_ERR_XLT_INVAL_ELEM_TYPE         
!  *                  SML_ERR_XLT_INVAL_LIST_TYPE         
!  *                  SML_ERR_XLT_INVAL_TAG_TYPE          
!  *                  SML_ERR_XLT_CONTENT_SIZE_LENGTH     
!  *                  SML_ERR_XLT_ENC_UNK	               
!  *                  SML_ERR_XLT_INVAL_PROTO_ELEM
!  */
!  
! Ret_t xltEncAppend(const XltEncoderPtr_t pEncoder, 
!                    SmlProtoElement_t pe, 
!                    const MemPtr_t pBufEnd,
!                    const VoidPtr_t pContent,
!                    MemPtr_t *ppBufPos);
! /**
!  * FUNCTION: smlXltEncTerminate_t pBufEnd, const VoidPtr_t pContent, MemPtr_t *ppBufPos,
!  *
!  * Finalizes the (WB)XML document and returns the size of written bytes to 
!  * the workspace module
!  *
!  * PRE-Condition:   pEncoder holds the initialized encoder structure.
!  *                  the initialization takes place in the xltEncAppend function
!  *                  pBufEnd must point to the end of the (WB)XML buffer
!  *                  ppBufPos has to be initialized to the start point of the
!  *                  (WB)XML buffer.
!  *                  
!  * POST-Condition:  After the function call ppBufPos points to the
!  *                  first free byte in the buffer behind the (WB)XML document
!  *
!  * IN:              pEncoder, the encoder object
!  *                  pBufEnd, pointer to the end of the buffer to write on
!  * 
!  * IN/OUT:          ppBufPos, current position of the bufferpointer
!  * 
!  * RETURN:          shows error codes of function, 
!  *                  0, if OK
!  *                  Possible Error Codes:
!  *                  SML_ERR_XLT_MISSING_CONT            
!  *                  SML_ERR_XLT_BUF_ERR                 
!  *                  SML_ERR_XLT_INVAL_ELEM_TYPE         
!  *                  SML_ERR_XLT_INVAL_LIST_TYPE         
!  *                  SML_ERR_XLT_INVAL_TAG_TYPE          
!  *                  SML_ERR_XLT_CONTENT_SIZE_LENGTH     
!  *                  SML_ERR_XLT_ENC_UNK	               
!  *                  SML_ERR_XLT_INVAL_PROTO_ELEM
!  */
  Ret_t xltEncTerminate(const XltEncoderPtr_t pEncoder, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos);
  Ret_t xltEncReset(XltEncoderPtr_t pEncoder);
--- 74,79 ----
  
  
  Ret_t xltEncInit(SmlEncoding_t enc, const SmlSyncHdrPtr_t pHeader, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos, XltEncoderPtr_t *ppEncoder, SmlVersion_t vers);
! Ret_t xltEncAppend(const XltEncoderPtr_t pEncoder, SmlProtoElement_t pe, const MemPtr_t pBufEnd, const VoidPtr_t pContent, MemPtr_t *ppBufPos);
  Ret_t xltEncTerminate(const XltEncoderPtr_t pEncoder, const MemPtr_t pBufEnd, MemPtr_t *ppBufPos);
  Ret_t xltEncReset(XltEncoderPtr_t pEncoder);

Index: xltdec.h
===================================================================
RCS file: /cvsroot/syncml-ctoolkit/toolkit/src/sml/xlt/inc/xltdec.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** xltdec.h	6 Aug 2002 20:42:51 -0000	1.1
--- xltdec.h	24 May 2004 01:33:39 -0000	1.2
***************
*** 1,8 ****
! /*************************************************************************/
! /* module:         Interface for the XLT Decoder component.              */
! /* file:           XLTDec.h                                              */
! /* target system:  all                                                   */
! /* target OS:      all                                                   */
! /*************************************************************************/
  
  /*
--- 1,11 ----
! /**
!  * @file 
!  * Interface for the XLT Decoder component.
!  *
!  * @target_system  all
!  * @target_os      all
!  * @description Interface for the WBXML and XML decoder component.
!  */
! 
  
  /*
***************
*** 42,49 ****
   */
  
- /**
-  * Interface for the WBXML and XML decoder component.
-  */
- 
  /*************************************************************************/
  /* Definitions                                                           */
--- 45,48 ----
***************
*** 69,109 ****
   * parameter for any public method is the object of which the method is
   * called.
-  * 
-  * The decoder's public methods/attributes are:
-  * 
-  * ATTRIBUTE: charset
-  *
-  * Character set used in the document - this is the MIBEnum value assigned
-  * by the IANA for the character encoding, e.g. "3" for US-ASCII.
-  *
-  * ATTRIBUTE: charsetStr
-  * 
-  * Name of the character set, e.g. "US-ASCII" - valid only when charset == 0.
-  *
-  * ATTRIBUTE: finished
-  *
-  * Indicates whether the decoder has reached the end of the buffer during
-  * the last call to xltDecNext.
-  *
-  * ATTRIBUTE: scanner
-  *
-  * Pointer to the scanner status object used by this decoder. The scanner
-  * will be created during the initialization of the decoder as either a XML
-  * or WBXML scanner.
-  *
-  * 
-  * ATTRIBUTE: tagstack
-  *
-  * The decoder uses an internal stack to check that for every start tag
-  * there is a corresponding end tag.
- 
   */
  typedef struct XltDecoder_s
  {
      Long_t charset;
      String_t charsetStr;
      Flag_t finished;
      Boolean_t final;
      XltDecScannerPtr_t scanner;
      XltUtilStackPtr_t tagstack;
  
--- 68,105 ----
   * parameter for any public method is the object of which the method is
   * called.
   */
  typedef struct XltDecoder_s
  {
+     /** 
+      * Character set used in the document - this is the MIBEnum value assigned
+      * by the IANA for the character encoding, e.g. "3" for US-ASCII.
+      */
      Long_t charset;
+ 
+     /** 
+      * Name of the character set, e.g. "US-ASCII" - valid 
+      * only when charset == 0.
+      */
      String_t charsetStr;
+ 
+     /**
+      * Indicates whether the decoder has reached the end of the buffer during
+      * the last call to xltDecNext.
+      */
      Flag_t finished;
+ 
      Boolean_t final;
+ 
+     /** 
+      * Pointer to the scanner status object used by this decoder. The scanner
+      * will be created during the initialization of the decoder as either a XML
+      * or WBXML scanner.
+      */
      XltDecScannerPtr_t scanner;
+      
+     /** 
+      * The decoder uses an internal stack to check that for every start tag
+      * there is a corresponding end tag.
+      */
      XltUtilStackPtr_t tagstack;
  
***************
*** 111,142 ****
  
  /**
-  * FUNCTION: xltDecInit
-  *
   * Initializes a new decoder object. This function allocates memory for the
   * decoder structure which has to be freed by a call to the decoder's
!  * terminate method when the decoder is not needed anymore.  As part of the
   * initialization the decoder begins decoding the SyncML document to find
   * the SyncHdr element.
   *
!  * PRE-Condition:
!  *                 ppDecoder is NULL
!  *                 ppBufPos
!  *
!  * POST-Condition:
!  *                 ppDecoder points to an initialized decoder status object
!  *
!  * IN:             enc, the document encoding (WBXML or XML)
!  *                 pBufEnd, pointer to the end of the buffer which contains
!  *                     the document
!  *
!  * IN/OUT:         ppBufPos, pointer to the current position within the
!  *                     buffer
!  *
!  * OUT:            ppDecoder, the decoder status object
!  *                 ppSyncHdr, the SyncHdr element
!  *
!  * RETURNS:        SML_ERR_OK, if the decoder could be created and the
!  *                             SmlSyncHdr was found
!  *                             else error code
   */
  Ret_t xltDecInit(const SmlEncoding_t enc,
--- 107,133 ----
  
  /**
   * Initializes a new decoder object. This function allocates memory for the
   * decoder structure which has to be freed by a call to the decoder's
!  * terminate method when the decoder is not needed anymore. As part of the
   * initialization the decoder begins decoding the SyncML document to find
   * the SyncHdr element.
   *
!  * @pre ppDecoder is NULL
!  *      ppBufPos
!  * @post ppDecoder points to an initialized decoder status object
!  * @param enc (IN)
!  *        the document encoding (WBXML or XML)
!  * @param pBufEnd (IN)
!  *        pointer to the end of the buffer which contains the document
!  * @param ppBufPos (IN/OUT)
!  *        pointer to the current position within the buffer
!  * @param ppDecoder (OUT)
!  *        the decoder status object
!  * @param ppSyncHdr (OUT)
!  *        the SyncHdr element
!  * @return 
!  *         - SML_ERR_OK, if the decoder could be created and the
!  *           SmlSyncHdr was found
!  *         - else error code
   */
  Ret_t xltDecInit(const SmlEncoding_t enc,
***************
*** 147,152 ****
  
  /**
-  * FUNCTION: xltDecNext
-  * 
   * Decodes the next protocol element of the given SyncML document. This
   * function creates the data structures detailed in the SMLDtd header file.
--- 138,141 ----
***************
*** 156,181 ****
   * found. In that case pPE is set to SML_PE_UNDEF and pContent is NULL.
   *
!  * PRE-Condition:
!  *                 pDecoder points to a decoder status object initialized
!  *                 by xltDecInit
!  * 
!  * POST-Condition:
!  *                 pPE and pContent describe the next valid protocol
!  *                 element within the SyncML document OR
!  *                 the finished flag of the decoder status object is set
!  * 
!  * IN:             pBufEnd, pointer to the end of the buffer
!  *
!  * IN/OUT:         pDecoder, the decoder status object
!  *                 ppBufPos, pointer to the current position within the
!  *                     buffer before and after the call to xltDecNext
!  *
!  * OUT:            pPE, the type of the protocol element (e.g. SML_PE_ADD)
!  *                 pContent, the data structure for the p.e. cast
!  *                     (e.g. AddPtr_t) to a void pointer
!  * 
!  * RETURN:         SML_ERR_OK, if a valid protocol element was found or if
!  *                 decoder reached the end of the buffer
!  *                 else error code showing where the parsing failed
   */
  Ret_t xltDecNext(XltDecoderPtr_t pDecoder,
--- 145,168 ----
   * found. In that case pPE is set to SML_PE_UNDEF and pContent is NULL.
   *
!  * @pre pDecoder points to a decoder status object initialized by xltDecInit
!  * @post pPE and pContent describe the next valid protocol
!  *       element within the SyncML document OR
!  *       the finished flag of the decoder status object is set
!  * @param pBufEnd (IN)
!  *        pointer to the end of the buffer
!  * @param pDecoder (IN/OUT)
!  *        the decoder status object
!  * @param ppBufPos (IN/OUT)
!  *        pointer to the current position within the
!  *        buffer before and after the call to xltDecNext
!  * @param pPE (OUT) 
!  *        the type of the protocol element (e.g. SML_PE_ADD)
!  * @param pContent (OUT)
!  *        the data structure for the p.e. cast
!  *        (e.g. AddPtr_t) to a void pointer
!  * @return 
!  *         - SML_ERR_OK, if a valid protocol element was found
!  *           or if decoder reached the end of the buffer
!  *         - else error code showing where the parsing failed
   */
  Ret_t xltDecNext(XltDecoderPtr_t pDecoder,
***************
*** 186,205 ****
  
  /**
-  * FUNCTION: xltDecTerminate
-  *
   * Frees the memory allocated by the decoder.
   *
!  * PRE-Condition:
!  *                 pDecoder points to a decoder status object initialized
!  *                 by xltDecInit
!  *
!  * POST-Condition:
!  *                 all memory allocated by the decoder status object is
!  *                 freed
!  *
!  * IN:             pDecoder, the decoder
!  *
!  * RETURN:         SML_ERR_OK, if the memory could be freed
!  *                 else error code
   */
  Ret_t xltDecTerminate(XltDecoderPtr_t pDecoder);
--- 173,185 ----
  
  /**
   * Frees the memory allocated by the decoder.
   *
!  * @pre pDecoder points to a decoder status object initialized by xltDecInit
!  * @post all memory allocated by the decoder status object is freed
!  * @param pDecoder (IN)
!  *        the decoder
!  * @return 
!  *         - SML_ERR_OK, if the memory could be freed
!  *         - else error code
   */
  Ret_t xltDecTerminate(XltDecoderPtr_t pDecoder);
***************
*** 216,223 ****
  #define IS_CONTENT(tok) ((tok)->type == TOK_CONT)
  /**
!  * nextToken and discardToken are just wrappers around the scanner's
!  * nextTok and pushTok methods that do some error checking.
   */
  Ret_t nextToken(XltDecoderPtr_t pDecoder);
  Ret_t discardToken(XltDecoderPtr_t pDecoder);
  /* eof xltdec.c stuff */
--- 196,207 ----
  #define IS_CONTENT(tok) ((tok)->type == TOK_CONT)
  /**
!  * just wrapper around the scanner's
!  * nextTok methods that do some error checking.
   */
  Ret_t nextToken(XltDecoderPtr_t pDecoder);
+ /**
+  * just wrapper around the scanner's
+  * pushTok methods that do some error checking.
+  */
  Ret_t discardToken(XltDecoderPtr_t pDecoder);
  /* eof xltdec.c stuff */