/* -*- Mode: IDL; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * 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/. */

#include "nsISupports.idl"

interface nsIWebBrowserPersistDocumentReceiver;

/**
 * Interface for objects which represent a document that can be
 * serialized with nsIWebBrowserPersist.  This interface is
 * asynchronous because the actual document can be in another process
 * (e.g., if this object is an nsFrameLoader for an out-of-process
 * frame).
 *
 * Warning: this is currently implemented only by nsFrameLoader, and
 * may change in the future to become more frame-loader-specific or be
 * merged into nsIFrameLoader.  See bug 1101100 comment #34.
 *
 * @see nsIWebBrowserPersistDocumentReceiver
 * @see nsIWebBrowserPersistDocument
 * @see nsIWebBrowserPersist
 *
 * @param aOuterWindowID
 *        The outer window ID of the subframe we'd like to persist.
 *        If set at 0, nsIWebBrowserPersistable will attempt to persist
 *        the top-level document. If the outer window ID is for a subframe
 *        that does not exist, or is not held beneath the nsIWebBrowserPersistable,
 *        aRecv's onError method will be called with NS_ERROR_NO_CONTENT.
 * @param aRecv
 *        The nsIWebBrowserPersistDocumentReceiver is a callback that
 *        will be fired once the document is ready for persisting.
 */
[scriptable, uuid(f4c3fa8e-83e9-49f8-ac6f-951fc7541fe4)]
interface nsIWebBrowserPersistable : nsISupports
{
  void startPersistence(in unsigned long long aOuterWindowID,
                        in nsIWebBrowserPersistDocumentReceiver aRecv);
};