Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-01 06:35:42 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
f7d7e441ed
gecko-dev/docshell/base/nsIDocShell.idl

717 lines
26 KiB
Plaintext
Raw Blame History

/* -*- Mode: IDL; tab-width: 4; 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"
#include "nsIAtom.idl"
%{ C++
class nsPresContext;
class nsIPresShell;
struct JSContext;
%}
/**
* The nsIDocShell interface.
*/
[ptr] native nsPresContext(nsPresContext);
[ptr] native nsIPresShell(nsIPresShell);
interface nsIURI;
interface nsIChannel;
interface nsIContentViewer;
interface nsIURIContentListener;
interface nsIDOMEventTarget;
interface nsIDocShellLoadInfo;
interface nsIWebNavigation;
interface nsISimpleEnumerator;
interface nsIInputStream;
interface nsIRequest;
interface nsISHEntry;
interface nsILayoutHistoryState;
interface nsISecureBrowserUI;
interface nsIDOMStorage;
interface nsIPrincipal;
interface nsIWebBrowserPrint;
interface nsIVariant;
interface nsIPrivacyTransitionObserver;
[scriptable, builtinclass, uuid(a106db7f-6449-4a6b-914f-834ba308c3e2)]
interface nsIDocShell : nsISupports
{
/**
* Loads a given URI. This will give priority to loading the requested URI
* in the object implementing this interface. If it can't be loaded here
* however, the URL dispatcher will go through its normal process of content
* loading.
*
* @param uri - The URI to load.
* @param loadInfo - This is the extended load info for this load. This
* most often will be null, but if you need to do
* additional setup for this load you can get a loadInfo
* object by calling createLoadInfo. Once you have this
* object you can set the needed properties on it and
* then pass it to loadURI.
* @param aLoadFlags - Flags to modify load behaviour. Flags are defined in
* nsIWebNavigation. Note that using flags outside
* LOAD_FLAGS_MASK is only allowed if passing in a
* non-null loadInfo. And even some of those might not
* be allowed. Use at your own risk.
*/
[noscript]void loadURI(in nsIURI uri,
in nsIDocShellLoadInfo loadInfo,
in unsigned long aLoadFlags,
in boolean firstParty);
/**
* Loads a given stream. This will give priority to loading the requested
* stream in the object implementing this interface. If it can't be loaded
* here however, the URL dispatched will go through its normal process of
* content loading.
*
* @param aStream - The input stream that provides access to the data
* to be loaded. This must be a blocking, threadsafe
* stream implementation.
* @param aURI - The URI representing the stream, or null.
* @param aContentType - The type (MIME) of data being loaded (empty if unknown).
* @param aContentCharset - The charset of the data being loaded (empty if unknown).
* @param aLoadInfo - This is the extended load info for this load. This
* most often will be null, but if you need to do
* additional setup for this load you can get a
* loadInfo object by calling createLoadInfo. Once
* you have this object you can set the needed
* properties on it and then pass it to loadStream.
*/
[noscript]void loadStream(in nsIInputStream aStream,
in nsIURI aURI,
in ACString aContentType,
in ACString aContentCharset,
in nsIDocShellLoadInfo aLoadInfo);
const long INTERNAL_LOAD_FLAGS_NONE = 0x0;
const long INTERNAL_LOAD_FLAGS_INHERIT_OWNER = 0x1;
const long INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER = 0x2;
const long INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x4;
// This flag marks the first load in this object
// @see nsIWebNavigation::LOAD_FLAGS_FIRST_LOAD
const long INTERNAL_LOAD_FLAGS_FIRST_LOAD = 0x8;
const long INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER = 0x10;
const long INTERNAL_LOAD_FLAGS_FORCE_ALLOW_COOKIES = 0x20;
/**
* Loads the given URI. This method is identical to loadURI(...) except
* that its parameter list is broken out instead of being packaged inside
* of an nsIDocShellLoadInfo object...
*
* @param aURI - The URI to load.
* @param aReferrer - Referring URI
* @param aOwner - Owner (security principal)
* @param aInheritOwner - Flag indicating whether the owner of the current
* document should be inherited if aOwner is null.
* @param aStopActiveDoc - Flag indicating whether loading the current
* document should be stopped.
* @param aWindowTarget - Window target for the load.
* @param aTypeHint - A hint as to the content-type of the resulting
* data. May be null or empty if no hint.
* @param aFileName - Non-null when the link should be downloaded as
the given filename.
* @param aPostDataStream - Post data stream (if POSTing)
* @param aHeadersStream - Stream containing "extra" request headers...
* @param aLoadFlags - Flags to modify load behaviour. Flags are defined
* in nsIWebNavigation.
* @param aSHEntry - Active Session History entry (if loading from SH)
*/
[noscript]void internalLoad(in nsIURI aURI,
in nsIURI aReferrer,
in nsISupports aOwner,
in uint32_t aFlags,
in wstring aWindowTarget,
in string aTypeHint,
in AString aFileName,
in nsIInputStream aPostDataStream,
in nsIInputStream aHeadersStream,
in unsigned long aLoadFlags,
in nsISHEntry aSHEntry,
in boolean firstParty,
out nsIDocShell aDocShell,
out nsIRequest aRequest);
/**
* Do either a history.pushState() or history.replaceState() operation,
* depending on the value of aReplace.
*/
[implicit_jscontext]
void addState(in nsIVariant aData, in DOMString aTitle,
in DOMString aURL, in boolean aReplace);
/**
* Creates a DocShellLoadInfo object that you can manipulate and then pass
* to loadURI.
*/
void createLoadInfo(out nsIDocShellLoadInfo loadInfo);
/**
* Reset state to a new content model within the current document and the document
* viewer. Called by the document before initiating an out of band document.write().
*/
void prepareForNewContentModel();
/**
* For editors and suchlike who wish to change the URI associated with the
* document. Note if you want to get the current URI, use the read-only
* property on nsIWebNavigation.
*/
void setCurrentURI(in nsIURI aURI);
/**
* Notify the associated content viewer and all child docshells that they are
* about to be hidden. If |isUnload| is true, then the document is being
* unloaded as well.
*
* @param isUnload if true, fire the unload event in addition to the pagehide
* event.
*/
[noscript] void firePageHideNotification(in boolean isUnload);
/**
* Presentation context for the currently loaded document. This may be null.
*/
[noscript] readonly attribute nsPresContext presContext;
/**
* Presentation shell for the currently loaded document. This may be null.
*/
[noscript] readonly attribute nsIPresShell presShell;
/**
* Presentation shell for the oldest document, if this docshell is
* currently transitioning between documents.
*/
[noscript] readonly attribute nsIPresShell eldestPresShell;
/**
* Content Viewer that is currently loaded for this DocShell. This may
* change as the underlying content changes.
*/
readonly attribute nsIContentViewer contentViewer;
/**
* This attribute allows chrome to tie in to handle DOM events that may
* be of interest to chrome.
*/
attribute nsIDOMEventTarget chromeEventHandler;
/**
* Whether to allow plugin execution
*/
attribute boolean allowPlugins;
/**
* Whether to allow Javascript execution
*/
attribute boolean allowJavascript;
/**
* Attribute stating if refresh based redirects can be allowed
*/
attribute boolean allowMetaRedirects;
/**
* Attribute stating if it should allow subframes (framesets/iframes) or not
*/
attribute boolean allowSubframes;
/**
* Attribute stating whether or not images should be loaded.
*/
attribute boolean allowImages;
/**
* Attribute that determines whether DNS prefetch is allowed for this subtree
* of the docshell tree. Defaults to true. Setting this will make it take
* effect starting with the next document loaded in the docshell.
*/
attribute boolean allowDNSPrefetch;
/**
* Attribute that determines whether window control (move/resize) is allowed.
*/
attribute boolean allowWindowControl;
/**
* Get an enumerator over this docShell and its children.
*
* @param aItemType - Only include docShells of this type, or if typeAll,
* include all child shells.
* Uses types from nsIDocShellTreeItem.
* @param aDirection - Whether to enumerate forwards or backwards.
*/
const long ENUMERATE_FORWARDS = 0;
const long ENUMERATE_BACKWARDS = 1;
nsISimpleEnumerator getDocShellEnumerator(in long aItemType,
in long aDirection);
/**
* The type of application that created this window
*/
const unsigned long APP_TYPE_UNKNOWN = 0;
const unsigned long APP_TYPE_MAIL = 1;
const unsigned long APP_TYPE_EDITOR = 2;
attribute unsigned long appType;
/**
* certain dochshells (like the message pane)
* should not throw up auth dialogs
* because it can act as a password trojan
*/
attribute boolean allowAuth;
/**
* Set/Get the document scale factor. When setting this attribute, a
* NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
* not supporting zoom. Implementations not supporting zoom should return
* 1.0 all the time for the Get operation. 1.0 by the way is the default
* of zoom. This means 100% of normal scaling or in other words normal size
* no zoom.
*/
attribute float zoom;
/*
* The size, in CSS pixels, of the horizontal margins for the <body> of an
* HTML document in this docshel; used to implement the marginwidth attribute
* on HTML <frame>/<iframe> elements. A value smaller than zero indicates
* that the attribute was not set.
*/
attribute long marginWidth;
/*
* The size, in CSS pixels, of the vertical margins for the <body> of an HTML
* document in this docshel; used to implement the marginheight attribute on
* HTML <frame>/<iframe> elements. A value smaller than zero indicates that
* the attribute was not set.
*/
attribute long marginHeight;
/*
* Tells the docshell to offer focus to its tree owner.
* This is currently only necessary for embedding chrome.
*/
void tabToTreeOwner(in boolean forward,
out boolean tookFocus);
/**
* Current busy state for DocShell
*/
const unsigned long BUSY_FLAGS_NONE = 0;
const unsigned long BUSY_FLAGS_BUSY = 1;
const unsigned long BUSY_FLAGS_BEFORE_PAGE_LOAD = 2;
const unsigned long BUSY_FLAGS_PAGE_LOADING = 4;
/**
* Load commands for the document
*/
const unsigned long LOAD_CMD_NORMAL = 0x1; // Normal load
const unsigned long LOAD_CMD_RELOAD = 0x2; // Reload
const unsigned long LOAD_CMD_HISTORY = 0x4; // Load from history
const unsigned long LOAD_CMD_PUSHSTATE = 0x8; // History.pushState()
readonly attribute unsigned long busyFlags;
/*
* attribute to access the loadtype for the document
*/
attribute unsigned long loadType;
/*
* returns true if the docshell is being destroyed, false otherwise
*/
boolean isBeingDestroyed();
/*
* Returns true if the docshell is currently executing the onLoad Handler
*/
readonly attribute boolean isExecutingOnLoadHandler;
attribute nsILayoutHistoryState layoutHistoryState;
readonly attribute boolean shouldSaveLayoutState;
/**
* The SecureBrowserUI object for this docshell. This is set by XUL
* <browser> or nsWebBrowser for their root docshell.
*/
attribute nsISecureBrowserUI securityUI;
/**
* Cancel the XPCOM timers for each meta-refresh URI in this docshell,
* and this docshell's children, recursively. The meta-refresh timers can be
* restarted using resumeRefreshURIs(). If the timers are already suspended,
* this has no effect.
*/
void suspendRefreshURIs();
/**
* Restart the XPCOM timers for each meta-refresh URI in this docshell,
* and this docshell's children, recursively. If the timers are already
* running, this has no effect.
*/
void resumeRefreshURIs();
/**
* Begin firing WebProgressListener notifications for restoring a page
* presentation. |viewer| is the content viewer whose document we are
* starting to load. If null, it defaults to the docshell's current content
* viewer, creating one if necessary. |top| should be true for the toplevel
* docshell that is being restored; it will be set to false when this method
* is called for child docshells. This method will post an event to
* complete the simulated load after returning to the event loop.
*/
void beginRestore(in nsIContentViewer viewer, in boolean top);
/**
* Finish firing WebProgressListener notifications and DOM events for
* restoring a page presentation. This should only be called via
* beginRestore().
*/
void finishRestore();
/* Track whether we're currently restoring a document presentation. */
readonly attribute boolean restoringDocument;
/* attribute to access whether error pages are enabled */
attribute boolean useErrorPages;
/**
* Keeps track of the previous SHTransaction index and the current
* SHTransaction index at the time that the doc shell begins to load.
* Used for ContentViewer eviction.
*/
readonly attribute long previousTransIndex;
readonly attribute long loadedTransIndex;
/**
* Notification that entries have been removed from the beginning of a
* nsSHistory which has this as its rootDocShell.
*
* @param numEntries - The number of entries removed
*/
void historyPurged(in long numEntries);
/*
* Retrieves the WebApps session storage object for the supplied principal.
*
* @param principal returns a storage for this principal
* @param documentURI new storage will be created with reference to this
* document.documentURI that will appear in storage event
* @param create If true and a session storage object doesn't
* already exist, a new one will be created.
*/
nsIDOMStorage getSessionStorageForPrincipal(in nsIPrincipal principal,
in DOMString documentURI,
in boolean create);
/*
* Add a WebApps session storage object to the docshell.
*
* @param principal the principal the storage object is associated with
* @param storage the storage object to add
*/
void addSessionStorage(in nsIPrincipal principal, in nsIDOMStorage storage);
/**
* Clones all session storage objects and attaches them to the given docshell.
* Useful when duplicating tabs and their states.
*
* @param docShell the docshell to clone the sessionstorage objects to
*/
void cloneSessionStoragesTo(in nsIDocShell docShell);
/**
* Removes all WebApps session storage objects attached to the docshell.
*/
void clearSessionStorages();
/**
* Gets the channel for the currently loaded document, if any.
* For a new document load, this will be the channel of the previous document
* until after OnLocationChange fires.
*/
readonly attribute nsIChannel currentDocumentChannel;
/**
* Set the offset of this child in its container.
*/
[noscript] void setChildOffset(in unsigned long offset);
/**
* Find out whether the docshell is currently in the middle of a page
* transition. This is set just before the pagehide/unload events fire.
*/
readonly attribute boolean isInUnload;
/**
* Find out if the currently loaded document came from a suspicious channel
* (such as a JAR channel where the server-returned content type isn't a
* known JAR type).
*/
readonly attribute boolean channelIsUnsafe;
/**
* Disconnects this docshell's editor from its window, and stores the
* editor data in the open document's session history entry. This
* should be called only during page transitions.
*/
[noscript, notxpcom] void DetachEditorFromWindow();
/**
* If true, this browser is not visible in the traditional sense, but
* is actively being rendered to the screen (ex. painted on a canvas)
* and should be treated accordingly.
**/
attribute boolean isOffScreenBrowser;
/**
* If the current content viewer isn't initialized for print preview,
* it is replaced with one which is and to which an about:blank document
* is loaded.
*/
readonly attribute nsIWebBrowserPrint printPreview;
/**
* Whether this docshell can execute scripts based on its hierarchy.
* The rule of thumb here is that we disable js if this docshell or any
* of its parents disallow scripting, unless the only reason for js being
* disabled in this docshell is a parent docshell having a document that
* is in design mode. In that case, we explicitly allow scripting on the
* current docshell.
*/
readonly attribute boolean canExecuteScripts;
/**
* Sets whether a docshell is active. An active docshell is one that is
* visible, and thus is not a good candidate for certain optimizations
* like image frame discarding. Docshells are active unless told otherwise.
*/
attribute boolean isActive;
/**
* The ID of the docshell in the session history.
*/
readonly attribute unsigned long long historyID;
/**
* Sets whether a docshell is an app tab. An app tab docshell may behave
* differently than a non-app tab docshell in some cases, such as when
* handling link clicks. Docshells are not app tabs unless told otherwise.
*/
attribute boolean isAppTab;
/**
* Create a new about:blank document and content viewer.
* @param aPrincipal the principal to use for the new document.
*/
void createAboutBlankContentViewer(in nsIPrincipal aPrincipal);
/**
* The charset attribute allows the user to view, hint, and set which
* converter is used to read the document's data.
*
* <P>Inside Mozilla all text is encoded as Unicode. By standardizing
* on Unicode every piece of code that handles characters no longer
* needs to:
*
* Have access to a character encoding parameter.
* Ask is the data stateful?
* Ask is the data single byte?
* Ask is the data multi-byte?
* If multi-byte: have access to a routine that can
* determine how many bytes in the current character.
*
* When the document is read in a converter is used to convert
* the document's data to Unicode.
*
* The charset attribute provides the ability to:
*
* See what converter was used when inputting the documents
* data.
*
* Override the character set for documents where the specified
* fallback, or auto-detected character set is incorrect
*
* Get/sets the encoding (converter) used to read the
* document. Get returns the encoding used. Set forces
* (overrides) the encoding. After forcing the charset the
* embedding application will need to cause the data to be
* reparsed in order to update the DOM / display.
*
* A force also sets the fallback encoding for this frame.
*/
attribute string charset;
/**
* The charset forced by the user. When the charset attribute is set this
* attribute is set to the same value.
*
* XXX Could this be replaced by a boolean?
*/
attribute nsIAtom forcedCharset;
/**
* In a child docshell, this is the charset of the parent docshell
*/
attribute nsIAtom parentCharset;
/*
* In a child docshell, this is the source of parentCharset
* @see nsIParser
*/
attribute int32_t parentCharsetSource;
/**
* Add an observer to the list of parties to be notified when this docshell's
* private browsing status is changed. |obs| must support weak references.
*/
void addWeakPrivacyTransitionObserver(in nsIPrivacyTransitionObserver obs);
/**
* Returns true if this docshell corresponds to an <iframe mozbrowser>.
* (<iframe mozapp mozbrowser> is not considered a browser.)
*/
[infallible] readonly attribute boolean isBrowserElement;
/**
* Returns true iff the docshell corresponds to an <iframe mozapp>.
*/
[infallible] readonly attribute boolean isApp;
/**
* Returns isBrowserElement || isApp.
*/
[infallible] readonly attribute boolean isBrowserOrApp;
/**
* Returns true if this docshell corresponds to an <iframe mozbrowser> or if
* the docshell is contained in an <iframe mozbrowser>. (<iframe mozapp
* mozbrowser> does not count as a browser.)
*
* Our notion here of "contained in" means: Walk up the docshell hierarchy in
* this process until we hit an <iframe mozapp> or <iframe mozbrowser> (or
* until the hierarchy ends). Return true iff the docshell we stopped on has
* isBrowserElement == true.
*/
[infallible] readonly attribute boolean isInBrowserElement;
/**
* Returns true if this docshell corresponds to an <iframe mozbrowser> or
* <iframe mozap>, or if this docshell is contained in an <iframe mozbrowser>
* or <iframe mozapp>.
*
* To compute this value, we walk up the docshell hierarchy. If we encounter
* a docshell with isBrowserElement or isApp before we hit the end of the
* hierarchy, we return true. Otherwise, we return false.
*/
[infallible] readonly attribute boolean isInBrowserOrApp;
/**
* Indicate that this docshell corresponds to an app with the given app id.
*
* You may pass NO_APP_ID or UNKNOWN_APP_ID for containingAppId. If you
* pass NO_APP_ID, then this docshell will return NO_APP_ID for appId. If
* you pass UNKNOWN_APP_ID, then this docshell will search its hiearchy for
* an app frame and use that frame's appId.
*
* You can call this method more than once, but there's no guarantee that
* other components will update their view of the world if you change a
* docshell's app id, so tread lightly.
*
* If you call this method after calling setIsBrowserInsideApp, this
* docshell will forget the fact that it was a browser.
*/
void setIsApp(in unsigned long ownAppId);
/**
* Indicate that this docshell corresponds to a browser inside an app with
* the given ID. As with setIsApp, you may pass NO_APP_ID or
* UNKNOWN_APP_ID.
*
* As with setIsApp, you may call this more than once, but it's kind of a
* hack, so be careful.
*/
void setIsBrowserInsideApp(in unsigned long containingAppId);
/**
* Returns the id of the app associated with this docshell. If this docshell
* is an <iframe mozbrowser> inside an <iframe mozapp>, we return the app's
* appId.
*
* We compute this value by walking up the docshell hierarchy until we find a
* docshell on which setIsApp(x) or setIsBrowserInsideApp(x) was called
* (ignoring those docshells where x == UNKNOWN_APP_ID). We return the app
* id x.
*
* If we don't find a docshell with an associated app id in our hierarchy, we
* return NO_APP_ID. We never return UNKNOWN_APP_ID.
*
* Notice that a docshell may have an associated app even if it returns true
* for isBrowserElement!
*/
[infallible] readonly attribute unsigned long appId;
/**
* Like nsIDocShellTreeItem::GetSameTypeParent, except this ignores <iframe
* mozbrowser> and <iframe mozapp> boundaries.
*/
nsIDocShell getSameTypeParentIgnoreBrowserAndAppBoundaries();
/**
* True iff asynchronous panning and zooming is enabled for this
* docshell.
*/
readonly attribute bool asyncPanZoomEnabled;
/**
* The sandbox flags on the docshell. These reflect the value of the sandbox
* attribute of the associated IFRAME or CSP-protectable content, if
* existent. See the HTML5 spec for more details.
* These flags on the docshell reflect the current state of the sandbox
* attribute, which is modifiable. They are only used when loading new
* content, sandbox flags are also immutably set on the document when it is
* loaded.
* The sandbox flags of a document depend on the sandbox flags on its
* docshell and of its parent document, if any.
* See nsSandboxFlags.h for the possible flags.
*/
attribute unsigned long sandboxFlags;
/**
* Are plugins allowed in the current document loaded in this docshell ?
* (if there is one). This depends on whether plugins are allowed by this
* docshell itself or if the document is sandboxed and hence plugins should
* not be allowed.
*/
[noscript, notxpcom] bool pluginsAllowedInCurrentDoc();
/**
* Attribute that determines whether fullscreen is allowed to be entered for
* this subtree of the docshell tree. This is true when all iframes containing
* this docshell have their "allowfullscreen" attribute set to "true".
* fullscreenAllowed is only writable at content boundaries, where it is used
* to propagate the value of the cross process parent's iframe's
* "allowfullscreen" attribute to the child process. Setting
* fullscreenAllowed on docshells which aren't content boundaries throws an
* exception.
*/
[infallible] readonly attribute boolean fullscreenAllowed;
void setFullscreenAllowed(in boolean allowed);
};
Reference in New Issue View Git Blame Copy Permalink