author Xidorn Quan <quanxunzhen@gmail.com>
Mon, 08 Dec 2014 21:45:56 +1100
changeset 219689 247b87f9114e8f9f2a3b6428b0a50f51601a4b49
parent 205826 98dd1d0aba486102e124eaee91e4b0f2c3943b04
child 222858 86924ac6a94a9147bcae518239d7a33b5981062b
permissions -rw-r--r--
Bug 1088489 - Implement ruby pseudo box generation. r=bz

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 * vim: set ts=8 sts=4 et sw=4 tw=99:
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef js_StructuredClone_h
#define js_StructuredClone_h

#include "mozilla/NullPtr.h"

#include <stdint.h>

#include "jstypes.h"

#include "js/RootingAPI.h"
#include "js/TypeDecls.h"
#include "js/Value.h"

struct JSRuntime;
struct JSStructuredCloneReader;
struct JSStructuredCloneWriter;

// API for the HTML5 internal structured cloning algorithm.

namespace JS {
enum TransferableOwnership {
    // Transferable data has not been filled in yet

    // Structured clone buffer does not yet own the data

    // All values at least this large are owned by the clone buffer

    // Data is a pointer that can be freed

    // Data is a SharedArrayBufferObject's buffer

    // Data is a memory mapped pointer

    // Data is embedding-specific. The engine can free it by calling the
    // freeTransfer op. The embedding can also use SCTAG_TMO_USER_MIN and
    // greater, up to 32 bits, to distinguish specific ownership variants.

} /* namespace JS */

// Read structured data from the reader r. This hook is used to read a value
// previously serialized by a call to the WriteStructuredCloneOp hook.
// tag and data are the pair of uint32_t values from the header. The callback
// may use the JS_Read* APIs to read any other relevant parts of the object
// from the reader r. closure is any value passed to the JS_ReadStructuredClone
// function. Return the new object on success, nullptr on error/exception.
typedef JSObject *(*ReadStructuredCloneOp)(JSContext *cx, JSStructuredCloneReader *r,
                                           uint32_t tag, uint32_t data, void *closure);

// Structured data serialization hook. The engine can write primitive values,
// Objects, Arrays, Dates, RegExps, TypedArrays, ArrayBuffers, Sets, Maps,
// and SharedTypedArrays. Any other type of object requires application support.
// This callback must first use the JS_WriteUint32Pair API to write an object
// header, passing a value greater than JS_SCTAG_USER to the tag parameter.
// Then it can use the JS_Write* APIs to write any other relevant parts of
// the value v to the writer w. closure is any value passed to the
// JS_WriteStructuredClone function.
// Return true on success, false on error/exception.
typedef bool (*WriteStructuredCloneOp)(JSContext *cx, JSStructuredCloneWriter *w,
                                       JS::HandleObject obj, void *closure);

// This is called when JS_WriteStructuredClone is given an invalid transferable.
// To follow HTML5, the application must throw a DATA_CLONE_ERR DOMException
// with error set to one of the JS_SCERR_* values.
typedef void (*StructuredCloneErrorOp)(JSContext *cx, uint32_t errorid);

// This is called when JS_ReadStructuredClone receives a transferable object
// not known to the engine. If this hook does not exist or returns false, the
// JS engine calls the reportError op if set, otherwise it throws a
// DATA_CLONE_ERR DOM Exception. This method is called before any other
// callback and must return a non-null object in returnObject on success.
typedef bool (*ReadTransferStructuredCloneOp)(JSContext *cx, JSStructuredCloneReader *r,
                                              uint32_t tag, void *content, uint64_t extraData,
                                              void *closure,
                                              JS::MutableHandleObject returnObject);

// Called when JS_WriteStructuredClone receives a transferable object not
// handled by the engine. If this hook does not exist or returns false, the JS
// engine will call the reportError hook or fall back to throwing a
// DATA_CLONE_ERR DOM Exception. This method is called before any other
// callback.
//  tag: indicates what type of transferable this is. Must be greater than
//       0xFFFF0201 (value of the internal SCTAG_TRANSFER_MAP_PENDING_ENTRY)
//  ownership: see TransferableOwnership, above. Used to communicate any needed
//       ownership info to the FreeTransferStructuredCloneOp.
//  content, extraData: what the ReadTransferStructuredCloneOp will receive
typedef bool (*TransferStructuredCloneOp)(JSContext *cx,
                                          JS::Handle<JSObject*> obj,
                                          void *closure,
                                          // Output:
                                          uint32_t *tag,
                                          JS::TransferableOwnership *ownership,
                                          void **content,
                                          uint64_t *extraData);

// Called when JS_ClearStructuredClone has to free an unknown transferable
// object. Note that it should never trigger a garbage collection (and will
// assert in a debug build if it does.)
typedef void (*FreeTransferStructuredCloneOp)(uint32_t tag, JS::TransferableOwnership ownership,
                                              void *content, uint64_t extraData, void *closure);

// The maximum supported structured-clone serialization format version.
// Increment this when anything at all changes in the serialization format.
// (Note that this does not need to be bumped for Transferable-only changes,
// since they are never saved to persistent storage.)

struct JSStructuredCloneCallbacks {
    ReadStructuredCloneOp read;
    WriteStructuredCloneOp write;
    StructuredCloneErrorOp reportError;
    ReadTransferStructuredCloneOp readTransfer;
    TransferStructuredCloneOp writeTransfer;
    FreeTransferStructuredCloneOp freeTransfer;

// Note: if the *data contains transferable objects, it can be read only once.
JS_ReadStructuredClone(JSContext *cx, uint64_t *data, size_t nbytes, uint32_t version,
                       JS::MutableHandleValue vp,
                       const JSStructuredCloneCallbacks *optionalCallbacks, void *closure);

// Note: On success, the caller is responsible for calling
// JS_ClearStructuredClone(*datap, nbytes, optionalCallbacks, closure).
JS_WriteStructuredClone(JSContext *cx, JS::HandleValue v, uint64_t **datap, size_t *nbytesp,
                        const JSStructuredCloneCallbacks *optionalCallbacks,
                        void *closure, JS::HandleValue transferable);

JS_ClearStructuredClone(uint64_t *data, size_t nbytes,
                        const JSStructuredCloneCallbacks *optionalCallbacks,
                        void *closure);

JS_StructuredCloneHasTransferables(const uint64_t *data, size_t nbytes, bool *hasTransferable);

JS_StructuredClone(JSContext *cx, JS::HandleValue v, JS::MutableHandleValue vp,
                   const JSStructuredCloneCallbacks *optionalCallbacks, void *closure);

// RAII sugar for JS_WriteStructuredClone.
class JS_PUBLIC_API(JSAutoStructuredCloneBuffer) {
    uint64_t *data_;
    size_t nbytes_;
    uint32_t version_;
    const JSStructuredCloneCallbacks *callbacks_;
    void *closure_;

