Back to index

lightning-sunbird  0.9+nobinonly
jsxdrapi.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
00002  * vim: set ts=8 sw=4 et tw=78:
00003  *
00004  * ***** BEGIN LICENSE BLOCK *****
00005  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00006  *
00007  * The contents of this file are subject to the Mozilla Public License Version
00008  * 1.1 (the "License"); you may not use this file except in compliance with
00009  * the License. You may obtain a copy of the License at
00010  * http://www.mozilla.org/MPL/
00011  *
00012  * Software distributed under the License is distributed on an "AS IS" basis,
00013  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00014  * for the specific language governing rights and limitations under the
00015  * License.
00016  *
00017  * The Original Code is Mozilla Communicator client code, released
00018  * March 31, 1998.
00019  *
00020  * The Initial Developer of the Original Code is
00021  * Netscape Communications Corporation.
00022  * Portions created by the Initial Developer are Copyright (C) 1998
00023  * the Initial Developer. All Rights Reserved.
00024  *
00025  * Contributor(s):
00026  *
00027  * Alternatively, the contents of this file may be used under the terms of
00028  * either of the GNU General Public License Version 2 or later (the "GPL"),
00029  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00030  * in which case the provisions of the GPL or the LGPL are applicable instead
00031  * of those above. If you wish to allow use of your version of this file only
00032  * under the terms of either the GPL or the LGPL, and not to allow others to
00033  * use your version of this file under the terms of the MPL, indicate your
00034  * decision by deleting the provisions above and replace them with the notice
00035  * and other provisions required by the GPL or the LGPL. If you do not delete
00036  * the provisions above, a recipient may use your version of this file under
00037  * the terms of any one of the MPL, the GPL or the LGPL.
00038  *
00039  * ***** END LICENSE BLOCK ***** */
00040 
00041 #ifndef jsxdrapi_h___
00042 #define jsxdrapi_h___
00043 
00044 /*
00045  * JS external data representation interface API.
00046  *
00047  * The XDR system is comprised of three major parts:
00048  *
00049  * - the state serialization/deserialization APIs, which allow consumers
00050  *   of the API to serialize JS runtime state (script bytecodes, atom maps,
00051  *   object graphs, etc.) for later restoration.  These portions
00052  *   are implemented in various appropriate files, such as jsscript.c
00053  *   for the script portions and jsobj.c for object state.
00054  * - the callback APIs through which the runtime requests an opaque
00055  *   representation of a native object, and through which the runtime
00056  *   constructs a live native object from an opaque representation. These
00057  *   portions are the responsibility of the native object implementor.
00058  * - utility functions for en/decoding of primitive types, such as
00059  *   JSStrings.  This portion is implemented in jsxdrapi.c.
00060  *
00061  * Spiritually guided by Sun's XDR, where appropriate.
00062  */
00063 
00064 #include "jspubtd.h"
00065 #include "jsprvtd.h"
00066 
00067 JS_BEGIN_EXTERN_C
00068 
00069 /* We use little-endian byteorder for all encoded data */
00070 
00071 #if defined IS_LITTLE_ENDIAN
00072 #define JSXDR_SWAB32(x) x
00073 #define JSXDR_SWAB16(x) x
00074 #elif defined IS_BIG_ENDIAN
00075 #define JSXDR_SWAB32(x) (((uint32)(x) >> 24) |                                \
00076                          (((uint32)(x) >> 8) & 0xff00) |                      \
00077                          (((uint32)(x) << 8) & 0xff0000) |                    \
00078                          ((uint32)(x) << 24))
00079 #define JSXDR_SWAB16(x) (((uint16)(x) >> 8) | ((uint16)(x) << 8))
00080 #else
00081 #error "unknown byte order"
00082 #endif
00083 
00084 #define JSXDR_ALIGN     4
00085 
00086 typedef enum JSXDRMode {
00087     JSXDR_ENCODE,
00088     JSXDR_DECODE,
00089     JSXDR_FREE
00090 } JSXDRMode;
00091 
00092 typedef enum JSXDRWhence {
00093     JSXDR_SEEK_SET,
00094     JSXDR_SEEK_CUR,
00095     JSXDR_SEEK_END
00096 } JSXDRWhence;
00097 
00098 typedef struct JSXDROps {
00099     JSBool      (*get32)(JSXDRState *, uint32 *);
00100     JSBool      (*set32)(JSXDRState *, uint32 *);
00101     JSBool      (*getbytes)(JSXDRState *, char *, uint32);
00102     JSBool      (*setbytes)(JSXDRState *, char *, uint32);
00103     void *      (*raw)(JSXDRState *, uint32);
00104     JSBool      (*seek)(JSXDRState *, int32, JSXDRWhence);
00105     uint32      (*tell)(JSXDRState *);
00106     void        (*finalize)(JSXDRState *);
00107 } JSXDROps;
00108 
00109 struct JSXDRState {
00110     JSXDRMode   mode;
00111     JSXDROps    *ops;
00112     JSContext   *cx;
00113     JSClass     **registry;
00114     uintN       numclasses;
00115     uintN       maxclasses;
00116     void        *reghash;
00117     void        *userdata;
00118     JSScript    *script;
00119 };
00120 
00121 extern JS_PUBLIC_API(void)
00122 JS_XDRInitBase(JSXDRState *xdr, JSXDRMode mode, JSContext *cx);
00123 
00124 extern JS_PUBLIC_API(JSXDRState *)
00125 JS_XDRNewMem(JSContext *cx, JSXDRMode mode);
00126 
00127 extern JS_PUBLIC_API(void *)
00128 JS_XDRMemGetData(JSXDRState *xdr, uint32 *lp);
00129 
00130 extern JS_PUBLIC_API(void)
00131 JS_XDRMemSetData(JSXDRState *xdr, void *data, uint32 len);
00132 
00133 extern JS_PUBLIC_API(uint32)
00134 JS_XDRMemDataLeft(JSXDRState *xdr);
00135 
00136 extern JS_PUBLIC_API(void)
00137 JS_XDRMemResetData(JSXDRState *xdr);
00138 
00139 extern JS_PUBLIC_API(void)
00140 JS_XDRDestroy(JSXDRState *xdr);
00141 
00142 extern JS_PUBLIC_API(JSBool)
00143 JS_XDRUint8(JSXDRState *xdr, uint8 *b);
00144 
00145 extern JS_PUBLIC_API(JSBool)
00146 JS_XDRUint16(JSXDRState *xdr, uint16 *s);
00147 
00148 extern JS_PUBLIC_API(JSBool)
00149 JS_XDRUint32(JSXDRState *xdr, uint32 *lp);
00150 
00151 extern JS_PUBLIC_API(JSBool)
00152 JS_XDRBytes(JSXDRState *xdr, char *bytes, uint32 len);
00153 
00154 extern JS_PUBLIC_API(JSBool)
00155 JS_XDRCString(JSXDRState *xdr, char **sp);
00156 
00157 extern JS_PUBLIC_API(JSBool)
00158 JS_XDRCStringOrNull(JSXDRState *xdr, char **sp);
00159 
00160 extern JS_PUBLIC_API(JSBool)
00161 JS_XDRString(JSXDRState *xdr, JSString **strp);
00162 
00163 extern JS_PUBLIC_API(JSBool)
00164 JS_XDRStringOrNull(JSXDRState *xdr, JSString **strp);
00165 
00166 extern JS_PUBLIC_API(JSBool)
00167 JS_XDRDouble(JSXDRState *xdr, jsdouble **dp);
00168 
00169 extern JS_PUBLIC_API(JSBool)
00170 JS_XDRValue(JSXDRState *xdr, jsval *vp);
00171 
00172 extern JS_PUBLIC_API(JSBool)
00173 JS_XDRScript(JSXDRState *xdr, JSScript **scriptp);
00174 
00175 extern JS_PUBLIC_API(JSBool)
00176 JS_XDRRegisterClass(JSXDRState *xdr, JSClass *clasp, uint32 *lp);
00177 
00178 extern JS_PUBLIC_API(uint32)
00179 JS_XDRFindClassIdByName(JSXDRState *xdr, const char *name);
00180 
00181 extern JS_PUBLIC_API(JSClass *)
00182 JS_XDRFindClassById(JSXDRState *xdr, uint32 id);
00183 
00184 /*
00185  * Magic numbers.
00186  */
00187 #define JSXDR_MAGIC_SCRIPT_1        0xdead0001
00188 #define JSXDR_MAGIC_SCRIPT_2        0xdead0002
00189 #define JSXDR_MAGIC_SCRIPT_3        0xdead0003
00190 #define JSXDR_MAGIC_SCRIPT_4        0xdead0004
00191 #define JSXDR_MAGIC_SCRIPT_5        0xdead0005
00192 #define JSXDR_MAGIC_SCRIPT_CURRENT  JSXDR_MAGIC_SCRIPT_5
00193 
00194 /*
00195  * Bytecode version number.  Decrement the second term whenever JS bytecode
00196  * changes incompatibly.
00197  *
00198  * This version number should be XDR'ed once near the front of any file or
00199  * larger storage unit containing XDR'ed bytecode and other data, and checked
00200  * before deserialization of bytecode.  If the saved version does not match
00201  * the current version, abort deserialization and invalidate the file.
00202  */
00203 #define JSXDR_BYTECODE_VERSION      (0xb973c0de - 29)
00204 
00205 /*
00206  * Library-private functions.
00207  */
00208 extern JSBool
00209 js_XDRAtom(JSXDRState *xdr, JSAtom **atomp);
00210 
00211 extern JSBool
00212 js_XDRStringAtom(JSXDRState *xdr, JSAtom **atomp);
00213 
00214 /*
00215  * FIXME: This is non-unicode version of js_XDRStringAtom that performs lossy
00216  * conversion. Do not use it in the new code! See bug 325202.
00217  */
00218 extern JSBool
00219 js_XDRCStringAtom(JSXDRState *xdr, JSAtom **atomp);
00220 
00221 JS_END_EXTERN_C
00222 
00223 #endif /* ! jsxdrapi_h___ */