wine/gecko
0
0
Fork 0
mirror of https://gitlab.winehq.org/wine/wine-gecko.git synced 2024-09-13 09:24:08 -07:00
Code Issues Packages Projects Releases Wiki Activity
0cae034974
gecko/docshell/base/nsIDocShell.idl

689 lines
24 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(9b283337-097d-4fa8-a2da-916318eaf828)]
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 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 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);
/**
* Mark the docshell as a browser frame.
* This should be used for <iframe mozbrowser> but not for <iframe mozapp>.
*
* This method should not be called more than once.
*/
void setIsBrowserElement();
/**
* Returns true iff the docshell is marked as a browser frame.
*/
[infallible] readonly attribute boolean isBrowserElement;
/**
* Returns true iif the docshell is marked as an app frame.
*/
[infallible] readonly attribute boolean isApp;
/**
* Returns true iif the docshell is marked as a type that behaves like a
* content boundary.
*/
[infallible] readonly attribute boolean isContentBoundary;
/**
* Returns true iif the docshell is inside a browser element.
*/
[infallible] readonly attribute boolean isInBrowserElement;
/**
* Returns true iif the docshell is inside an application. However, it will
* return false if the docshell is inside a browser element that is inside
* an application.
*
* Note: Do not use this method for permissions checks! An app may contain
* an <iframe> pointing at arbitrary web code. This iframe's docshell will
* have isInApp() == true, but the iframe's content is not "app code", and
* so should not be granted more trust than vanilla web content.
*
* (For example, suppose when web content calls API method X, we show a
* permission prompt, but when "app code" calls method X, we don't. In this
* case, it would be /incorrect/ to show the permission prompt if
* !isInApp().)
*
* If you're doing a security check, use the content's principal instead of
* this method.
*/
[infallible] readonly attribute boolean isInApp;
/**
* Returns if the docshell has a docshell that behaves as a content boundary
* in his parent hierarchy.
*/
[infallible] readonly attribute boolean isBelowContentBoundary;
/**
* Set the app id this docshell is associated with. The id has to be a valid
* app id. If the docshell isn't associated with any app, the value should be
* nsIScriptSecurityManager::NO_APP_ID. However, this is the default value if
* nothing is et.
*
* This method is [noscript] to reduce the scope. It should be used at very
* specific moments.
*
* Calling setAppId() will mark the frame as an app frame.
*/
[noscript] void setAppId(in unsigned long appId);
/**
* Returns the app id of the app the docshell is in. Returns
* nsIScriptSecurityManager::NO_APP_ID if the docshell is not in an app.
*/
[infallible] readonly attribute unsigned long appId;
/**
* True iff asynchronous panning and zooming is enabled for this
* docshell.
*/
readonly attribute bool asyncPanZoomEnabled;
/**
* Like GetSameTypeParent, except this ignores <iframe mozbrowser>
* boundaries.
*/
nsIDocShell getParentIgnoreBrowserFrame();
/**
* 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();
};
Reference in New Issue View Git Blame Copy Permalink