michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  * vim: set ts=8 sw=2 et tw=80:
michael@0:  *
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIVariant;
michael@0: interface nsIDocument;
michael@0: 
michael@0: %{C++
michael@0: #include "js/TypeDecls.h"
michael@0: %}
michael@0: 
michael@0: /**
michael@0:  * This interface acts as a container for an object serialized using the
michael@0:  * structured clone algorithm.
michael@0:  *
michael@0:  * You can copy an object into an nsIStructuredCloneContainer using
michael@0:  * initFromVariant or initFromBase64.  It's an error to initialize an
michael@0:  * nsIStructuredCloneContainer more than once.
michael@0:  *
michael@0:  * Once you've initialized the container, you can get a copy of the object it
michael@0:  * stores by calling deserializeToVariant.  You can also get a base-64-encoded
michael@0:  * string containing a copy of the container's serialized data, using
michael@0:  * getDataAsBase64.
michael@0:  */
michael@0: [scriptable, uuid(c8852f01-4c05-47c3-acca-253a958f39f6)]
michael@0: interface nsIStructuredCloneContainer : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Initialize this structured clone container so it contains a clone of the
michael@0:    * given jsval.
michael@0:    */
michael@0:   [noscript, implicit_jscontext]
michael@0:   void initFromJSVal(in jsval aData);
michael@0: 
michael@0:   /**
michael@0:    * Initialize this structured clone container from a base-64-encoded byte
michael@0:    * stream, stored in aData.  aFormatVersion should be the version of the
michael@0:    * structured clone algorithm which was used to generate aData.
michael@0:    */
michael@0:   [implicit_jscontext]
michael@0:   void initFromBase64(in AString aData,in unsigned long aFormatVersion);
michael@0: 
michael@0:   /**
michael@0:    * Deserialize the object this conatiner holds, returning it wrapped as
michael@0:    * an nsIVariant.
michael@0:    */
michael@0:   [implicit_jscontext]
michael@0:   nsIVariant deserializeToVariant();
michael@0: 
michael@0:   /**
michael@0:    * Get this structured clone container's data as a base-64-encoded string.
michael@0:    */
michael@0:   AString getDataAsBase64();
michael@0: 
michael@0:   /**
michael@0:    * Get the size in bytes of this container's serialized data.
michael@0:    */
michael@0:   readonly attribute unsigned long long serializedNBytes;
michael@0: 
michael@0:   /**
michael@0:    * Get the version of the structured clone algorithm which was used to
michael@0:    * generate this container's serialized buffer.
michael@0:    */
michael@0:   readonly attribute unsigned long formatVersion;
michael@0: };