gecko/docshell/shistory/public/nsISHEntry.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Radha Kulkarni <radha@netscape.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/**
 * The interface to nsISHentry. Each document or subframe in 
 * Session History will have a nsISHEntry associated with it which will
 * hold all information required to recreate the document from history
 * 
 */
#include "nsIHistoryEntry.idl"

interface nsILayoutHistoryState;
interface nsIContentViewer;
interface nsIURI;
interface nsIInputStream;
interface nsIDocShellTreeItem;
interface nsISupportsArray;
%{C++
struct nsIntRect;
class nsDocShellEditorData;
%}
[ref] native nsIntRect(nsIntRect);
[ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);


[scriptable, uuid(39b73c3a-48eb-4189-8069-247279c3c42d)]
interface nsISHEntry : nsIHistoryEntry
{
    /** URI for the document */
    void setURI(in nsIURI aURI);

    /** Referrer URI */
    attribute nsIURI referrerURI;

    /** Content viewer, for fast restoration of presentation */
    attribute nsIContentViewer contentViewer;

    /** Whether the content viewer is marked "sticky" */
    attribute boolean sticky;

    /** Saved state of the global window object */
    attribute nsISupports windowState;

    /**
     * Saved position and dimensions of the content viewer; we must adjust the
     * root view's widget accordingly if this has changed when the presentation
     * is restored.
     */
    [noscript] void getViewerBounds(in nsIntRect bounds);
    [noscript] void setViewerBounds([const] in nsIntRect bounds);

    /**
     * Saved child docshells corresponding to contentViewer.  The child shells
     * are restored as children of the parent docshell, in this order, when the
     * parent docshell restores a saved presentation.
     */

    /** Append a child shell to the end of our list. */
    void addChildShell(in nsIDocShellTreeItem shell);

    /**
     * Get the child shell at |index|; returns null if |index| is out of bounds.
     */
    nsIDocShellTreeItem childShellAt(in long index);

    /**
     * Clear the child shell list.
     */
    void clearChildShells();

    /** Saved refresh URI list for the content viewer */
    attribute nsISupportsArray refreshURIList;

    /**
     * Ensure that the cached presentation members are self-consistent.
     * If either |contentViewer| or |windowState| are null, then all of the
     * following members are cleared/reset:
     *  contentViewer, sticky, windowState, viewerBounds, childShells,
     *  refreshURIList.
     */
    void syncPresentationState();

    /** Title for the document */
    void setTitle(in AString aTitle);

    /** Post Data for the document */
    attribute nsIInputStream postData;

    /** LayoutHistoryState for scroll position and form values */
    attribute nsILayoutHistoryState layoutHistoryState;

    /** parent of this entry */
    attribute nsISHEntry parent;

    /**
     * The loadType for this entry. This is typically loadHistory except
     * when reload is pressed, it has the appropriate reload flag
     */
    attribute unsigned long loadType;

    /**
     * An ID to help identify this entry from others during
     * subframe navigation
     */
    attribute unsigned long ID;

    /**
     * pageIdentifier is an integer that should be the same for two entries
     * attached to the same docshell only if the two entries are entries for
     * the same page in the sense that one could go from the state represented
     * by one to the state represented by the other simply by scrolling (so the
     * entries are separated by an anchor traversal or a subframe navigation in
     * some other frame).
     */
    attribute unsigned long pageIdentifier;

    /**
     * docIdentifier is an integer that should be the same for two entries
     * attached to the same docshell if and only if the two entries are entries
     * for the same document.  In practice, two entries A and B will have the
     * same docIdentifier if they have the same pageIdentifier or if B was
     * created by A calling history.pushState().
     */
    attribute unsigned long long docIdentifier;

    /**
     * Changes this entry's doc identifier to a new value which is unique
     * among those of all other entries.
     */
    void setUniqueDocIdentifier();

    /** attribute to set and get the cache key for the entry */
    attribute nsISupports cacheKey;

    /** attribute to indicate whether layoutHistoryState should be saved */
    attribute boolean saveLayoutStateFlag;

    /** attribute to indicate whether the page is already expired in cache */
    attribute boolean expirationStatus;

    /**
     * attribute to indicate the content-type of the document that this
     * is a session history entry for
     */
    attribute ACString contentType; 
 
    /** Set/Get scrollers' positon in anchored pages */
    void setScrollPosition(in long x, in long y);
    void getScrollPosition(out long x, out long y);

    /** Additional ways to create an entry */
    [noscript] void create(in nsIURI URI, in AString title,
                           in nsIInputStream inputStream,
                           in nsILayoutHistoryState layoutHistoryState,
                           in nsISupports cacheKey, in ACString contentType,
                           in nsISupports owner,
                           in unsigned long long docshellID,
                           in boolean dynamicCreation);

    nsISHEntry clone();

    /** Attribute that indicates if this entry is for a subframe navigation */
    void setIsSubFrame(in boolean aFlag);

    /** Return any content viewer present in or below this node in the
        nsSHEntry tree.  This will differ from contentViewer in the case
        where a child nsSHEntry has the content viewer for this tree. */
    nsIContentViewer getAnyContentViewer(out nsISHEntry ownerEntry);

    /**
     * Get the owner, if any, that was associated with the channel
     * that the document that was loaded to create this history entry
     * came from.
     */
    attribute nsISupports owner;

    /**
     * Get/set data associated with this history state via a pushState() call,
     * encoded as JSON.
     **/
    attribute AString stateData;

    /**
     * Gets the owning pointer to the editor data assosicated with
     * this shistory entry. This forgets its pointer, so free it when
     * you're done.
     */
    [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();

    /**
     * Sets the owning pointer to the editor data assosicated with
     * this shistory entry. Unless forgetEditorData() is called, this
     * shentry will destroy the editor data when it's destroyed.
     */
    [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);

    /** Returns true if this shistory entry is storing a detached editor. */
    [noscript, notxpcom] boolean hasDetachedEditor();

    /**
     * Returns true if the related docshell was added because of
     * dynamic addition of an iframe/frame.
     */
    boolean isDynamicallyAdded();

    /**
     * Returns true if any of the child entries returns true
     * when isDynamicallyAdded is called on it.
     */
    boolean hasDynamicallyAddedChild();

    /**
     * The history ID of the docshell.
     */
    attribute unsigned long long docshellID;
};


%{ C++
// {BFD1A791-AD9F-11d3-BDC7-0050040A9B44}
#define NS_SHENTRY_CID \
{0xbfd1a791, 0xad9f, 0x11d3, {0xbd, 0xc7, 0x0, 0x50, 0x4, 0xa, 0x9b, 0x44}}

#define NS_SHENTRY_CONTRACTID \
    "@mozilla.org/browser/session-history-entry;1"

%}