js/src/jsxdrapi.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sw=4 et tw=78:
   3  *
   4  * ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version
   8  * 1.1 (the "License"); you may not use this file except in compliance with
   9  * the License. You may obtain a copy of the License at
  10  * http://www.mozilla.org/MPL/
  11  *
  12  * Software distributed under the License is distributed on an "AS IS" basis,
  13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14  * for the specific language governing rights and limitations under the
  15  * License.
  16  *
  17  * The Original Code is Mozilla Communicator client code, released
  18  * March 31, 1998.
  19  *
  20  * The Initial Developer of the Original Code is
  21  * Netscape Communications Corporation.
  22  * Portions created by the Initial Developer are Copyright (C) 1998
  23  * the Initial Developer. All Rights Reserved.
  24  *
  25  * Contributor(s):
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #ifndef jsxdrapi_h___
  42 #define jsxdrapi_h___
  43
  44 /*
  45  * JS external data representation interface API.
  46  *
  47  * The XDR system is comprised of three major parts:
  48  *
  49  * - the state serialization/deserialization APIs, which allow consumers
  50  *   of the API to serialize JS runtime state (script bytecodes, atom maps,
  51  *   object graphs, etc.) for later restoration.  These portions
  52  *   are implemented in various appropriate files, such as jsscript.c
  53  *   for the script portions and jsobj.c for object state.
  54  * - the callback APIs through which the runtime requests an opaque
  55  *   representation of a native object, and through which the runtime
  56  *   constructs a live native object from an opaque representation. These
  57  *   portions are the responsibility of the native object implementor.
  58  * - utility functions for en/decoding of primitive types, such as
  59  *   JSStrings.  This portion is implemented in jsxdrapi.c.
  60  *
  61  * Spiritually guided by Sun's XDR, where appropriate.
  62  */
  63
  64 #include "jspubtd.h"
  65 #include "jsprvtd.h"
  66
  67 JS_BEGIN_EXTERN_C
  68
  69 /* We use little-endian byteorder for all encoded data */
  70
  71 #if defined IS_LITTLE_ENDIAN
  72 #define JSXDR_SWAB32(x) x
  73 #define JSXDR_SWAB16(x) x
  74 #elif defined IS_BIG_ENDIAN
  75 #define JSXDR_SWAB32(x) (((uint32)(x) >> 24) |                                \
  76                          (((uint32)(x) >> 8) & 0xff00) |                      \
  77                          (((uint32)(x) << 8) & 0xff0000) |                    \
  78                          ((uint32)(x) << 24))
  79 #define JSXDR_SWAB16(x) (((uint16)(x) >> 8) | ((uint16)(x) << 8))
  80 #else
  81 #error "unknown byte order"
  82 #endif
  83
  84 #define JSXDR_ALIGN     4
  85
  86 typedef enum JSXDRMode {
  87     JSXDR_ENCODE,
  88     JSXDR_DECODE,
  89     JSXDR_FREE
  90 } JSXDRMode;
  91
  92 typedef enum JSXDRWhence {
  93     JSXDR_SEEK_SET,
  94     JSXDR_SEEK_CUR,
  95     JSXDR_SEEK_END
  96 } JSXDRWhence;
  97
  98 typedef struct JSXDROps {
  99     JSBool      (*get32)(JSXDRState *, uint32 *);
 100     JSBool      (*set32)(JSXDRState *, uint32 *);
 101     JSBool      (*getbytes)(JSXDRState *, char *, uint32);
 102     JSBool      (*setbytes)(JSXDRState *, char *, uint32);
 103     void *      (*raw)(JSXDRState *, uint32);
 104     JSBool      (*seek)(JSXDRState *, int32, JSXDRWhence);
 105     uint32      (*tell)(JSXDRState *);
 106     void        (*finalize)(JSXDRState *);
 107 } JSXDROps;
 108
 109 struct JSXDRState {
 110     JSXDRMode   mode;
 111     JSXDROps    *ops;
 112     JSContext   *cx;
 113     JSClass     **registry;
 114     uintN       numclasses;
 115     uintN       maxclasses;
 116     void        *reghash;
 117     void        *userdata;
 118     JSScript    *script;
 119 };
 120
 121 extern JS_PUBLIC_API(void)
 122 JS_XDRInitBase(JSXDRState *xdr, JSXDRMode mode, JSContext *cx);
 123
 124 extern JS_PUBLIC_API(JSXDRState *)
 125 JS_XDRNewMem(JSContext *cx, JSXDRMode mode);
 126
 127 extern JS_PUBLIC_API(void *)
 128 JS_XDRMemGetData(JSXDRState *xdr, uint32 *lp);
 129
 130 extern JS_PUBLIC_API(void)
 131 JS_XDRMemSetData(JSXDRState *xdr, void *data, uint32 len);
 132
 133 extern JS_PUBLIC_API(uint32)
 134 JS_XDRMemDataLeft(JSXDRState *xdr);
 135
 136 extern JS_PUBLIC_API(void)
 137 JS_XDRMemResetData(JSXDRState *xdr);
 138
 139 extern JS_PUBLIC_API(void)
 140 JS_XDRDestroy(JSXDRState *xdr);
 141
 142 extern JS_PUBLIC_API(JSBool)
 143 JS_XDRUint8(JSXDRState *xdr, uint8 *b);
 144
 145 extern JS_PUBLIC_API(JSBool)
 146 JS_XDRUint16(JSXDRState *xdr, uint16 *s);
 147
 148 extern JS_PUBLIC_API(JSBool)
 149 JS_XDRUint32(JSXDRState *xdr, uint32 *lp);
 150
 151 extern JS_PUBLIC_API(JSBool)
 152 JS_XDRBytes(JSXDRState *xdr, char *bytes, uint32 len);
 153
 154 extern JS_PUBLIC_API(JSBool)
 155 JS_XDRCString(JSXDRState *xdr, char **sp);
 156
 157 extern JS_PUBLIC_API(JSBool)
 158 JS_XDRCStringOrNull(JSXDRState *xdr, char **sp);
 159
 160 extern JS_PUBLIC_API(JSBool)
 161 JS_XDRString(JSXDRState *xdr, JSString **strp);
 162
 163 extern JS_PUBLIC_API(JSBool)
 164 JS_XDRStringOrNull(JSXDRState *xdr, JSString **strp);
 165
 166 extern JS_PUBLIC_API(JSBool)
 167 JS_XDRDouble(JSXDRState *xdr, jsdouble **dp);
 168
 169 extern JS_PUBLIC_API(JSBool)
 170 JS_XDRValue(JSXDRState *xdr, jsval *vp);
 171
 172 extern JS_PUBLIC_API(JSBool)
 173 JS_XDRScript(JSXDRState *xdr, JSScript **scriptp);
 174
 175 extern JS_PUBLIC_API(JSBool)
 176 JS_XDRRegisterClass(JSXDRState *xdr, JSClass *clasp, uint32 *lp);
 177
 178 extern JS_PUBLIC_API(uint32)
 179 JS_XDRFindClassIdByName(JSXDRState *xdr, const char *name);
 180
 181 extern JS_PUBLIC_API(JSClass *)
 182 JS_XDRFindClassById(JSXDRState *xdr, uint32 id);
 183
 184 /*
 185  * Magic numbers.
 186  */
 187 #define JSXDR_MAGIC_SCRIPT_1        0xdead0001
 188 #define JSXDR_MAGIC_SCRIPT_2        0xdead0002
 189 #define JSXDR_MAGIC_SCRIPT_3        0xdead0003
 190 #define JSXDR_MAGIC_SCRIPT_4        0xdead0004
 191 #define JSXDR_MAGIC_SCRIPT_5        0xdead0005
 192 #define JSXDR_MAGIC_SCRIPT_6        0xdead0006
 193 #define JSXDR_MAGIC_SCRIPT_7        0xdead0007
 194 #define JSXDR_MAGIC_SCRIPT_8        0xdead0008
 195 #define JSXDR_MAGIC_SCRIPT_9        0xdead0009
 196 #define JSXDR_MAGIC_SCRIPT_CURRENT  JSXDR_MAGIC_SCRIPT_9
 197
 198 /*
 199  * Bytecode version number. Increment the subtrahend whenever JS bytecode
 200  * changes incompatibly.
 201  *
 202  * This version number should be XDR'ed once near the front of any file or
 203  * larger storage unit containing XDR'ed bytecode and other data, and checked
 204  * before deserialization of bytecode.  If the saved version does not match
 205  * the current version, abort deserialization and invalidate the file.
 206  */
 207 #define JSXDR_BYTECODE_VERSION      (0xb973c0de - 37)
 208
 209 /*
 210  * Library-private functions.
 211  */
 212 extern JSBool
 213 js_XDRAtom(JSXDRState *xdr, JSAtom **atomp);
 214
 215 extern JSBool
 216 js_XDRStringAtom(JSXDRState *xdr, JSAtom **atomp);
 217
 218 JS_END_EXTERN_C
 219
 220 #endif /* ! jsxdrapi_h___ */