1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * vim: set ts=8 sts=2 et sw=2 tw=80:
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef js_StructuredClone_h
8 #define js_StructuredClone_h
10 #include "mozilla/Attributes.h"
11 #include "mozilla/BufferList.h"
12 #include "mozilla/MemoryReporting.h"
19 #include "js/AllocPolicy.h"
20 #include "js/RootingAPI.h"
21 #include "js/TypeDecls.h"
22 #include "js/Vector.h"
25 * API for safe passing of structured data, HTML 2018 Feb 21 section 2.7.
26 * <https://html.spec.whatwg.org/multipage/structured-data.html>
28 * This is a serialization scheme for JS values, somewhat like JSON. It
29 * preserves some aspects of JS objects (strings, numbers, own data properties
30 * with string keys, array elements) but not others (methods, getters and
31 * setters, prototype chains). Unlike JSON, structured data:
33 * - can contain cyclic references.
35 * - handles Maps, Sets, and some other object types.
37 * - supports *transferring* objects of certain types from one realm to
38 * another, rather than cloning them.
40 * - is specified by a living standard, and continues to evolve.
42 * - is encoded in a nonstandard binary format, and is never exposed to Web
43 * content in its serialized form. It's used internally by the browser to
44 * send data from one thread/realm/domain to another, not across the
48 struct JSStructuredCloneReader
;
49 struct JSStructuredCloneWriter
;
52 * The structured-clone serialization format version number.
54 * When serialized data is stored as bytes, e.g. in your Firefox profile, later
55 * versions of the engine may have to read it. When you upgrade Firefox, we
56 * don't crawl through your whole profile converting all saved data from the
57 * previous version of the serialization format to the latest version. So it is
58 * normal to have data in old formats stored in your profile.
60 * The JS engine can *write* data only in the current format version.
62 * It can *read* any data written in the current version, and data written for
63 * DifferentProcess scope in earlier versions.
66 * ## When to bump this version number
68 * When making a change so drastic that the JS engine needs to know whether
69 * it's reading old or new serialized data in order to handle both correctly,
70 * increment this version number. Make sure the engine can still read all
71 * old data written with previous versions.
73 * If StructuredClone.cpp doesn't contain code that distinguishes between
74 * version 8 and version 9, there should not be a version 9.
76 * Do not increment for changes that only affect SameProcess encoding.
78 * Increment only for changes that would otherwise break old serialized data.
79 * Do not increment for new data types. (Rationale: Modulo bugs, older versions
80 * of the JS engine can already correctly throw errors when they encounter new,
81 * unrecognized features. A version number bump does not actually help them.)
83 #define JS_STRUCTURED_CLONE_VERSION 8
88 * Indicates the "scope of validity" of serialized data.
90 * Writing plain JS data produces an array of bytes that can be copied and
91 * read in another process or whatever. The serialized data is Plain Old Data.
92 * However, HTML also supports `Transferable` objects, which, when cloned, can
93 * be moved from the source object into the clone, like when you take a
94 * photograph of someone and it steals their soul.
95 * See <https://developer.mozilla.org/en-US/docs/Web/API/Transferable>.
96 * We support cloning and transferring objects of many types.
98 * For example, when we transfer an ArrayBuffer (within a process), we "detach"
99 * the ArrayBuffer, embed the raw buffer pointer in the serialized data, and
100 * later install it in a new ArrayBuffer in the destination realm. Ownership
101 * of that buffer memory is transferred from the original ArrayBuffer to the
102 * serialized data and then to the clone.
104 * This only makes sense within a single address space. When we transfer an
105 * ArrayBuffer to another process, the contents of the buffer must be copied
106 * into the serialized data. (The original ArrayBuffer is still detached,
107 * though, for consistency; in some cases the caller shouldn't know or care if
108 * the recipient is in the same process.)
110 * ArrayBuffers are actually a lucky case; some objects (like MessagePorts)
111 * can't reasonably be stored by value in serialized data -- it's pointers or
114 * So there is a tradeoff between scope of validity -- how far away the
115 * serialized data may be sent and still make sense -- and efficiency or
116 * features. The read and write algorithms therefore take an argument of this
117 * type, allowing the user to control those trade-offs.
119 enum class StructuredCloneScope
: uint32_t {
121 * The most restrictive scope, with greatest efficiency and features.
123 * When writing, this means: The caller promises that the serialized data
124 * will **not** be shipped off to a different process or stored in a
125 * database. However, it may be shipped to another thread. It's OK to
126 * produce serialized data that contains pointers to data that is safe to
127 * send across threads, such as array buffers. In Rust terms, the
128 * serialized data will be treated as `Send` but not `Copy`.
130 * When reading, this means: Accept transferred objects and buffers
131 * (pointers). The caller promises that the serialized data was written
132 * using this API (otherwise, the serialized data may contain bogus
133 * pointers, leading to undefined behavior).
135 * Starts from 1 because there used to be a SameProcessSameThread enum value
136 * of 0 and these values are encoded into the structured serialization format
137 * as part of the SCTAG_HEADER, and IndexedDB persists the representation to
143 * When writing, this means we're writing for an audience in a different
144 * process. Produce serialized data that can be sent to other processes,
145 * bitwise copied, or even stored as bytes in a database and read by later
146 * versions of Firefox years from now. The HTML5 spec refers to this as
147 * "ForStorage" as in StructuredSerializeForStorage, though we use
148 * DifferentProcess for IPC as well as storage.
150 * Transferable objects are limited to ArrayBuffers, whose contents are
151 * copied into the serialized data (rather than just writing a pointer).
153 * When reading, this means: Do not accept pointers.
158 * Handle a backwards-compatibility case with IndexedDB (bug 1434308): when
159 * reading, this means to treat legacy SameProcess data as if it were
162 * Do not use this for writing; use DifferentProcess instead.
164 DifferentProcessForIndexedDB
,
167 * Existing code wants to be able to create an uninitialized
168 * JSStructuredCloneData without knowing the scope, then populate it with
169 * data (at which point the scope *is* known.)
174 * This scope is used when the deserialization context is unknown. When
175 * writing, DifferentProcess or SameProcess scope is chosen based on the
176 * nature of the object.
181 /** Values used to describe the ownership individual Transferables.
183 * Note that these *can* show up in DifferentProcess clones, since
184 * DifferentProcess ArrayBuffers can be Transferred. In that case, this will
185 * distinguish the specific ownership mechanism: is it a malloc pointer or a
187 enum TransferableOwnership
{
188 /** Transferable data has not been filled in yet. */
189 SCTAG_TMO_UNFILLED
= 0,
191 /** Structured clone buffer does not yet own the data. */
192 SCTAG_TMO_UNOWNED
= 1,
194 /** All enum values at least this large are owned by the clone buffer. */
195 SCTAG_TMO_FIRST_OWNED
= 2,
197 /** Data is a pointer that can be freed. */
198 SCTAG_TMO_ALLOC_DATA
= SCTAG_TMO_FIRST_OWNED
,
200 /** Data is a memory mapped pointer. */
201 SCTAG_TMO_MAPPED_DATA
= 3,
204 * Data is embedding-specific. The engine can free it by calling the
205 * freeTransfer op. */
206 SCTAG_TMO_CUSTOM
= 4,
209 * Same as SCTAG_TMO_CUSTOM, but the embedding can also use
210 * SCTAG_TMO_USER_MIN and greater, up to 2^32-1, to distinguish specific
211 * ownership variants.
216 class CloneDataPolicy
{
217 bool allowIntraClusterClonableSharedObjects_
;
218 bool allowSharedMemoryObjects_
;
221 // The default is to deny all policy-controlled aspects.
224 : allowIntraClusterClonableSharedObjects_(false),
225 allowSharedMemoryObjects_(false) {}
227 // SharedArrayBuffers and WASM modules can only be cloned intra-process
228 // because the shared memory areas are allocated in process-private memory or
229 // because there are security issues of sharing them cross agent clusters.
230 // y default, we don't allow shared-memory and intra-cluster objects. Clients
231 // should therefore enable these 2 clone features when needed.
233 void allowIntraClusterClonableSharedObjects() {
234 allowIntraClusterClonableSharedObjects_
= true;
236 bool areIntraClusterClonableSharedObjectsAllowed() const {
237 return allowIntraClusterClonableSharedObjects_
;
240 void allowSharedMemoryObjects() { allowSharedMemoryObjects_
= true; }
241 bool areSharedMemoryObjectsAllowed() const {
242 return allowSharedMemoryObjects_
;
249 * Read structured data from the reader r. This hook is used to read a value
250 * previously serialized by a call to the WriteStructuredCloneOp hook.
252 * tag and data are the pair of uint32_t values from the header. The callback
253 * may use the JS_Read* APIs to read any other relevant parts of the object
254 * from the reader r. closure is any value passed to the JS_ReadStructuredClone
257 * Return the new object on success, or raise an exception and return nullptr on
260 typedef JSObject
* (*ReadStructuredCloneOp
)(
261 JSContext
* cx
, JSStructuredCloneReader
* r
,
262 const JS::CloneDataPolicy
& cloneDataPolicy
, uint32_t tag
, uint32_t data
,
266 * Structured data serialization hook. The engine can write primitive values,
267 * Objects, Arrays, Dates, RegExps, TypedArrays, ArrayBuffers, Sets, Maps,
268 * and SharedTypedArrays. Any other type of object requires application support.
269 * This callback must first use the JS_WriteUint32Pair API to write an object
270 * header, passing a value greater than JS_SCTAG_USER to the tag parameter.
271 * Then it can use the JS_Write* APIs to write any other relevant parts of
272 * the value v to the writer w. closure is any value passed to the
273 * JS_WriteStructuredClone function.
275 * Return true on success, false on error. On error, an exception should
278 typedef bool (*WriteStructuredCloneOp
)(JSContext
* cx
,
279 JSStructuredCloneWriter
* w
,
280 JS::HandleObject obj
,
281 bool* sameProcessScopeRequired
,
285 * This is called when serialization or deserialization encounters an error.
286 * To follow HTML5, the application must throw a DATA_CLONE_ERR DOMException
287 * with error set to one of the JS_SCERR_* values.
289 * Note that if the .reportError field of the JSStructuredCloneCallbacks is
290 * set (to a function with this signature), then an exception will *not* be
291 * set on the JSContext when an error is encountered. The clone operation
292 * will still be aborted and will return false, however, so it is up to the
293 * embedding to do what it needs to for the error.
295 * Example: for the DOM, mozilla::dom::StructuredCloneHolder will save away
296 * the error message during its reportError callback. Then when the overall
297 * operation fails, it will clear any exception that might have been set
298 * from other ways to fail and pass the saved error message to
299 * ErrorResult::ThrowDataCloneError().
301 typedef void (*StructuredCloneErrorOp
)(JSContext
* cx
, uint32_t errorid
,
302 void* closure
, const char* errorMessage
);
305 * This is called when JS_ReadStructuredClone receives a transferable object
306 * not known to the engine. If this hook does not exist or returns false, the
307 * JS engine calls the reportError op if set, otherwise it throws a
308 * DATA_CLONE_ERR DOM Exception. This method is called before any other
309 * callback and must return a non-null object in returnObject on success.
311 * If this readTransfer() hook is called and produces an object, then the
312 * read() hook will *not* be called for the same object, since the main data
313 * will only contain a backreference to the already-read object.
315 typedef bool (*ReadTransferStructuredCloneOp
)(
316 JSContext
* cx
, JSStructuredCloneReader
* r
,
317 const JS::CloneDataPolicy
& aCloneDataPolicy
, uint32_t tag
, void* content
,
318 uint64_t extraData
, void* closure
, JS::MutableHandleObject returnObject
);
321 * Called when JS_WriteStructuredClone receives a transferable object not
322 * handled by the engine. If this hook does not exist or returns false, the JS
323 * engine will call the reportError hook or fall back to throwing a
324 * DATA_CLONE_ERR DOM Exception. This method is called before any other
327 * tag: indicates what type of transferable this is. Must be greater than
328 * 0xFFFF0201 (value of the internal SCTAG_TRANSFER_MAP_PENDING_ENTRY)
330 * ownership: see TransferableOwnership, above. Used to communicate any needed
331 * ownership info to the FreeTransferStructuredCloneOp.
333 * content, extraData: what the ReadTransferStructuredCloneOp will receive
335 typedef bool (*TransferStructuredCloneOp
)(JSContext
* cx
,
336 JS::Handle
<JSObject
*> obj
,
340 JS::TransferableOwnership
* ownership
,
341 void** content
, uint64_t* extraData
);
344 * Called when freeing a transferable handled by the embedding. Note that it
345 * should never trigger a garbage collection (and will assert in a
346 * debug build if it does.)
348 * This callback will be used to release ownership in three situations:
350 * 1. During serialization: an object is Transferred from, then an error is
351 * encountered later and the incomplete serialization is discarded.
353 * 2. During deserialization: before an object is Transferred to, an error
354 * is encountered and the incompletely deserialized clone is discarded.
356 * 3. Serialized data that includes Transferring is never deserialized (eg when
357 * the receiver disappears before reading in the message), and the clone data
361 typedef void (*FreeTransferStructuredCloneOp
)(
362 uint32_t tag
, JS::TransferableOwnership ownership
, void* content
,
363 uint64_t extraData
, void* closure
);
366 * Called when the transferring objects are checked. If this function returns
367 * false, the serialization ends throwing a DataCloneError exception.
369 typedef bool (*CanTransferStructuredCloneOp
)(JSContext
* cx
,
370 JS::Handle
<JSObject
*> obj
,
371 bool* sameProcessScopeRequired
,
375 * Called when a SharedArrayBuffer (including one owned by a Wasm memory object)
376 * has been processed in context `cx` by structured cloning. If `receiving` is
377 * true then the SAB has been received from a channel and a new SAB object has
378 * been created; if false then an existing SAB has been serialized onto a
381 * If the callback returns false then the clone operation (read or write) will
384 typedef bool (*SharedArrayBufferClonedOp
)(JSContext
* cx
, bool receiving
,
387 struct JSStructuredCloneCallbacks
{
388 ReadStructuredCloneOp read
;
389 WriteStructuredCloneOp write
;
390 StructuredCloneErrorOp reportError
;
391 ReadTransferStructuredCloneOp readTransfer
;
392 TransferStructuredCloneOp writeTransfer
;
393 FreeTransferStructuredCloneOp freeTransfer
;
394 CanTransferStructuredCloneOp canTransfer
;
395 SharedArrayBufferClonedOp sabCloned
;
398 enum OwnTransferablePolicy
{
400 * The buffer owns any Transferables that it might contain, and should
401 * properly release them upon destruction.
403 OwnsTransferablesIfAny
,
406 * Do not free any Transferables within this buffer when deleting it. This
407 * is used to mark a clone buffer as containing data from another process,
408 * and so it can't legitimately contain pointers. If the buffer claims to
409 * have transferables, it's a bug or an attack. This is also used for
410 * abandon(), where a buffer still contains raw data but the ownership has
411 * been given over to some other entity.
413 IgnoreTransferablesIfAny
,
416 * A buffer that cannot contain Transferables at all. This usually means
417 * the buffer is empty (not yet filled in, or having been cleared).
423 class SharedArrayRawBuffer
;
425 class SharedArrayRawBufferRefs
{
427 SharedArrayRawBufferRefs() = default;
428 SharedArrayRawBufferRefs(SharedArrayRawBufferRefs
&& other
) = default;
429 SharedArrayRawBufferRefs
& operator=(SharedArrayRawBufferRefs
&& other
);
430 ~SharedArrayRawBufferRefs();
432 [[nodiscard
]] bool acquire(JSContext
* cx
, SharedArrayRawBuffer
* rawbuf
);
433 [[nodiscard
]] bool acquireAll(JSContext
* cx
,
434 const SharedArrayRawBufferRefs
& that
);
435 void takeOwnership(SharedArrayRawBufferRefs
&&);
439 js::Vector
<js::SharedArrayRawBuffer
*, 0, js::SystemAllocPolicy
> refs_
;
442 template <typename T
, typename AllocPolicy
>
443 struct BufferIterator
;
447 * JSStructuredCloneData represents structured clone data together with the
448 * information needed to read/write/transfer/free the records within it, in the
449 * form of a set of callbacks.
451 class MOZ_NON_MEMMOVABLE JS_PUBLIC_API JSStructuredCloneData
{
453 using BufferList
= mozilla::BufferList
<js::SystemAllocPolicy
>;
454 using Iterator
= BufferList::IterImpl
;
457 static const size_t kStandardCapacity
= 4096;
461 // The (address space, thread) scope within which this clone is valid. Note
462 // that this must be either set during construction, or start out as
463 // Unassigned and transition once to something else.
464 JS::StructuredCloneScope scope_
;
466 const JSStructuredCloneCallbacks
* callbacks_
= nullptr;
467 void* closure_
= nullptr;
468 OwnTransferablePolicy ownTransferables_
=
469 OwnTransferablePolicy::NoTransferables
;
470 js::SharedArrayRawBufferRefs refsHeld_
;
472 friend struct JSStructuredCloneWriter
;
473 friend class JS_PUBLIC_API JSAutoStructuredCloneBuffer
;
474 template <typename T
, typename AllocPolicy
>
475 friend struct js::BufferIterator
;
478 // The constructor must be infallible but SystemAllocPolicy is not, so both
479 // the initial size and initial capacity of the BufferList must be zero.
480 explicit JSStructuredCloneData(JS::StructuredCloneScope scope
)
481 : bufList_(0, 0, kStandardCapacity
, js::SystemAllocPolicy()),
484 // Steal the raw data from a BufferList. In this case, we don't know the
485 // scope and none of the callback info is assigned yet.
486 JSStructuredCloneData(BufferList
&& buffers
, JS::StructuredCloneScope scope
,
487 OwnTransferablePolicy ownership
)
488 : bufList_(std::move(buffers
)),
490 ownTransferables_(ownership
) {}
491 JSStructuredCloneData(JSStructuredCloneData
&& other
) = default;
492 JSStructuredCloneData
& operator=(JSStructuredCloneData
&& other
) = default;
493 ~JSStructuredCloneData();
495 void setCallbacks(const JSStructuredCloneCallbacks
* callbacks
, void* closure
,
496 OwnTransferablePolicy policy
) {
497 callbacks_
= callbacks
;
499 ownTransferables_
= policy
;
502 [[nodiscard
]] bool Init(size_t initialCapacity
= 0) {
503 return bufList_
.Init(0, initialCapacity
);
506 JS::StructuredCloneScope
scope() const {
507 if (scope_
== JS::StructuredCloneScope::UnknownDestination
) {
508 return JS::StructuredCloneScope::DifferentProcess
;
513 void sameProcessScopeRequired() {
514 if (scope_
== JS::StructuredCloneScope::UnknownDestination
) {
515 scope_
= JS::StructuredCloneScope::SameProcess
;
519 void initScope(JS::StructuredCloneScope newScope
) {
520 MOZ_ASSERT(Size() == 0, "initScope() of nonempty JSStructuredCloneData");
521 if (scope() != JS::StructuredCloneScope::Unassigned
) {
522 MOZ_ASSERT(scope() == newScope
,
523 "Cannot change scope after it has been initialized");
528 size_t Size() const { return bufList_
.Size(); }
530 const Iterator
Start() const { return bufList_
.Iter(); }
532 [[nodiscard
]] bool Advance(Iterator
& iter
, size_t distance
) const {
533 return iter
.AdvanceAcrossSegments(bufList_
, distance
);
536 [[nodiscard
]] bool ReadBytes(Iterator
& iter
, char* buffer
,
538 return bufList_
.ReadBytes(iter
, buffer
, size
);
541 // Append new data to the end of the buffer.
542 [[nodiscard
]] bool AppendBytes(const char* data
, size_t size
) {
543 MOZ_ASSERT(scope() != JS::StructuredCloneScope::Unassigned
);
544 return bufList_
.WriteBytes(data
, size
);
547 // Update data stored within the existing buffer. There must be at least
548 // 'size' bytes between the position of 'iter' and the end of the buffer.
549 [[nodiscard
]] bool UpdateBytes(Iterator
& iter
, const char* data
,
551 MOZ_ASSERT(scope() != JS::StructuredCloneScope::Unassigned
);
553 size_t remaining
= iter
.RemainingInSegment();
554 size_t nbytes
= std::min(remaining
, size
);
555 memcpy(iter
.Data(), data
, nbytes
);
558 iter
.Advance(bufList_
, nbytes
);
563 char* AllocateBytes(size_t maxSize
, size_t* size
) {
564 return bufList_
.AllocateBytes(maxSize
, size
);
568 discardTransferables();
572 // Return a new read-only JSStructuredCloneData that "borrows" the contents
573 // of |this|. Its lifetime should not exceed the donor's. This is only
574 // allowed for DifferentProcess clones, so finalization of the borrowing
575 // clone will do nothing.
576 JSStructuredCloneData
Borrow(Iterator
& iter
, size_t size
,
577 bool* success
) const {
578 MOZ_ASSERT(scope() == JS::StructuredCloneScope::DifferentProcess
);
579 return JSStructuredCloneData(
580 bufList_
.Borrow
<js::SystemAllocPolicy
>(iter
, size
, success
), scope(),
581 IgnoreTransferablesIfAny
);
584 // Iterate over all contained data, one BufferList segment's worth at a
585 // time, and invoke the given FunctionToApply with the data pointer and
586 // size. The function should return a bool value, and this loop will exit
587 // with false if the function ever returns false.
588 template <typename FunctionToApply
>
589 bool ForEachDataChunk(FunctionToApply
&& function
) const {
590 Iterator iter
= bufList_
.Iter();
591 while (!iter
.Done()) {
592 if (!function(iter
.Data(), iter
.RemainingInSegment())) {
595 iter
.Advance(bufList_
, iter
.RemainingInSegment());
600 // Append the entire contents of other's bufList_ to our own.
601 [[nodiscard
]] bool Append(const JSStructuredCloneData
& other
) {
602 MOZ_ASSERT(scope() == other
.scope());
603 return other
.ForEachDataChunk(
604 [&](const char* data
, size_t size
) { return AppendBytes(data
, size
); });
607 size_t SizeOfExcludingThis(mozilla::MallocSizeOf mallocSizeOf
) {
608 return bufList_
.SizeOfExcludingThis(mallocSizeOf
);
611 void discardTransferables();
614 // This internal method exposes the real value of scope_. It's meant to be
615 // used only when starting the writing.
616 JS::StructuredCloneScope
scopeForInternalWriting() const { return scope_
; }
620 * Implements StructuredDeserialize and StructuredDeserializeWithTransfer.
622 * Note: If `data` contains transferable objects, it can be read only once.
624 JS_PUBLIC_API
bool JS_ReadStructuredClone(
625 JSContext
* cx
, const JSStructuredCloneData
& data
, uint32_t version
,
626 JS::StructuredCloneScope scope
, JS::MutableHandleValue vp
,
627 const JS::CloneDataPolicy
& cloneDataPolicy
,
628 const JSStructuredCloneCallbacks
* optionalCallbacks
, void* closure
);
631 * Implements StructuredSerialize, StructuredSerializeForStorage, and
632 * StructuredSerializeWithTransfer.
634 * Note: If the scope is DifferentProcess then the cloneDataPolicy must deny
635 * shared-memory objects, or an error will be signaled if a shared memory object
638 JS_PUBLIC_API
bool JS_WriteStructuredClone(
639 JSContext
* cx
, JS::HandleValue v
, JSStructuredCloneData
* data
,
640 JS::StructuredCloneScope scope
, const JS::CloneDataPolicy
& cloneDataPolicy
,
641 const JSStructuredCloneCallbacks
* optionalCallbacks
, void* closure
,
642 JS::HandleValue transferable
);
644 JS_PUBLIC_API
bool JS_StructuredCloneHasTransferables(
645 JSStructuredCloneData
& data
, bool* hasTransferable
);
647 JS_PUBLIC_API
bool JS_StructuredClone(
648 JSContext
* cx
, JS::HandleValue v
, JS::MutableHandleValue vp
,
649 const JSStructuredCloneCallbacks
* optionalCallbacks
, void* closure
);
652 * The C-style API calls to read and write structured clones are fragile --
653 * they rely on the caller to properly handle ownership of the clone data, and
654 * the handling of the input data as well as the interpretation of the contents
655 * of the clone buffer are dependent on the callbacks passed in. If you
656 * serialize and deserialize with different callbacks, the results are
659 * JSAutoStructuredCloneBuffer wraps things up in an RAII class for data
660 * management, and uses the same callbacks for both writing and reading
661 * (serializing and deserializing).
663 class JS_PUBLIC_API JSAutoStructuredCloneBuffer
{
664 JSStructuredCloneData data_
;
668 JSAutoStructuredCloneBuffer(JS::StructuredCloneScope scope
,
669 const JSStructuredCloneCallbacks
* callbacks
,
671 : data_(scope
), version_(JS_STRUCTURED_CLONE_VERSION
) {
672 data_
.setCallbacks(callbacks
, closure
,
673 OwnTransferablePolicy::NoTransferables
);
676 JSAutoStructuredCloneBuffer(JSAutoStructuredCloneBuffer
&& other
);
677 JSAutoStructuredCloneBuffer
& operator=(JSAutoStructuredCloneBuffer
&& other
);
679 ~JSAutoStructuredCloneBuffer() { clear(); }
681 JSStructuredCloneData
& data() { return data_
; }
682 bool empty() const { return !data_
.Size(); }
686 JS::StructuredCloneScope
scope() const { return data_
.scope(); }
689 * Adopt some memory. It will be automatically freed by the destructor.
690 * data must have been allocated by the JS engine (e.g., extracted via
691 * JSAutoStructuredCloneBuffer::steal).
693 void adopt(JSStructuredCloneData
&& data
,
694 uint32_t version
= JS_STRUCTURED_CLONE_VERSION
,
695 const JSStructuredCloneCallbacks
* callbacks
= nullptr,
696 void* closure
= nullptr);
699 * Release ownership of the buffer and assign it and ownership of it to
702 void giveTo(JSStructuredCloneData
* data
);
704 bool read(JSContext
* cx
, JS::MutableHandleValue vp
,
705 const JS::CloneDataPolicy
& cloneDataPolicy
= JS::CloneDataPolicy(),
706 const JSStructuredCloneCallbacks
* optionalCallbacks
= nullptr,
707 void* closure
= nullptr);
709 bool write(JSContext
* cx
, JS::HandleValue v
,
710 const JSStructuredCloneCallbacks
* optionalCallbacks
= nullptr,
711 void* closure
= nullptr);
713 bool write(JSContext
* cx
, JS::HandleValue v
, JS::HandleValue transferable
,
714 const JS::CloneDataPolicy
& cloneDataPolicy
,
715 const JSStructuredCloneCallbacks
* optionalCallbacks
= nullptr,
716 void* closure
= nullptr);
718 size_t sizeOfExcludingThis(mozilla::MallocSizeOf mallocSizeOf
) {
719 return data_
.SizeOfExcludingThis(mallocSizeOf
);
722 size_t sizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf
) {
723 return mallocSizeOf(this) + sizeOfExcludingThis(mallocSizeOf
);
727 // Copy and assignment are not supported.
728 JSAutoStructuredCloneBuffer(const JSAutoStructuredCloneBuffer
& other
) =
730 JSAutoStructuredCloneBuffer
& operator=(
731 const JSAutoStructuredCloneBuffer
& other
) = delete;
734 // The range of tag values the application may use for its own custom object
736 #define JS_SCTAG_USER_MIN ((uint32_t)0xFFFF8000)
737 #define JS_SCTAG_USER_MAX ((uint32_t)0xFFFFFFFF)
739 #define JS_SCERR_RECURSION 0
740 #define JS_SCERR_TRANSFERABLE 1
741 #define JS_SCERR_DUP_TRANSFERABLE 2
742 #define JS_SCERR_UNSUPPORTED_TYPE 3
743 #define JS_SCERR_SHMEM_TRANSFERABLE 4
744 #define JS_SCERR_TYPED_ARRAY_DETACHED 5
745 #define JS_SCERR_WASM_NO_TRANSFER 6
746 #define JS_SCERR_NOT_CLONABLE 7
747 #define JS_SCERR_NOT_CLONABLE_WITH_COOP_COEP 8
749 JS_PUBLIC_API
bool JS_ReadUint32Pair(JSStructuredCloneReader
* r
, uint32_t* p1
,
752 JS_PUBLIC_API
bool JS_ReadBytes(JSStructuredCloneReader
* r
, void* p
,
755 JS_PUBLIC_API
bool JS_ReadString(JSStructuredCloneReader
* r
,
756 JS::MutableHandleString str
);
758 JS_PUBLIC_API
bool JS_ReadDouble(JSStructuredCloneReader
* r
, double* v
);
760 JS_PUBLIC_API
bool JS_ReadTypedArray(JSStructuredCloneReader
* r
,
761 JS::MutableHandleValue vp
);
763 JS_PUBLIC_API
bool JS_WriteUint32Pair(JSStructuredCloneWriter
* w
, uint32_t tag
,
766 JS_PUBLIC_API
bool JS_WriteBytes(JSStructuredCloneWriter
* w
, const void* p
,
769 JS_PUBLIC_API
bool JS_WriteString(JSStructuredCloneWriter
* w
,
770 JS::HandleString str
);
772 JS_PUBLIC_API
bool JS_WriteDouble(JSStructuredCloneWriter
* w
, double v
);
774 JS_PUBLIC_API
bool JS_WriteTypedArray(JSStructuredCloneWriter
* w
,
777 JS_PUBLIC_API
bool JS_ObjectNotWritten(JSStructuredCloneWriter
* w
,
778 JS::HandleObject obj
);
780 JS_PUBLIC_API
JS::StructuredCloneScope
JS_GetStructuredCloneScope(
781 JSStructuredCloneWriter
* w
);
783 #endif /* js_StructuredClone_h */