Source code
Revision control
Copy as Markdown
Other Tools
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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 mozilla_dom_StructuredCloneHolder_h
#define mozilla_dom_StructuredCloneHolder_h
#include <cstddef>
#include <cstdint>
#include <utility>
#include "js/StructuredClone.h"
#include "js/TypeDecls.h"
#include "mozilla/Assertions.h"
#include "mozilla/MemoryReporting.h"
#include "mozilla/ProcessType.h"
#include "mozilla/RefPtr.h"
#include "mozilla/UniquePtr.h"
#include "mozilla/ipc/EagerIPCStream.h"
#include "nsCOMPtr.h"
#include "nsString.h"
#include "nsTArray.h"
class nsIEventTarget;
class nsIGlobalObject;
class nsIInputStream;
struct JSStructuredCloneReader;
struct JSStructuredCloneWriter;
namespace JS {
class Value;
struct WasmModule;
} // namespace JS
namespace mozilla {
class ErrorResult;
template <class T>
class OwningNonNull;
namespace layers {
class Image;
}
namespace gfx {
class DataSourceSurface;
}
namespace dom {
class BlobImpl;
class MessagePort;
class MessagePortIdentifier;
template <typename T>
class Sequence;
class StructuredCloneHolderBase {
public:
typedef JS::StructuredCloneScope StructuredCloneScope;
StructuredCloneHolderBase(
StructuredCloneScope aScope = StructuredCloneScope::SameProcess);
virtual ~StructuredCloneHolderBase();
// Note, it is unsafe to std::move() a StructuredCloneHolderBase since a raw
// this pointer is passed to mBuffer as a callback closure. That must
// be fixed if you want to implement a move constructor here.
StructuredCloneHolderBase(StructuredCloneHolderBase&& aOther) = delete;
// These methods should be implemented in order to clone data.
// Read more documentation in js/public/StructuredClone.h.
virtual JSObject* CustomReadHandler(
JSContext* aCx, JSStructuredCloneReader* aReader,
const JS::CloneDataPolicy& aCloneDataPolicy, uint32_t aTag,
uint32_t aIndex) = 0;
virtual bool CustomWriteHandler(JSContext* aCx,
JSStructuredCloneWriter* aWriter,
JS::Handle<JSObject*> aObj,
bool* aSameProcessScopeRequired) = 0;
// This method has to be called when this object is not needed anymore.
// It will free memory and the buffer. This has to be called because
// otherwise the buffer will be freed in the DTOR of this class and at that
// point we cannot use the overridden methods.
void Clear();
// If these 3 methods are not implement, transfering objects will not be
// allowed. Otherwise only arrayBuffers will be transferred.
virtual bool CustomReadTransferHandler(
JSContext* aCx, JSStructuredCloneReader* aReader,
const JS::CloneDataPolicy& aCloneDataPolicy, uint32_t aTag,
void* aContent, uint64_t aExtraData,
JS::MutableHandle<JSObject*> aReturnObject);
virtual bool CustomWriteTransferHandler(JSContext* aCx,
JS::Handle<JSObject*> aObj,
// Output:
uint32_t* aTag,
JS::TransferableOwnership* aOwnership,
void** aContent,
uint64_t* aExtraData);
virtual void CustomFreeTransferHandler(uint32_t aTag,
JS::TransferableOwnership aOwnership,
void* aContent, uint64_t aExtraData);
virtual bool CustomCanTransferHandler(JSContext* aCx,
JS::Handle<JSObject*> aObj,
bool* aSameProcessScopeRequired);
// These methods are what you should use to read/write data.
// Execute the serialization of aValue using the Structured Clone Algorithm.
// The data can read back using Read().
void Write(JSContext* aCx, JS::Handle<JS::Value> aValue, ErrorResult& aRv);
// Like Write() but it supports the transferring of objects and handling
// of cloning policy.
void Write(JSContext* aCx, JS::Handle<JS::Value> aValue,
JS::Handle<JS::Value> aTransfer,
const JS::CloneDataPolicy& aCloneDataPolicy, ErrorResult& aRv);
// If Write() has been called, this method retrieves data and stores it into
// aValue.
void Read(JSContext* aCx, JS::MutableHandle<JS::Value> aValue,
ErrorResult& aRv);
// Like Read() but it supports handling of clone policy.
void Read(JSContext* aCx, JS::MutableHandle<JS::Value> aValue,
const JS::CloneDataPolicy& aCloneDataPolicy, ErrorResult& aRv);
// Directly adopt a pre-existing data buffer which was previously serialized
// elsewhere using this data structure.
// The StructuredCloneScope of this holder must match the passed-in data.
void Adopt(JSStructuredCloneData&& aData,
uint32_t aVersion = JS_STRUCTURED_CLONE_VERSION);
bool HasData() const { return !!mBuffer; }
JSStructuredCloneData& BufferData() const {
MOZ_ASSERT(mBuffer, "Write() has never been called.");
return mBuffer->data();
}
uint32_t BufferVersion() const {
MOZ_ASSERT(mBuffer, "Write() has never been called.");
return mBuffer->version();
}
size_t SizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf) {
size_t size = 0;
if (HasData()) {
size += mBuffer->sizeOfIncludingThis(aMallocSizeOf);
}
return size;
}
protected:
UniquePtr<JSAutoStructuredCloneBuffer> mBuffer;
StructuredCloneScope mStructuredCloneScope;
#ifdef DEBUG
bool mClearCalled;
#endif
};
class BlobImpl;
class EncodedAudioChunkData;
class EncodedVideoChunkData;
class MessagePort;
class MessagePortIdentifier;
struct VideoFrameSerializedData;
struct AudioDataSerializedData;
#ifdef MOZ_WEBRTC
struct RTCEncodedVideoFrameData;
struct RTCEncodedAudioFrameData;
#endif
class StructuredCloneHolder : public StructuredCloneHolderBase {
public:
enum CloningSupport { CloningSupported, CloningNotSupported };
enum TransferringSupport { TransferringSupported, TransferringNotSupported };
// If cloning is supported, this object will clone objects such as Blobs,
// FileList, ImageData, etc.
// If transferring is supported, we will transfer MessagePorts and in the
// future other transferrable objects.
// The StructuredCloneScope is useful to know where the cloned/transferred
// data can be read and written. Additional checks about the nature of the
// objects will be done based on this scope value because not all the
// objects can be sent between threads or processes.
explicit StructuredCloneHolder(CloningSupport aSupportsCloning,
TransferringSupport aSupportsTransferring,
StructuredCloneScope aStructuredCloneScope);
virtual ~StructuredCloneHolder();
StructuredCloneHolder(StructuredCloneHolder&& aOther) = delete;
// Normally you should just use Write() and Read().
virtual void Write(JSContext* aCx, JS::Handle<JS::Value> aValue,
ErrorResult& aRv);
virtual void Write(JSContext* aCx, JS::Handle<JS::Value> aValue,
JS::Handle<JS::Value> aTransfer,
const JS::CloneDataPolicy& aCloneDataPolicy,
ErrorResult& aRv);
void Read(JSContext* aCx, JS::MutableHandle<JS::Value> aValue,
ErrorResult& aRv);
void Read(JSContext* aCx, JS::MutableHandle<JS::Value> aValue,
const JS::CloneDataPolicy& aCloneDataPolicy, ErrorResult& aRv);
void Adopt(JSStructuredCloneData&& aData,
uint32_t aVersion = JS_STRUCTURED_CLONE_VERSION,
GeckoChildID aOriginChildID = kInvalidGeckoChildID);
// Call this method to know if this object is keeping some DOM object alive.
bool HasClonedDOMObjects();
GeckoChildID GetOriginChildID() const { return mOriginChildID; }
nsTArray<NotNull<RefPtr<BlobImpl>>>& BlobImpls() {
MOZ_ASSERT(mSupportsCloning,
"Blobs cannot be taken/set if cloning is not supported.");
return mBlobImplArray;
}
nsTArray<RefPtr<JS::WasmModule>>& WasmModules() {
MOZ_ASSERT(mSupportsCloning,
"WasmModules cannot be taken/set if cloning is not supported.");
return mWasmModuleArray;
}
nsTArray<mozilla::ipc::EagerIPCStream>& InputStreams() {
MOZ_ASSERT(mSupportsCloning,
"InputStreams cannot be taken/set if cloning is not supported.");
return mInputStreamArray;
}
// This method returns the final scope. If the final scope is unknown,
// DifferentProcess is returned because it's the most restrictive one.
StructuredCloneScope CloneScope() const {
if (mStructuredCloneScope == StructuredCloneScope::UnknownDestination) {
return StructuredCloneScope::DifferentProcess;
}
return mStructuredCloneScope;
}
// This must be called if the transferring has ports generated by Read().
// MessagePorts are not thread-safe and they must be retrieved in the thread
// where they are created.
nsTArray<RefPtr<MessagePort>>&& TakeTransferredPorts() {
MOZ_ASSERT(mSupportsTransferring);
return std::move(mTransferredPorts);
}
// This method uses TakeTransferredPorts() to populate a sequence of
// MessagePorts for WebIDL binding classes.
bool TakeTransferredPortsAsSequence(
Sequence<OwningNonNull<mozilla::dom::MessagePort>>& aPorts);
nsTArray<MessagePortIdentifier>& PortIdentifiers() const {
MOZ_ASSERT(mSupportsTransferring);
return mPortIdentifiers;
}
nsTArray<RefPtr<gfx::DataSourceSurface>>& GetSurfaces() {
return mClonedSurfaces;
}
nsTArray<VideoFrameSerializedData>& VideoFrames() { return mVideoFrames; }
nsTArray<AudioDataSerializedData>& AudioData() { return mAudioData; }
nsTArray<EncodedVideoChunkData>& EncodedVideoChunks() {
return mEncodedVideoChunks;
}
nsTArray<EncodedAudioChunkData>& EncodedAudioChunks() {
return mEncodedAudioChunks;
}
#ifdef MOZ_WEBRTC
nsTArray<RTCEncodedVideoFrameData>& RtcEncodedVideoFrames() {
return mRtcEncodedVideoFrames;
}
nsTArray<RTCEncodedAudioFrameData>& RtcEncodedAudioFrames() {
return mRtcEncodedAudioFrames;
}
#endif
// Implementations of the virtual methods to allow cloning of objects which
// JS engine itself doesn't clone.
virtual JSObject* CustomReadHandler(
JSContext* aCx, JSStructuredCloneReader* aReader,
const JS::CloneDataPolicy& aCloneDataPolicy, uint32_t aTag,
uint32_t aIndex) override;
virtual bool CustomWriteHandler(JSContext* aCx,
JSStructuredCloneWriter* aWriter,
JS::Handle<JSObject*> aObj,
bool* aSameProcessScopeRequired) override;
virtual bool CustomReadTransferHandler(
JSContext* aCx, JSStructuredCloneReader* aReader,
const JS::CloneDataPolicy& aCloneDataPolicy, uint32_t aTag,
void* aContent, uint64_t aExtraData,
JS::MutableHandle<JSObject*> aReturnObject) override;
virtual bool CustomWriteTransferHandler(JSContext* aCx,
JS::Handle<JSObject*> aObj,
uint32_t* aTag,
JS::TransferableOwnership* aOwnership,
void** aContent,
uint64_t* aExtraData) override;
virtual void CustomFreeTransferHandler(uint32_t aTag,
JS::TransferableOwnership aOwnership,
void* aContent,
uint64_t aExtraData) override;
virtual bool CustomCanTransferHandler(
JSContext* aCx, JS::Handle<JSObject*> aObj,
bool* aSameProcessScopeRequired) override;
// These 2 static methods are useful to read/write fully serializable objects.
// They can be used by custom StructuredCloneHolderBase classes to
// serialize objects such as ImageData, CryptoKey, RTCCertificate, etc.
static JSObject* ReadFullySerializableObjects(
JSContext* aCx, JSStructuredCloneReader* aReader, uint32_t aTag,
bool aIsForIndexedDB);
static bool WriteFullySerializableObjects(JSContext* aCx,
JSStructuredCloneWriter* aWriter,
JS::Handle<JSObject*> aObj);
// Helper functions for reading and writing strings.
static bool ReadString(JSStructuredCloneReader* aReader, nsString& aString);
static bool WriteString(JSStructuredCloneWriter* aWriter,
const nsAString& aString);
static bool ReadCString(JSStructuredCloneReader* aReader, nsCString& aString);
static bool WriteCString(JSStructuredCloneWriter* aWriter,
const nsACString& aString);
static const JSStructuredCloneCallbacks sCallbacks;
protected:
void SameProcessScopeRequired(bool* aSameProcessScopeRequired);
already_AddRefed<MessagePort> ReceiveMessagePort(nsIGlobalObject* aGlobal,
uint64_t aIndex);
#ifdef DEBUG
// Asserts that all of the attachment members of this StructuredCloneHolder
// match the SupportsTransferring and CloneScope flags.
void AssertAttachmentsMatchFlags();
#else
void AssertAttachmentsMatchFlags() {}
#endif
// If you add a new array for attachments below, make sure to add it to the
// appropriate tuple below. This is used for generic checks or operations
// which need to be performed over all attachment arrays.
auto CloneableAttachmentArrays() {
return std::tie(mBlobImplArray, mInputStreamArray);
}
auto InProcessCloneableAttachmentArrays() {
return std::tie(mWasmModuleArray, mClonedSurfaces, mVideoFrames, mAudioData,
mEncodedVideoChunks, mEncodedAudioChunks
#ifdef MOZ_WEBRTC
,
mRtcEncodedVideoFrames, mRtcEncodedAudioFrames
#endif
);
}
auto TransferableAttachmentArrays() {
// NOTE: mTransferredPorts is intentionally skipped, as it it not part of
// the serialized state (it is used as an extra return value from `Read`).
return std::tie(mPortIdentifiers);
}
auto AttachmentArrays() {
return std::tuple_cat(CloneableAttachmentArrays(),
InProcessCloneableAttachmentArrays(),
TransferableAttachmentArrays());
}
bool mSupportsCloning;
bool mSupportsTransferring;
// In the case where this StructuredCloneHolder was received over IPC, this
// should be set to the GeckoChildID which created the message. In the case of
// an in-process serialized data structure, it will be set to the current
// ChildID.
//
// This value is _not_ preserved if the object is sent across multiple process
// boundaries. It only tracks the most recent IPC hop.
GeckoChildID mOriginChildID = kInvalidGeckoChildID;
// SizeOfExcludingThis is inherited from StructuredCloneHolderBase. It doesn't
// account for objects in the following arrays because a) they're not expected
// to be stored in long-lived StructuredCloneHolder objects, and b) in the
// case of BlobImpl objects, MemoryBlobImpls have their own memory reporters,
// and the other types do not hold significant amounts of memory alive.
// Used for cloning blobs in the structured cloning algorithm.
nsTArray<NotNull<RefPtr<BlobImpl>>> mBlobImplArray;
// Used for cloning JS::WasmModules in the structured cloning algorithm.
nsTArray<RefPtr<JS::WasmModule>> mWasmModuleArray;
// Used for cloning InputStream in the structured cloning algorithm.
nsTArray<mozilla::ipc::EagerIPCStream> mInputStreamArray;
// This is used for sharing the backend of ImageBitmaps.
// The DataSourceSurface object must be thread-safely reference-counted.
// The DataSourceSurface object will not be written ever via any ImageBitmap
// instance, so no race condition will occur.
nsTArray<RefPtr<gfx::DataSourceSurface>> mClonedSurfaces;
// Used for cloning VideoFrame in the structured cloning algorithm.
nsTArray<VideoFrameSerializedData> mVideoFrames;
// Used for cloning AudioData in the structured cloning algorithm.
nsTArray<AudioDataSerializedData> mAudioData;
// Used for cloning EncodedVideoChunk in the structured cloning algorithm.
nsTArray<EncodedVideoChunkData> mEncodedVideoChunks;
// Used for cloning EncodedAudioChunk in the structured cloning algorithm.
nsTArray<EncodedAudioChunkData> mEncodedAudioChunks;
#ifdef MOZ_WEBRTC
// Used for cloning RTCEncodedVideoFrame in the structured cloning algorithm.
nsTArray<RTCEncodedVideoFrameData> mRtcEncodedVideoFrames;
// Used for cloning RTCEncodedAudioFrame in the structured cloning algorithm.
nsTArray<RTCEncodedAudioFrameData> mRtcEncodedAudioFrames;
#endif
// This array contains the ports once we've finished the reading. It's
// generated from the mPortIdentifiers array.
nsTArray<RefPtr<MessagePort>> mTransferredPorts;
// This array contains the identifiers of the MessagePorts. Based on these we
// are able to reconnect the new transferred ports with the other
// MessageChannel ports.
mutable nsTArray<MessagePortIdentifier> mPortIdentifiers;
};
} // namespace dom
} // namespace mozilla
#endif // mozilla_dom_StructuredCloneHolder_h