1 /*************************************************************************/ 2 /* module: Interface for the XLT Decoder component. */ 3 /* file: XLTDec.h */ 4 /* target system: all */ 5 /* target OS: all */ 6 /*************************************************************************/ 7 8 /* 9 * Copyright Notice 10 * Copyright (c) Ericsson, IBM, Lotus, Matsushita Communication 11 * Industrial Co., Ltd., Motorola, Nokia, Openwave Systems, Inc., 12 * Palm, Inc., Psion, Starfish Software, Symbian, Ltd. (2001). 13 * All Rights Reserved. 14 * Implementation of all or part of any Specification may require 15 * licenses under third party intellectual property rights, 16 * including without limitation, patent rights (such a third party 17 * may or may not be a Supporter). The Sponsors of the Specification 18 * are not responsible and shall not be held responsible in any 19 * manner for identifying or failing to identify any or all such 20 * third party intellectual property rights. 21 * 22 * THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN ARE PROVIDED 23 * ON AN "AS IS" BASIS WITHOUT WARRANTY OF ANY KIND AND ERICSSON, IBM, 24 * LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO. LTD, MOTOROLA, 25 * NOKIA, PALM INC., PSION, STARFISH SOFTWARE AND ALL OTHER SYNCML 26 * SPONSORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 27 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 28 * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 29 * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT 30 * SHALL ERICSSON, IBM, LOTUS, MATSUSHITA COMMUNICATION INDUSTRIAL CO., 31 * LTD, MOTOROLA, NOKIA, PALM INC., PSION, STARFISH SOFTWARE OR ANY 32 * OTHER SYNCML SPONSOR BE LIABLE TO ANY PARTY FOR ANY LOSS OF 33 * PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF 34 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTAL, 35 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH 36 * THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED 37 * OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. 38 * 39 * The above notice and this paragraph must be included on all copies 40 * of this document that are made. 41 * 42 */ 43 44 /** 45 * Interface for the WBXML and XML decoder component. 46 */ 47 48 /*************************************************************************/ 49 /* Definitions */ 50 /*************************************************************************/ 51 #ifndef _XLT_DEC_H 52 #define _XLT_DEC_H 53 54 #include <smldef.h> 55 #include <smldtd.h> 56 #include <smlerr.h> 57 58 #include "xltdeccom.h" 59 #include "xltutilstack.h" 60 61 #ifdef _cplusplus 62 extern "C" { 63 #endif 64 65 /** 66 * The XLT Decoder Interface consists of a single XltDecoder "object" 67 * (struct) and an creation/initialization function. The XltDecoder 68 * object contains all "public" methods and data structures. The first 69 * parameter for any public method is the object of which the method is 70 * called. 71 * 72 * The decoder's public methods/attributes are: 73 * 74 * ATTRIBUTE: charset 75 * 76 * Character set used in the document - this is the MIBEnum value assigned 77 * by the IANA for the character encoding, e.g. "3" for US-ASCII. 78 * 79 * ATTRIBUTE: charsetStr 80 * 81 * Name of the character set, e.g. "US-ASCII" - valid only when charset == 0. 82 * 83 * ATTRIBUTE: finished 84 * 85 * Indicates whether the decoder has reached the end of the buffer during 86 * the last call to xltDecNext. 87 * 88 * ATTRIBUTE: scanner 89 * 90 * Pointer to the scanner status object used by this decoder. The scanner 91 * will be created during the initialization of the decoder as either a XML 92 * or WBXML scanner. 93 * 94 * 95 * ATTRIBUTE: tagstack 96 * 97 * The decoder uses an internal stack to check that for every start tag 98 * there is a corresponding end tag. 99 100 */ 101 typedef struct XltDecoder_s 102 { 103 Long_t charset; 104 String_t charsetStr; 105 Flag_t finished; 106 Boolean_t final; 107 XltDecScannerPtr_t scanner; 108 XltUtilStackPtr_t tagstack; 109 #ifdef __USE_DMTND__ 110 SmlEncoding_t smlEncoding; 111 SmlEncoding_t tndsEncoding; 112 #endif 113 114 } XltDecoder_t, *XltDecoderPtr_t; 115 116 /** 117 * FUNCTION: xltDecInit 118 * 119 * Initializes a new decoder object. This function allocates memory for the 120 * decoder structure which has to be freed by a call to the decoder's 121 * terminate method when the decoder is not needed anymore. As part of the 122 * initialization the decoder begins decoding the SyncML document to find 123 * the SyncHdr element. 124 * 125 * PRE-Condition: 126 * ppDecoder is NULL 127 * ppBufPos 128 * 129 * POST-Condition: 130 * ppDecoder points to an initialized decoder status object 131 * 132 * IN: enc, the document encoding (WBXML or XML) 133 * pBufEnd, pointer to the end of the buffer which contains 134 * the document 135 * 136 * IN/OUT: ppBufPos, pointer to the current position within the 137 * buffer 138 * 139 * OUT: ppDecoder, the decoder status object 140 * ppSyncHdr, the SyncHdr element 141 * 142 * RETURNS: SML_ERR_OK, if the decoder could be created and the 143 * SmlSyncHdr was found 144 * else error code 145 */ 146 Ret_t xltDecInit(const SmlEncoding_t enc, 147 const MemPtr_t pBufEnd, 148 MemPtr_t *ppBufPos, 149 XltDecoderPtr_t *ppDecoder, 150 SmlSyncHdrPtr_t *ppSyncHdr); 151 152 /** 153 * FUNCTION: xltDecNext 154 * 155 * Decodes the next protocol element of the given SyncML document. This 156 * function creates the data structures detailed in the SMLDtd header file. 157 * It is the responsibility of the SyncML client application to free the 158 * allocated memory after it is done processing the data. 159 * This function sets the decoder's finished flag if no protocol element was 160 * found. In that case pPE is set to SML_PE_UNDEF and pContent is NULL. 161 * 162 * PRE-Condition: 163 * pDecoder points to a decoder status object initialized 164 * by xltDecInit 165 * 166 * POST-Condition: 167 * pPE and pContent describe the next valid protocol 168 * element within the SyncML document OR 169 * the finished flag of the decoder status object is set 170 * 171 * IN: pBufEnd, pointer to the end of the buffer 172 * 173 * IN/OUT: pDecoder, the decoder status object 174 * ppBufPos, pointer to the current position within the 175 * buffer before and after the call to xltDecNext 176 * 177 * OUT: pPE, the type of the protocol element (e.g. SML_PE_ADD) 178 * pContent, the data structure for the p.e. cast 179 * (e.g. AddPtr_t) to a void pointer 180 * 181 * RETURN: SML_ERR_OK, if a valid protocol element was found or if 182 * decoder reached the end of the buffer 183 * else error code showing where the parsing failed 184 */ 185 Ret_t xltDecNext(XltDecoderPtr_t pDecoder, 186 const MemPtr_t pBufEnd, 187 MemPtr_t *ppBufPos, 188 SmlProtoElement_t *pPE, 189 VoidPtr_t *pContent); 190 191 /** 192 * FUNCTION: xltDecTerminate 193 * 194 * Frees the memory allocated by the decoder. 195 * 196 * PRE-Condition: 197 * pDecoder points to a decoder status object initialized 198 * by xltDecInit 199 * 200 * POST-Condition: 201 * all memory allocated by the decoder status object is 202 * freed 203 * 204 * IN: pDecoder, the decoder 205 * 206 * RETURN: SML_ERR_OK, if the memory could be freed 207 * else error code 208 */ 209 Ret_t xltDecTerminate(XltDecoderPtr_t pDecoder); 210 211 212 Ret_t xltDecReset(XltDecoderPtr_t pDecoder); 213 214 /* T.K. moved here from xltdec.c for use in sub-DTD parsing */ 215 #define IS_START(tok) ((tok)->type == TOK_TAG_START) 216 #define IS_END(tok) ((tok)->type == TOK_TAG_END) 217 #define IS_EMPTY(tok) ((tok)->type == TOK_TAG_EMPTY) 218 #define IS_TAG(tok) (IS_START(tok) || IS_EMPTY(tok) || IS_END(tok)) 219 #define IS_START_OR_EMPTY(tok) (IS_START(tok) || IS_EMPTY(tok)) 220 #define IS_CONTENT(tok) ((tok)->type == TOK_CONT) 221 /** 222 * nextToken and discardToken are just wrappers around the scanner's 223 * nextTok and pushTok methods that do some error checking. 224 */ 225 Ret_t nextToken(XltDecoderPtr_t pDecoder); 226 Ret_t discardToken(XltDecoderPtr_t pDecoder); 227 /* eof xltdec.c stuff */ 228 229 #ifdef __SML_WBXML__ 230 /*Added by w21034 begin*/ 231 Ret_t wbxml2xmlInternal(unsigned char *bufIn, int bufInLen, unsigned char *bufOut, int * bufOutLen); 232 /*Added by w21034 end*/ 233 #endif 234 235 236 #ifdef _cplusplus 237 } 238 #endif 239 240 #endif 241