        : data_(nullptr), nbytes_(0), version_(JS_STRUCTURED_CLONE_VERSION),
          callbacks_(nullptr), closure_(nullptr)

    JSAutoStructuredCloneBuffer(const JSStructuredCloneCallbacks *callbacks, void *closure)
        : data_(nullptr), nbytes_(0), version_(JS_STRUCTURED_CLONE_VERSION),
          callbacks_(callbacks), closure_(closure)

    JSAutoStructuredCloneBuffer(JSAutoStructuredCloneBuffer &&other);
    JSAutoStructuredCloneBuffer &operator=(JSAutoStructuredCloneBuffer &&other);

    ~JSAutoStructuredCloneBuffer() { clear(); }

    uint64_t *data() const { return data_; }
    size_t nbytes() const { return nbytes_; }

    void clear();

    // Copy some memory. It will be automatically freed by the destructor.
    bool copy(const uint64_t *data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION);

    // Adopt some memory. It will be automatically freed by the destructor.
    // data must have been allocated by the JS engine (e.g., extracted via
    // JSAutoStructuredCloneBuffer::steal).
    void adopt(uint64_t *data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION);

    // Remove the buffer so that it will not be automatically freed.
    // After this, the caller is responsible for feeding the memory back to
    // JSAutoStructuredCloneBuffer::adopt.
    void steal(uint64_t **datap, size_t *nbytesp, uint32_t *versionp=nullptr);

    bool read(JSContext *cx, JS::MutableHandleValue vp,
              const JSStructuredCloneCallbacks *optionalCallbacks=nullptr, void *closure=nullptr);

    bool write(JSContext *cx, JS::HandleValue v,
               const JSStructuredCloneCallbacks *optionalCallbacks=nullptr, void *closure=nullptr);

    bool write(JSContext *cx, JS::HandleValue v, JS::HandleValue transferable,
               const JSStructuredCloneCallbacks *optionalCallbacks=nullptr, void *closure=nullptr);

    // Copy and assignment are not supported.
    JSAutoStructuredCloneBuffer(const JSAutoStructuredCloneBuffer &other) MOZ_DELETE;
    JSAutoStructuredCloneBuffer &operator=(const JSAutoStructuredCloneBuffer &other) MOZ_DELETE;

// The range of tag values the application may use for its own custom object types.
#define JS_SCTAG_USER_MIN  ((uint32_t) 0xFFFF8000)
#define JS_SCTAG_USER_MAX  ((uint32_t) 0xFFFFFFFF)


JS_SetStructuredCloneCallbacks(JSRuntime *rt, const JSStructuredCloneCallbacks *callbacks);

JS_ReadUint32Pair(JSStructuredCloneReader *r, uint32_t *p1, uint32_t *p2);

JS_ReadBytes(JSStructuredCloneReader *r, void *p, size_t len);

JS_ReadTypedArray(JSStructuredCloneReader *r, JS::MutableHandleValue vp);

JS_WriteUint32Pair(JSStructuredCloneWriter *w, uint32_t tag, uint32_t data);

JS_WriteBytes(JSStructuredCloneWriter *w, const void *p, size_t len);

JS_WriteTypedArray(JSStructuredCloneWriter *w, JS::HandleValue v);

#endif  /* js_StructuredClone_h */