/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
 67JS_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_t)(x) >> 24) |                              \
 76                         (((uint32_t)(x) >> 8) & 0xff00) |                    \
 77                         (((uint32_t)(x) << 8) & 0xff0000) |                  \
 78                         ((uint32_t)(x) << 24))
 79#define JSXDR_SWAB16(x) (((uint16_t)(x) >> 8) | ((uint16_t)(x) << 8))
 80#else
 81#error "unknown byte order"
 82#endif
 83
 84#define JSXDR_ALIGN     4
 85
 86typedef enum JSXDRMode {
 87    JSXDR_ENCODE,
 88    JSXDR_DECODE
 89} JSXDRMode;
 90
 91typedef enum JSXDRWhence {
 92    JSXDR_SEEK_SET,
 93    JSXDR_SEEK_CUR,
 94    JSXDR_SEEK_END
 95} JSXDRWhence;
 96
 97typedef struct JSXDROps {
 98    JSBool      (*get32)(JSXDRState *, uint32_t *);
 99    JSBool      (*set32)(JSXDRState *, uint32_t *);
100    JSBool      (*getbytes)(JSXDRState *, char *, uint32_t);
101    JSBool      (*setbytes)(JSXDRState *, char *, uint32_t);
102    void *      (*raw)(JSXDRState *, uint32_t);
103    JSBool      (*seek)(JSXDRState *, int32_t, JSXDRWhence);
104    uint32_t    (*tell)(JSXDRState *);
105    void        (*finalize)(JSXDRState *);
106} JSXDROps;
107
108struct JSXDRState;
109
110namespace js {
111
112class XDRScriptState {
113public:
114    XDRScriptState(JSXDRState *x);
115    ~XDRScriptState();
116
117    JSXDRState      *xdr;
118    const char      *filename;
119    bool             filenameSaved;
120};
121
122} /* namespace JS */
123
124struct JSXDRState {
125    JSXDRMode   mode;
126    JSXDROps    *ops;
127    JSContext   *cx;
128    JSClass     **registry;
129    uintN       numclasses;
130    uintN       maxclasses;
131    void        *reghash;
132    void        *userdata;
133    JSScript    *script;
134    js::XDRScriptState *state;
135};
136
137extern JS_PUBLIC_API(void)
138JS_XDRInitBase(JSXDRState *xdr, JSXDRMode mode, JSContext *cx);
139
140extern JS_PUBLIC_API(JSXDRState *)
141JS_XDRNewMem(JSContext *cx, JSXDRMode mode);
142
143extern JS_PUBLIC_API(void *)
144JS_XDRMemGetData(JSXDRState *xdr, uint32_t *lp);
145
146extern JS_PUBLIC_API(void)
147JS_XDRMemSetData(JSXDRState *xdr, void *data, uint32_t len);
148
149extern JS_PUBLIC_API(uint32_t)
150JS_XDRMemDataLeft(JSXDRState *xdr);
151
152extern JS_PUBLIC_API(void)
153JS_XDRMemResetData(JSXDRState *xdr);
154
155extern JS_PUBLIC_API(void)
156JS_XDRDestroy(JSXDRState *xdr);
157
158extern JS_PUBLIC_API(JSBool)
159JS_XDRUint8(JSXDRState *xdr, uint8_t *b);
160
161extern JS_PUBLIC_API(JSBool)
162JS_XDRUint16(JSXDRState *xdr, uint16_t *s);
163
164extern JS_PUBLIC_API(JSBool)
165JS_XDRUint32(JSXDRState *xdr, uint32_t *lp);
166
167extern JS_PUBLIC_API(JSBool)
168JS_XDRBytes(JSXDRState *xdr, char *bytes, uint32_t len);
169
170extern JS_PUBLIC_API(JSBool)
171JS_XDRCString(JSXDRState *xdr, char **sp);
172
173extern JS_PUBLIC_API(JSBool)
174JS_XDRCStringOrNull(JSXDRState *xdr, char **sp);
175
176extern JS_PUBLIC_API(JSBool)
177JS_XDRString(JSXDRState *xdr, JSString **strp);
178
179extern JS_PUBLIC_API(JSBool)
180JS_XDRStringOrNull(JSXDRState *xdr, JSString **strp);
181
182extern JS_PUBLIC_API(JSBool)
183JS_XDRDouble(JSXDRState *xdr, jsdouble *dp);
184
185extern JS_PUBLIC_API(JSBool)
186JS_XDRValue(JSXDRState *xdr, jsval *vp);
187
188extern JS_PUBLIC_API(JSBool)
189JS_XDRFunctionObject(JSXDRState *xdr, JSObject **objp);
190
191extern JS_PUBLIC_API(JSBool)
192JS_XDRScript(JSXDRState *xdr, JSScript **scriptp);
193
194extern JS_PUBLIC_API(JSBool)
195JS_XDRRegisterClass(JSXDRState *xdr, JSClass *clasp, uint32_t *lp);
196
197extern JS_PUBLIC_API(uint32_t)
198JS_XDRFindClassIdByName(JSXDRState *xdr, const char *name);
199
200extern JS_PUBLIC_API(JSClass *)
201JS_XDRFindClassById(JSXDRState *xdr, uint32_t id);
202
203/*
204 * Magic numbers.
205 */
206#define JSXDR_MAGIC_SCRIPT_1        0xdead0001
207#define JSXDR_MAGIC_SCRIPT_2        0xdead0002
208#define JSXDR_MAGIC_SCRIPT_3        0xdead0003
209#define JSXDR_MAGIC_SCRIPT_4        0xdead0004
210#define JSXDR_MAGIC_SCRIPT_5        0xdead0005
211#define JSXDR_MAGIC_SCRIPT_6        0xdead0006
212#define JSXDR_MAGIC_SCRIPT_7        0xdead0007
213#define JSXDR_MAGIC_SCRIPT_8        0xdead0008
214#define JSXDR_MAGIC_SCRIPT_9        0xdead0009
215#define JSXDR_MAGIC_SCRIPT_10       0xdead000a
216#define JSXDR_MAGIC_SCRIPT_11       0xdead000b
217#define JSXDR_MAGIC_SCRIPT_12       0xdead000c
218#define JSXDR_MAGIC_SCRIPT_CURRENT  JSXDR_MAGIC_SCRIPT_12
219
220/*
221 * Bytecode version number. Increment the subtrahend whenever JS bytecode
222 * changes incompatibly.
223 *
224 * This version number is XDR'd near the front of xdr bytecode and
225 * aborts deserialization if there is a mismatch between the current
226 * and saved versions. If deserialization fails, the data should be
227 * invalidated if possible.
228 */
229#define JSXDR_BYTECODE_VERSION      (0xb973c0de - 107)
230
231/*
232 * Library-private functions.
233 */
234extern JSBool
235js_XDRAtom(JSXDRState *xdr, JSAtom **atomp);
236
237JS_END_EXTERN_C
238
239#endif /* ! jsxdrapi_h___ */