The Tor Browser: js/public/StructuredClone.h@925c144e1f1f (annotated)

js/public/StructuredClone.h@925c144e1f1f (annotated)

js/public/StructuredClone.h

Fri, 16 Jan 2015 18:13:44 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Fri, 16 Jan 2015 18:13:44 +0100
branch: TOR_BUG_9701
changeset 14: 925c144e1f1f
permissions: -rw-r--r--

Integrate suggestion from review to improve consistency with existing code.

 /* -*- 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
     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, and ArrayBuffers. 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. 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 2
 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);
 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_;
     const JSStructuredCloneCallbacks *callbacks_;
     void *closure_;
   public:
     JSAutoStructuredCloneBuffer()
         : 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);
   private:
     // 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)
 #define JS_SCERR_RECURSION 0
 #define JS_SCERR_TRANSFERABLE 1
 JS_PUBLIC_API(void)
 JS_SetStructuredCloneCallbacks(JSRuntime *rt, const JSStructuredCloneCallbacks *callbacks);
 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_WriteTypedArray(JSStructuredCloneWriter *w, JS::HandleValue v);
 #endif  /* js_StructuredClone_h */

The Tor Browser / annotate

js/public/StructuredClone.h@925c144e1f1f (annotated)

js/public/StructuredClone.h