1 /* ==================================================================== 2 * The Kannel Software License, Version 1.0 3 * 4 * Copyright (c) 2001-2014 Kannel Group 5 * Copyright (c) 1998-2001 WapIT Ltd. 6 * All rights reserved. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 12 * 1. Redistributions of source code must retain the above copyright 13 * notice, this list of conditions and the following disclaimer. 14 * 15 * 2. Redistributions in binary form must reproduce the above copyright 16 * notice, this list of conditions and the following disclaimer in 17 * the documentation and/or other materials provided with the 18 * distribution. 19 * 20 * 3. The end-user documentation included with the redistribution, 21 * if any, must include the following acknowledgment: 22 * "This product includes software developed by the 23 * Kannel Group (http://www.kannel.org/)." 24 * Alternately, this acknowledgment may appear in the software itself, 25 * if and wherever such third-party acknowledgments normally appear. 26 * 27 * 4. The names "Kannel" and "Kannel Group" must not be used to 28 * endorse or promote products derived from this software without 29 * prior written permission. For written permission, please 30 * contact org@kannel.org. 31 * 32 * 5. Products derived from this software may not be called "Kannel", 33 * nor may "Kannel" appear in their name, without prior written 34 * permission of the Kannel Group. 35 * 36 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 37 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 38 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 39 * DISCLAIMED. IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS 40 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 41 * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 42 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 43 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 44 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 45 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 46 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 47 * ==================================================================== 48 * 49 * This software consists of voluntary contributions made by many 50 * individuals on behalf of the Kannel Group. For more information on 51 * the Kannel Group, please see <http://www.kannel.org/>. 52 * 53 * Portions of this software are based upon software originally written at 54 * WapIT Ltd., Helsinki, Finland for the Kannel project. 55 */ 56 57 /* 58 * 59 * wsbc.h 60 * 61 * Author: Markku Rossi <mtr@iki.fi> 62 * 63 * Copyright (c) 1999-2000 WAPIT OY LTD. 64 * All rights reserved. 65 * 66 * Byte-code handling. 67 * 68 */ 69 70 #ifndef WSBC_H 71 #define WSBC_H 72 73 #include "wsint.h" 74 75 /********************* Types and defintions *****************************/ 76 77 /* The byte-code version numbers. */ 78 #define WS_BC_VERSION_MAJOR 1 79 #define WS_BC_VERSION_MINOR 1 80 #define WS_BC_VERSION (((WS_BC_VERSION_MAJOR - 1) << 4) | WS_BC_VERSION_MINOR) 81 82 /* The maximum length of the byte-code header: the multi-byte encoded 83 length + one byte for the version information. */ 84 #define WS_BC_MAX_HEADER_LEN (WS_MB_UINT32_MAX_ENCODED_LEN + 1) 85 86 /* The string encoding, used in the byte-code data. These are the 87 MIBEnum values, assigned by IANA. For a complete description of 88 the character sets and values, please see the document 89 `rfc/iana/assignments/character-sets'. */ 90 typedef enum 91 { 92 WS_BC_STRING_ENC_ISO_8859_1 = 4, 93 WS_BC_STRING_ENC_UTF8 = 106 94 } WsBcStringEncoding; 95 96 /* Constant types in the BC constants pool. */ 97 #define WS_BC_CONST_INT8 0 98 #define WS_BC_CONST_INT16 1 99 #define WS_BC_CONST_INT32 2 100 #define WS_BC_CONST_FLOAT32 3 101 #define WS_BC_CONST_UTF8_STRING 4 102 #define WS_BC_CONST_EMPTY_STRING 5 103 #define WS_BC_CONST_EXT_ENC_STRING 6 104 #define WS_BC_CONST_FIRST_RESERVED 7 105 106 /* An in-memory byte-code constant. */ 107 108 typedef enum 109 { 110 WS_BC_CONST_TYPE_INT, 111 WS_BC_CONST_TYPE_FLOAT32, 112 WS_BC_CONST_TYPE_FLOAT32_NAN, 113 WS_BC_CONST_TYPE_FLOAT32_POSITIVE_INF, 114 WS_BC_CONST_TYPE_FLOAT32_NEGATIVE_INF, 115 WS_BC_CONST_TYPE_UTF8_STRING, 116 WS_BC_CONST_TYPE_EMPTY_STRING 117 } WsBcConstantType; 118 119 struct WsBcConstantRec 120 { 121 WsBcConstantType type; 122 123 union 124 { 125 WsInt32 v_int; 126 WsFloat v_float; 127 WsUtf8String v_string; 128 } u; 129 }; 130 131 typedef struct WsBcConstantRec WsBcConstant; 132 133 /* Pragma types in the BC pragma pool. */ 134 #define WS_BC_PRAGMA_ACCESS_DOMAIN 0 135 #define WS_BC_PRAGMA_ACCESS_PATH 1 136 #define WS_BC_PRAGMA_USER_AGENT_PROPERTY 2 137 #define WS_BC_PRAGMA_USER_AGENT_PROPERTY_AND_SCHEME 3 138 #define WS_BC_PRAGMA_FIRST_RESERVED 4 139 140 /* An in-memory byte-code pragma. */ 141 142 typedef enum 143 { 144 WS_BC_PRAGMA_TYPE_ACCESS_DOMAIN, 145 WS_BC_PRAGMA_TYPE_ACCESS_PATH, 146 WS_BC_PRAGMA_TYPE_USER_AGENT_PROPERTY, 147 WS_BC_PRAGMA_TYPE_USER_AGENT_PROPERTY_AND_SCHEME 148 } WsBcPragmaType; 149 150 struct WsBcPragmaRec 151 { 152 WsBcPragmaType type; 153 154 WsUInt16 index_1; 155 WsUInt16 index_2; 156 WsUInt16 index_3; 157 }; 158 159 typedef struct WsBcPragmaRec WsBcPragma; 160 161 /* An in-memory byte-code function name. */ 162 struct WsBcFunctionNameRec 163 { 164 /* Index to the function pool. */ 165 WsUInt8 index; 166 167 /* The name of the function as a 7 bit ASCII. This is as-is in the 168 UTF-8 format. */ 169 char *name; 170 }; 171 172 typedef struct WsBcFunctionNameRec WsBcFunctionName; 173 174 /* An in-memory byte-code function. */ 175 struct WsBcFunctionRec 176 { 177 WsUInt8 num_arguments; 178 WsUInt8 num_locals; 179 WsUInt32 code_size; 180 unsigned char *code; 181 }; 182 183 typedef struct WsBcFunctionRec WsBcFunction; 184 185 /* An in-memory byte-code file. */ 186 struct WsBcRec 187 { 188 /* How the strings are encoded in linearization. */ 189 WsBcStringEncoding string_encoding; 190 191 /* Constant pool. In this structure, all strings are in UTF-8 192 format. However, they can be converted to different formats - if 193 requested - when linearizing the byte-code. */ 194 WsUInt16 num_constants; 195 WsBcConstant *constants; 196 197 /* Pragma pool. */ 198 WsUInt16 num_pragmas; 199 WsBcPragma *pragmas; 200 201 /* Function pool. */ 202 203 WsUInt8 num_function_names; 204 WsBcFunctionName *function_names; 205 206 WsUInt8 num_functions; 207 WsBcFunction *functions; 208 }; 209 210 typedef struct WsBcRec WsBc; 211 212 /********************* Manipulating byte-code structure *****************/ 213 214 /* Allocate a new byte-code structure. The argument `string_encoding' 215 specifies the encoding that is used for strings. The function 216 returns NULL if the allocation failed. */ 217 WsBc *ws_bc_alloc(WsBcStringEncoding string_encoding); 218 219 /* Free the byte-code structure `bc' and all its internally allocated 220 data structures. The byte-code handle `bc' should not be used 221 after this function. */ 222 void ws_bc_free(WsBc *bc); 223 224 /* Encode the byte-code structure `bc' into a linearized binary 225 byte-code blob. The function returns WS_TRUE if the encoding was 226 successful of WS_FALSE otherwise. The result blob is returned in 227 `data_return' and its length is returned in `data_len_return'. The 228 returned byte-code block must be freed with the ws_bc_data_free() 229 function. You *must* not free it with ws_free() since it will 230 corrupt the heap. */ 231 WsBool ws_bc_encode(WsBc *bc, unsigned char **data_return, 232 size_t *data_len_return); 233 234 /* Free a byte-code data `data', returned by the ws_bc_encode() 235 function. */ 236 void ws_bc_data_free(unsigned char *data); 237 238 /* Decode the byte-code data `data' into an in-memory byte-code 239 structure. The function returns the byte-code structure or NULL if 240 the decoding fails. The argument `data_len' specfies the length of 241 the byte-code data `data'. The returned byte-code structure must 242 be freed with the ws_bc_free() function when it is not needed 243 anymore. */ 244 WsBc *ws_bc_decode(const unsigned char *data, size_t data_len); 245 246 /********************* Adding constant elements *************************/ 247 248 /* Add an integer constant `value' to the constant pool of the 249 byte-code structure `bc'. The index of the constant is returned in 250 `index_return'. The function returns WS_TRUE if the operation was 251 successful or WS_FALSE otherwise (out of memory). */ 252 WsBool ws_bc_add_const_int(WsBc *bc, WsUInt16 *index_return, 253 WsInt32 value); 254 255 /* Add a floating point constant `value' to the constant pool of the 256 byte-code structure `bc'. */ 257 WsBool ws_bc_add_const_float(WsBc *bc, WsUInt16 *index_return, WsFloat value); 258 259 /* Add an UTF-8 encoded string to the constant pool of the byte-code 260 structure `bc'. */ 261 WsBool ws_bc_add_const_utf8_string(WsBc *bc, WsUInt16 *index_return, 262 const unsigned char *data, size_t len); 263 264 /* Add an empty string to the constant pool of the byte-code structure 265 `bc'. */ 266 WsBool ws_bc_add_const_empty_string(WsBc *bc, WsUInt16 *index_return); 267 268 /********************* Adding pragmas ***********************************/ 269 270 /* Add an access control specifier pragma to the constant and pragma 271 pools of the byte-code structure `bc'. The argument `domain' has 272 `domain_len' bytes of UTF-8 data specifying the access domain. */ 273 WsBool ws_bc_add_pragma_access_domain(WsBc *bc, 274 const unsigned char *domain, 275 size_t domain_len); 276 277 /* Add an access control specifier pragma to the constant and pragma 278 pools of the byte-code structure `bc'. The argument `path' has 279 `path_len' bytes of UTF-8 data specifying the access path. */ 280 WsBool ws_bc_add_pragma_access_path(WsBc *bc, 281 const unsigned char *path, 282 size_t path_len); 283 284 /* Add a use agent property pragma to the constant and pragma pools of 285 the byte-code structure `bc'. The arguments `name' and `property' 286 are UTF-8 encoded use agent property. */ 287 WsBool ws_bc_add_pragma_user_agent_property(WsBc *bc, 288 const unsigned char *name, 289 size_t name_len, 290 const unsigned char *property, 291 size_t property_len); 292 293 /* Add a use agent property pragma to the constant and pragma pools of 294 the byte-code structure `bc'. The arguments `name', `property', 295 and `scheme' are UTF-8 encoded use agent property and scheme. */ 296 WsBool ws_bc_add_pragma_user_agent_property_and_scheme( 297 WsBc *bc, 298 const unsigned char *name, 299 size_t name_len, 300 const unsigned char *property, 301 size_t property_len, 302 const unsigned char *scheme, 303 size_t scheme_len); 304 305 /********************* Adding functions *********************************/ 306 307 /* Add a new function to the function pool of the byte-code structure 308 `bc'. The argument `name' specifies the name of the function for 309 external functions. For internal functions, the `name' argument 310 must be NULL. The argument `num_arguments' specifies the number of 311 arguments the function takes. The argument `num_locals' specifies 312 how many local variables the function needs. The byte-code of the 313 function is in `code' and it is `code_size' bytes long. The 314 function takes a copy of the byte-code array `code'. The caller 315 can free / modify the original array, pointed by the argument 316 `code', after the function returns. The function returns WS_TRUE 317 if the adding was successful or WS_FALSE otherwise (out of 318 memory). */ 319 WsBool ws_bc_add_function(WsBc *bc, WsUInt8 *index_return, 320 char *name, WsUInt8 num_arguments, 321 WsUInt8 num_locals, WsUInt32 code_size, 322 unsigned char *code); 323 324 #endif /* not WSBC_H */ 325