gecko-dev/js/public/StructuredClone.h

285 строки
12 KiB
C++

/* -*- 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 <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 */
SCTAG_TMO_UNFILLED = 0,
/** Structured clone buffer does not yet own the data */
SCTAG_TMO_UNOWNED = 1,
/** All values at least this large are owned by the clone buffer */
SCTAG_TMO_FIRST_OWNED = 2,
/** Data is a pointer that can be freed */
SCTAG_TMO_ALLOC_DATA = 2,
/** Data is a SharedArrayBufferObject's buffer */
SCTAG_TMO_SHARED_BUFFER = 3,
/** Data is a memory mapped pointer */
SCTAG_TMO_MAPPED_DATA = 4,
/**
* 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.
*/
SCTAG_TMO_CUSTOM = 5,
SCTAG_TMO_USER_MIN
};
} /* 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.)
#define JS_STRUCTURED_CLONE_VERSION 6
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_PUBLIC_API(bool)
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_PUBLIC_API(bool)
JS_WriteStructuredClone(JSContext* cx, JS::HandleValue v, uint64_t** datap, size_t* nbytesp,
const JSStructuredCloneCallbacks* optionalCallbacks,
void* closure, JS::HandleValue transferable);
JS_PUBLIC_API(bool)
JS_ClearStructuredClone(uint64_t* data, size_t nbytes,
const JSStructuredCloneCallbacks* optionalCallbacks,
void *closure, bool freeData = true);
JS_PUBLIC_API(bool)
JS_StructuredCloneHasTransferables(const uint64_t* data, size_t nbytes, bool* hasTransferable);
JS_PUBLIC_API(bool)
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_;
enum {
OwnsTransferablesIfAny,
IgnoreTransferablesIfAny,
NoTransferables
} ownTransferables_;
const JSStructuredCloneCallbacks* callbacks_;
void* closure_;
public:
JSAutoStructuredCloneBuffer()
: data_(nullptr), nbytes_(0), version_(JS_STRUCTURED_CLONE_VERSION),
ownTransferables_(NoTransferables),
callbacks_(nullptr), closure_(nullptr)
{}
JSAutoStructuredCloneBuffer(const JSStructuredCloneCallbacks* callbacks, void* closure)
: data_(nullptr), nbytes_(0), version_(JS_STRUCTURED_CLONE_VERSION),
ownTransferables_(NoTransferables),
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(const JSStructuredCloneCallbacks* optionalCallbacks=nullptr, void* closure=nullptr);
/** 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,
const JSStructuredCloneCallbacks* callbacks=nullptr, void* closure=nullptr);
/**
* 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,
const JSStructuredCloneCallbacks* callbacks=nullptr, void* closure=nullptr);
/**
* Release the buffer and transfer ownership to the caller. The caller is
* responsible for calling JS_ClearStructuredClone or feeding the memory
* back to JSAutoStructuredCloneBuffer::adopt.
*/
void steal(uint64_t** datap, size_t* nbytesp, uint32_t* versionp=nullptr,
const JSStructuredCloneCallbacks** callbacks=nullptr, void** closure=nullptr);
/**
* Abandon ownership of any transferable objects stored in the buffer,
* without freeing the buffer itself. Useful when copying the data out into
* an external container, though note that you will need to use adopt() or
* JS_ClearStructuredClone to properly release that data eventually.
*/
void abandon() { ownTransferables_ = IgnoreTransferablesIfAny; }
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);
private:
// Copy and assignment are not supported.
JSAutoStructuredCloneBuffer(const JSAutoStructuredCloneBuffer& other) = delete;
JSAutoStructuredCloneBuffer& operator=(const JSAutoStructuredCloneBuffer& other) = 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)
#define JS_SCERR_RECURSION 0
#define JS_SCERR_TRANSFERABLE 1
#define JS_SCERR_DUP_TRANSFERABLE 2
JS_PUBLIC_API(bool)
JS_ReadUint32Pair(JSStructuredCloneReader* r, uint32_t* p1, uint32_t* p2);
JS_PUBLIC_API(bool)
JS_ReadBytes(JSStructuredCloneReader* r, void* p, size_t len);
JS_PUBLIC_API(bool)
JS_ReadTypedArray(JSStructuredCloneReader* r, JS::MutableHandleValue vp);
JS_PUBLIC_API(bool)
JS_WriteUint32Pair(JSStructuredCloneWriter* w, uint32_t tag, uint32_t data);
JS_PUBLIC_API(bool)
JS_WriteBytes(JSStructuredCloneWriter* w, const void* p, size_t len);
JS_PUBLIC_API(bool)
JS_WriteString(JSStructuredCloneWriter* w, JS::HandleString str);
JS_PUBLIC_API(bool)
JS_WriteTypedArray(JSStructuredCloneWriter* w, JS::HandleValue v);
#endif /* js_StructuredClone_h */