ns_xulrunner_20.idl

#include "ns_generic.idl"

///////////////////////////////////////////////////////////////////////////////
//  nsIDOM3Document
///////////////////////////////////////////////////////////////////////////////

interface nsIDOMDOMConfiguration;

/**
 * For more information on this interface, please see
 * http://www.w3.org/TR/DOM-Level-3-Core/
 */
[scriptable, uuid(c0568f22-b9d5-427a-9642-b6a797edc5cd)]
interface nsIDOM3Document : nsISupports
{
  // Introduced in DOM Level 3:
  readonly attribute DOMString       inputEncoding;
  // Introduced in DOM Level 3:
  readonly attribute DOMString       xmlEncoding;
  // Introduced in DOM Level 3:
           attribute boolean         xmlStandalone;
                                        // raises(DOMException) on setting
  // Introduced in DOM Level 3:
           attribute DOMString       xmlVersion;
                                        // raises(DOMException) on setting
  // Introduced in DOM Level 3:
           attribute boolean         strictErrorChecking;
  // Introduced in DOM Level 3:
           attribute DOMString       documentURI;
  // Introduced in DOM Level 3:
  nsIDOMNode         adoptNode(in nsIDOMNode source)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  readonly attribute nsIDOMDOMConfiguration domConfig;
  // Introduced in DOM Level 3:
  void               normalizeDocument();
  // Introduced in DOM Level 3:
  nsIDOMNode         renameNode(in nsIDOMNode node, 
                                in DOMString namespaceURI, 
                                in DOMString qualifiedName)
                                        raises(DOMException);
};

///////////////////////////////////////////////////////////////////////////////
//  nsIDOMWindow2
///////////////////////////////////////////////////////////////////////////////

interface nsIDOMEventTarget;
interface nsIDOMOfflineResourceList;
interface nsIDOMBlob;

[scriptable, uuid(efff0d88-3b94-4375-bdeb-676a847ecd7d)]
interface nsIDOMWindow2 : nsIDOMWindow
{
  /**
   * Get the window root for this window. This is useful for hooking
   * up event listeners to this window and every other window nested
   * in the window root.
   */
  [noscript] readonly attribute nsIDOMEventTarget windowRoot;

  /**
   * Get the application cache object for this window.
   */
  readonly attribute nsIDOMOfflineResourceList applicationCache;

  /**
   * Deprecated, but can't remove yet since we don't want to change interfaces.
   */
  [noscript] DOMString createBlobURL(in nsIDOMBlob blob);
  [noscript] void revokeBlobURL(in DOMString URL);
};


///////////////////////////////////////////////////////////////////////////////
//  nsITransfer
///////////////////////////////////////////////////////////////////////////////

interface nsIURI;
interface nsICancelable;
interface nsIMIMEInfo;
interface nsILocalFile;

[scriptable, uuid(3a982955-dc44-422e-8734-8462bf8d2121)]
interface nsITransfer : nsIWebProgressListener2 {

    /**
     * Initializes the transfer with certain properties.  This function must
     * be called prior to accessing any properties on this interface.
     *
     * @param aSource The source URI of the transfer. Must not be null.
     *
     * @param aTarget The target URI of the transfer. Must not be null.
     *
     * @param aDisplayName The user-readable description of the transfer.
     *                     Can be empty.
     *
     * @param aMIMEInfo The MIME info associated with the target,
     *                  including MIME type and helper app when appropriate.
     *                  This parameter is optional.
     *
     * @param startTime Time when the download started (ie, when the first
     *                  response from the server was received)
     *                  XXX presumably wbp and exthandler do this differently
     *
     * @param aTempFile The location of a temporary file; i.e. a file in which
     *                  the received data will be stored, but which is not
     *                  equal to the target file. (will be moved to the real
     *                  target by the caller, when the download is finished)
     *                  May be null.
     *
     * @param aCancelable An object that can be used to abort the download.
     *                    Must not be null.
     *                    Implementations are expected to hold a strong
     *                    reference to this object until the download is
     *                    finished, at which point they should release the
     *                    reference.
     */
    void init(in nsIURI aSource,
              in nsIURI aTarget,
              in AString aDisplayName,
              in nsIMIMEInfo aMIMEInfo,
              in PRTime startTime,
              in nsILocalFile aTempFile,
              in nsICancelable aCancelable);
};


///////////////////////////////////////////////////////////////////////////////
//  nsIMIMEInfo
///////////////////////////////////////////////////////////////////////////////


interface nsIURI;
interface nsIFile;
interface nsIUTF8StringEnumerator;
interface nsIHandlerApp;
interface nsIArray;
interface nsIMutableArray;
interface nsIInterfaceRequestor;

typedef long nsHandlerInfoAction;

/**
 * nsIHandlerInfo gives access to the information about how a given protocol
 * scheme or MIME-type is handled.
 */
[scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)] 
interface nsIHandlerInfo : nsISupports {
    /**
     * The type of this handler info.  For MIME handlers, this is the MIME type.
     * For protocol handlers, it's the scheme.
     * 
     * @return String representing the type.
     */
    readonly attribute ACString type;

    /**
     * A human readable description of the handler type
     */
    attribute AString description;

    /**
     * The application the user has said they want associated with this content
     * type. This is not always guaranteed to be set!!
     */
    attribute nsIHandlerApp preferredApplicationHandler;

    /**
     * Applications that can handle this content type.
     *
     * The list will include the preferred handler, if any.  Elements of this
     * array are nsIHandlerApp objects, and this attribute will always reference
     * an array, whether or not there are any possible handlers.  If there are
     * no possible handlers, the array will contain no elements, so just check
     * its length (nsIArray::length) to see if there are any possible handlers.
     */
    readonly attribute nsIMutableArray possibleApplicationHandlers;

    /**
     * Indicates whether a default application handler exists,
     * i.e. whether launchWithFile with action = useSystemDefault is possible
     * and defaultDescription will contain usable information.
     */
    readonly attribute boolean hasDefaultHandler;

    /**
     * A pretty name description of the associated default application. Only
     * usable if hasDefaultHandler is true.
     */
    readonly attribute AString defaultDescription;

    /**
     * Launches the application with the specified URI, in a way that
     * depends on the value of preferredAction. preferredAction must be
     * useHelperApp or useSystemDefault.
     *  
     * @note Only the URI scheme is used to determine how to launch.  This is
     * essentially a pass-by-value operation.  This means that in the case of
     * a file: URI, the handler that is registered for file: will be launched
     * and our code will not make any decision based on the content-type or
     * extension, though the invoked file: handler is free to do so. 
     *
     * @param aURI
     *        The URI to launch this application with
     *
     * @param aWindowContext 
     *        The window to parent the dialog against, and, if a web handler
     *        is chosen, it is loaded in this window as well.  See 
     *        nsIHandlerApp.launchWithURI for more details.
     *
     * @throw NS_ERROR_INVALID_ARG if preferredAction is not valid for this
     * call. Other exceptions may be thrown.
     */
    void launchWithURI(in nsIURI aURI, 
                       [optional] in nsIInterfaceRequestor aWindowContext);

    /**
     * preferredAction is how the user specified they would like to handle
     * this content type: save to disk, use specified helper app, use OS
     * default handler or handle using navigator; possible value constants
     * listed below
     */
    attribute nsHandlerInfoAction preferredAction;

    const long saveToDisk = 0;
    /**
     * Used to indicate that we know nothing about what to do with this.  You
     * could consider this to be not initialized.
     */
    const long alwaysAsk = 1;
    const long useHelperApp = 2;
    const long handleInternally = 3;
    const long useSystemDefault = 4;

    /**
     * alwaysAskBeforeHandling: if true, we should always give the user a
     * dialog asking how to dispose of this content.
     */
    attribute boolean alwaysAskBeforeHandling;
};

/**
 * nsIMIMEInfo extends nsIHandlerInfo with a bunch of information specific to
 * MIME content-types. There is a one-to-many relationship between MIME types
 * and file extensions. This means that a MIMEInfo object may have multiple
 * file extensions associated with it.  However, the reverse is not true.
 *
 * MIMEInfo objects are generally retrieved from the MIME Service
 * @see nsIMIMEService
 */
[scriptable, uuid(1c21acef-c7a1-40c6-9d40-a20480ee53a1)]
interface nsIMIMEInfo : nsIHandlerInfo {
    /**
     * Gives you an array of file types associated with this type.
     *
     * @return Number of elements in the array.
     * @return Array of extensions.
     */
    nsIUTF8StringEnumerator getFileExtensions();

    /**
     * Set File Extensions. Input is a comma delimited list of extensions.
     */
    void setFileExtensions(in AUTF8String aExtensions);
 
    /**
     * Returns whether or not the given extension is
     * associated with this MIME info.
     *
     * @return TRUE if the association exists. 
     */
    boolean extensionExists(in AUTF8String aExtension);

    /**
     * Append a given extension to the set of extensions
     */
    void appendExtension(in AUTF8String aExtension);

    /**
     * Returns the first extension association in
     * the internal set of extensions.
     *
     * @return The first extension.
     */
    attribute AUTF8String primaryExtension;
    
    /**
     * The MIME type of this MIMEInfo.
     * 
     * @return String representing the MIME type.
     * 
     * @deprecated  use nsIHandlerInfo::type instead.
     */
    readonly attribute ACString MIMEType;

    /**
     * Returns whether or not these two nsIMIMEInfos are logically
     * equivalent.
     *
     * @returns PR_TRUE if the two are considered equal
     */
    boolean equals(in nsIMIMEInfo aMIMEInfo);

    /** 
     * Returns a list of nsILocalHandlerApp objects containing
     * handlers associated with this mimeinfo. Implemented per 
     * platform using information in this object to generate the
     * best list. Typically used for an "open with" style user 
     * option.
     * 
     * @return nsIArray of nsILocalHandlerApp
     */
    readonly attribute nsIArray possibleLocalHandlers;

    /**
     * Launches the application with the specified file, in a way that
     * depends on the value of preferredAction. preferredAction must be
     * useHelperApp or useSystemDefault.
     *
     * @param aFile The file to launch this application with.
     *
     * @throw NS_ERROR_INVALID_ARG if action is not valid for this function.
     * Other exceptions may be thrown.
     */
    void launchWithFile(in nsIFile aFile);
};

///////////////////////////////////////////////////////////////////////////////
//  nsIDOMHTMLInputElement
///////////////////////////////////////////////////////////////////////////////


interface nsIControllers;
interface nsIDOMFileList;
interface nsIDOMValidityState;

 /**
  * The nsIDOMHTMLInputElement interface is the interface to a [X]HTML
  * input element.
  *
  * This interface is trying to follow the DOM Level 2 HTML specification:
  * http://www.w3.org/TR/DOM-Level-2-HTML/
  *
  * with changes from the work-in-progress WHATWG HTML specification:
  * http://www.whatwg.org/specs/web-apps/current-work/
  */

[scriptable, uuid(0805059d-f18f-4095-ae6b-0bf6df80b7b8)]
interface nsIDOMHTMLInputElement : nsIDOMHTMLElement
{
           attribute DOMString             accept;
           attribute DOMString             alt;

           attribute DOMString             autocomplete;
           attribute boolean               autofocus;
           attribute boolean               defaultChecked;
           attribute boolean               checked;
           attribute boolean               disabled;
  readonly attribute nsIDOMHTMLFormElement form;
           attribute DOMString             formAction;
           attribute DOMString             formEnctype;
           attribute DOMString             formMethod;
           attribute boolean               formNoValidate;
           attribute DOMString             formTarget;

  readonly attribute nsIDOMFileList        files;

           attribute boolean               indeterminate;

  readonly attribute nsIDOMHTMLElement     list;
           attribute long                  maxLength;

           attribute boolean               multiple;
           attribute DOMString             name;

           attribute DOMString             pattern;
           attribute DOMString             placeholder;
           attribute boolean               readOnly;
           attribute boolean               required;

           attribute DOMString             accessKey;
           attribute DOMString             align;

           attribute unsigned long         size;
           attribute DOMString             src;

           attribute DOMString             type;
           attribute DOMString             defaultValue;
           attribute DOMString             value;

  // The following lines are parte of the constraint validation API, see:
  // http://www.whatwg.org/specs/web-apps/current-work/#the-constraint-validation-api
  readonly attribute boolean             willValidate;
  readonly attribute nsIDOMValidityState validity;
  readonly attribute DOMString           validationMessage;
  boolean checkValidity();
  void setCustomValidity(in DOMString error);

  void select();
           attribute long                  selectionStart;
           attribute long                  selectionEnd;
  void setSelectionRange(in long selectionStart, in long selectionEnd);
          

           attribute long                  tabIndex;
           attribute DOMString             useMap;
  readonly attribute nsIControllers        controllers;	
	readonly attribute long                  textLength;

  void mozGetFileNameArray([optional] out unsigned long aLength,
                           [array,size_is(aLength), retval] out wstring aFileNames);
  void mozSetFileNameArray([array,size_is(aLength)] in wstring aFileNames,
                           in unsigned long aLength);

    /**
   * This non-standard method prevents to check types manually to know if the
   * element is a text field.
   */
  boolean mozIsTextField(in boolean aExcludePassword);

  void blur();
  void focus();
  void click();
};



///////////////////////////////////////////////////////////////////////////////
//  nsIDOMHTMLButtonElement
///////////////////////////////////////////////////////////////////////////////

interface nsIDOMValidityState;

[scriptable, uuid(bcae78a1-9f9b-46bf-abb5-a3fe410d97ae)]
interface nsIDOMHTMLButtonElement : nsIDOMHTMLElement
{
           attribute boolean               autofocus;
           attribute boolean               disabled;
  readonly attribute nsIDOMHTMLFormElement form;
           attribute DOMString             formAction;
           attribute DOMString             formEnctype;
           attribute DOMString             formMethod;
           attribute boolean               formNoValidate;
           attribute DOMString             formTarget;

           attribute DOMString             name;
           attribute DOMString             type;
           attribute DOMString             value;

           
           attribute DOMString             accessKey;
           attribute long                  tabIndex;
  void                      blur();
  void                      focus();
  void                      click();

  // The following lines are parte of the constraint validation API, see:
  // http://www.whatwg.org/specs/web-apps/current-work/#the-constraint-validation-api
  readonly attribute boolean             willValidate;
  readonly attribute nsIDOMValidityState validity;
  readonly attribute DOMString           validationMessage;
  boolean checkValidity();
  void setCustomValidity(in DOMString error);
};

interface nsIDOMHTMLFormElement;

///////////////////////////////////////////////////////////////////////////////
//  nsIDOMHTMLAnchorElement
///////////////////////////////////////////////////////////////////////////////



[scriptable, uuid(4e237175-3628-4dc8-892f-5270edc3c71a)]
interface nsIDOMHTMLAnchorElement : nsIDOMHTMLElement
{
           attribute DOMString        href;
           attribute DOMString        target;

           attribute DOMString        ping;

           attribute DOMString        rel;
           attribute DOMString        hreflang;
           attribute DOMString        type;

  /**
   * An alias for the textContent attribute.
   */
  [Null(Stringify)]
           attribute DOMString        text;

  // URL decomposition IDL attributes
           attribute DOMString        protocol;
           attribute DOMString        host;
           attribute DOMString        hostname;
           attribute DOMString        port;
           attribute DOMString        pathname;
           attribute DOMString        search;
           attribute DOMString        hash;


           attribute DOMString        accessKey;
           attribute DOMString        charset;
           attribute DOMString        coords;
           attribute DOMString        name;
           attribute DOMString        rev;
           attribute DOMString        shape;
           attribute long             tabIndex;

  DOMString                 toString();
  void                      blur();
  void                      focus();
};


///////////////////////////////////////////////////////////////////////////////
//  nsIDOMHTMLSelectElement
///////////////////////////////////////////////////////////////////////////////

interface nsIDOMValidityState;
interface nsIDOMHTMLOptionsCollection;

[scriptable, uuid(e3c6d960-972c-4a5e-a8f4-6ca65d578abf)]
interface nsIDOMHTMLSelectElement : nsIDOMHTMLElement
{
           attribute boolean                     autofocus;
           attribute boolean                     disabled;
  readonly attribute nsIDOMHTMLFormElement       form;
           attribute boolean                     multiple;
           attribute DOMString                   name;
           attribute long                        size;

  readonly attribute DOMString                   type;

  readonly attribute nsIDOMHTMLOptionsCollection options;
           attribute unsigned long               length;
  nsIDOMNode                item(in unsigned long index);
  nsIDOMNode                namedItem(in DOMString name);
  void                      add(in nsIDOMHTMLElement element, 
                                in nsIDOMHTMLElement before)
                                                     raises(DOMException);   
  void                      remove(in long index);

           attribute long                  selectedIndex;
           attribute DOMString             value;

           attribute long                  tabIndex;
  void                      blur();
  void                      focus();

  // The following lines are parte of the constraint validation API, see:
  // http://www.whatwg.org/specs/web-apps/current-work/#the-constraint-validation-api
  readonly attribute boolean             willValidate;
  readonly attribute nsIDOMValidityState validity;
  readonly attribute DOMString           validationMessage;
  boolean checkValidity();
  void setCustomValidity(in DOMString error);
};

///////////////////////////////////////////////////////////////////////////////
//  nsIDOMHTMLOptionElement
///////////////////////////////////////////////////////////////////////////////

[scriptable, uuid(611d00f5-1eb8-4571-b995-2a2019d2d11c)]
interface nsIDOMHTMLOptionElement : nsIDOMHTMLElement
{
           attribute boolean               disabled;
  readonly attribute nsIDOMHTMLFormElement form;
           attribute DOMString             label;
           attribute boolean               defaultSelected;
           attribute boolean               selected;
           attribute DOMString             value;

           attribute DOMString             text;
  readonly attribute long                  index;
};



///////////////////////////////////////////////////////////////////////////////
//  nsIPrincipal
///////////////////////////////////////////////////////////////////////////////

[uuid(0575ea96-4561-4dc6-a818-3c4c97c2430d)]
interface nsIPrincipal : nsISupports //nsISerializable
{
    // TODO: fill out (if necessary)
    void placeholder();
};



///////////////////////////////////////////////////////////////////////////////
//  nsIScriptSecurityManager
///////////////////////////////////////////////////////////////////////////////

interface nsIURI;
interface nsIChannel;
native jsid(jsid);

[scriptable, uuid(50eda256-4dd2-4c7c-baed-96983910af9f)]
interface nsIScriptSecurityManager : nsIXPCSecurityManager
{
    ///////////////// Security Checks //////////////////
    /**
     * Checks whether the running script is allowed to access aProperty.
     */
    [noscript] void checkPropertyAccess(in JSContextPtr aJSContext,
                                        in JSObjectPtr aJSObject,
                                        in string aClassName,
                                        in jsid aProperty,
                                        in PRUint32 aAction);

    /**
     * Check that the script currently running in context "cx" can load "uri".
     *
     * Will return error code NS_ERROR_DOM_BAD_URI if the load request 
     * should be denied.
     *
     * @param cx the JSContext of the script causing the load
     * @param uri the URI that is being loaded
     */
    [noscript] void checkLoadURIFromScript(in JSContextPtr cx, in nsIURI uri);

    /**
     * Default CheckLoadURI permissions
     */
    // Default permissions
    const unsigned long STANDARD = 0;

    // Indicate that the load is a load of a new document that is not
    // user-triggered.  Here "user-triggered" could be broadly interpreted --
    // for example, scripted sets of window.location.href might be treated as
    // "user-triggered" in some circumstances.  A typical example of a load
    // that is not user-triggered is a <meta> refresh load.  If this flag is
    // set, the load will be denied if the originating principal's URI has the
    // nsIProtocolHandler::URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT flag set.
    const unsigned long LOAD_IS_AUTOMATIC_DOCUMENT_REPLACEMENT = 1 << 0;

    // Allow the loading of chrome URLs by non-chrome URLs.  Use with great
    // care!  This will actually allow the loading of any URI which has the
    // nsIProtocolHandler::URI_IS_UI_RESOURCE protocol handler flag set.  Ths
    // probably means at least chrome: and resource:.
    const unsigned long ALLOW_CHROME = 1 << 1;

    // Don't allow URLs which would inherit the caller's principal (such as
    // javascript: or data:) to load.  See
    // nsIProtocolHandler::URI_INHERITS_SECURITY_CONTEXT.
    const unsigned long DISALLOW_INHERIT_PRINCIPAL = 1 << 2;

    // Alias for DISALLOW_INHERIT_PRINCIPAL for backwards compat with
    // JS-implemented extensions.
    const unsigned long DISALLOW_SCRIPT_OR_DATA = DISALLOW_INHERIT_PRINCIPAL;

    // Don't allow javascript: URLs to load
    //   WARNING: Support for this value was added in Mozilla 1.7.8 and
    //   Firefox 1.0.4.  Use in prior versions WILL BE IGNORED.
    // When using this, make sure that you actually want DISALLOW_SCRIPT, not
    // DISALLOW_INHERIT_PRINCIPAL
    const unsigned long DISALLOW_SCRIPT = 1 << 3;

    /**
     * Check that content with principal aPrincipal can load "uri".
     *
     * Will return error code NS_ERROR_DOM_BAD_URI if the load request 
     * should be denied.
     *
     * @param aPrincipal the principal identifying the actor causing the load
     * @param uri the URI that is being loaded
     * @param flags the permission set, see above
     */
    void checkLoadURIWithPrincipal(in nsIPrincipal aPrincipal,
                                   in nsIURI uri, 
                                   in unsigned long flags);

    /**
     * Check that content from "from" can load "uri".
     *
     * Will return error code NS_ERROR_DOM_BAD_URI if the load request 
     * should be denied.
     *
     * @param from the URI causing the load
     * @param uri the URI that is being loaded
     * @param flags the permission set, see above
     *
     * @deprecated Use checkLoadURIWithPrincipal instead of this function.
     */
    void checkLoadURI(in nsIURI from, in nsIURI uri, 
                      in unsigned long flags);

    /**
     * Similar to checkLoadURIWithPrincipal but there are two differences:
     *
     * 1) The URI is a string, not a URI object.
     * 2) This function assumes that the URI may still be subject to fixup (and
     * hence will check whether fixed-up versions of the URI are allowed to
     * load as well); if any of the versions of this URI is not allowed, this
     * function will return error code NS_ERROR_DOM_BAD_URI.
     */
    void checkLoadURIStrWithPrincipal(in nsIPrincipal aPrincipal,
                                      in AUTF8String uri, 
                                      in unsigned long flags);     
    
    /**
     * Same as CheckLoadURI but takes string arguments for ease of use
     * by scripts
     *
     * @deprecated Use checkLoadURIStrWithPrincipal instead of this function.
     */
    void checkLoadURIStr(in AUTF8String from, in AUTF8String uri, 
                         in unsigned long flags);

    /**
     * Check that the function 'funObj' is allowed to run on 'targetObj'
     *
     * Will return error code NS_ERROR_DOM_SECURITY_ERR if the function
     * should not run
     *
     * @param cx The current active JavaScript context.
     * @param funObj The function trying to run..
     * @param targetObj The object the function will run on.
     */
    [noscript] void checkFunctionAccess(in JSContextPtr cx, in voidPtr funObj,
                                        in voidPtr targetObj);

    /**
     * Return true if content from the given principal is allowed to
     * execute scripts.
     */
    [noscript] boolean canExecuteScripts(in JSContextPtr cx,
                                         in nsIPrincipal principal);

    ///////////////// Principals /////////////////////// 
    /**
     * Return the principal of the innermost frame of the currently 
     * executing script. Will return null if there is no script 
     * currently executing.
     */
    [noscript] nsIPrincipal getSubjectPrincipal();

    /**
     * Return the all-powerful system principal.
     */
    nsIPrincipal getSystemPrincipal();

    /**
     * Return a principal with the specified certificate fingerprint, subject
     * name (the full name or concatenated set of names of the entity
     * represented by the certificate), pretty name, certificate, and
     * codebase URI.  The certificate fingerprint and subject name MUST be
     * nonempty; otherwise an error will be thrown.  Similarly, aCert must
     * not be null.
     */
    [noscript] nsIPrincipal
         getCertificatePrincipal(in AUTF8String aCertFingerprint,
                                 in AUTF8String aSubjectName,
                                 in AUTF8String aPrettyName,
                                 in nsISupports aCert,
                                 in nsIURI aURI);

    /**
     * Return a principal that has the same origin as aURI.
     */
    nsIPrincipal getCodebasePrincipal(in nsIURI aURI);

    ///////////////// Capabilities API /////////////////////
    /**
     * Request that 'capability' can be enabled by scripts or applets
     * running with 'principal'. Will prompt user if
     * necessary. Returns nsIPrincipal::ENABLE_GRANTED or
     * nsIPrincipal::ENABLE_DENIED based on user's choice.
     */
    [noscript] short requestCapability(in nsIPrincipal principal,
                                       in string capability);
    
    /**
     * Return true if the currently executing script has 'capability' enabled.
     */
    boolean isCapabilityEnabled(in string capability);
    
    /**
     * Enable 'capability' in the innermost frame of the currently executing
     * script.
     */
    void enableCapability(in string capability);

    /**
     * Remove 'capability' from the innermost frame of the currently
     * executing script. Any setting of 'capability' from enclosing
     * frames thus comes into effect.
     */
    void revertCapability(in string capability);

    /**
     * Disable 'capability' in the innermost frame of the currently executing
     * script.
     */
    void disableCapability(in string capability);

    //////////////// Master Certificate Functions ////////////////////
    /**
     * Allow 'certificateID' to enable 'capability.' Can only be performed
     * by code signed by the system certificate.
     */
    // XXXbz Capabilities can't have non-ascii chars?
    // XXXbz ideally we'd pass a subjectName here too, and the nsISupports
    // cert we're enabling for...
    void setCanEnableCapability(in AUTF8String certificateFingerprint,
                                in string capability, 
                                in short canEnable);

    ///////////////////////
    /**
     * Return the principal of the specified object in the specified context.
     */
    [noscript] nsIPrincipal getObjectPrincipal(in JSContextPtr cx,
                                               in JSObjectPtr obj);

    /**
     * Returns true if the principal of the currently running script is the
     * system principal, false otherwise.
     */
    [noscript] boolean subjectPrincipalIsSystem();

    /**
     * Returns OK if aJSContext and target have the same "origin"
     * (scheme, host, and port).
     */
    [noscript] void checkSameOrigin(in JSContextPtr aJSContext,
                                    in nsIURI aTargetURI);

    /**
     * Returns OK if aSourceURI and target have the same "origin"
     * (scheme, host, and port).
     * ReportError flag suppresses error reports for functions that
     * don't need reporting.
     */
    void checkSameOriginURI(in nsIURI aSourceURI,
                            in nsIURI aTargetURI,
                            in boolean reportError);

    /**
     * Returns the principal of the global object of the given context, or null
     * if no global or no principal.
     */
    [noscript] nsIPrincipal getPrincipalFromContext(in JSContextPtr cx);

    /**
     * Get the principal for the given channel.  This will typically be the
     * channel owner if there is one, and the codebase principal for the
     * channel's URI otherwise.  aChannel must not be null.
     */
    nsIPrincipal getChannelPrincipal(in nsIChannel aChannel);

    /**
     * Check whether a given principal is a system principal.  This allows us
     * to avoid handing back the system principal to script while allowing
     * script to check whether a given principal is system.
     */
    boolean isSystemPrincipal(in nsIPrincipal aPrincipal);

    /**
     * Same as getSubjectPrincipal(), only faster. cx must *never* be
     * passed null, and it must be the context on the top of the
     * context stack. Does *not* reference count the returned
     * principal.
     */
    [noscript,notxpcom] nsIPrincipal getCxSubjectPrincipal(in JSContextPtr cx);
    [noscript,notxpcom] nsIPrincipal getCxSubjectPrincipalAndFrame(in JSContextPtr cx,
                                                                   out JSStackFramePtr fp);

    /**
     * If no scripted code is running "above" (or called from) fp, then
     * instead of looking at cx->globalObject, we will return |principal|.
     * This function only affects |cx|. If someone pushes another context onto
     * the context stack, then it supersedes this call.
     * NOTE: If |fp| is non-null popContextPrincipal must be called before fp
     * has finished executing.
     *
     * @param cx The context to clamp.
     * @param fp The frame pointer to clamp at. May be 'null'.
     * @param principal The principal to clamp to.
     */
    [noscript] void pushContextPrincipal(in JSContextPtr cx,
                                         in JSStackFramePtr fp,
                                         in nsIPrincipal principal);

    /**
     * Removes a clamp set by pushContextPrincipal from cx. This must be
     * called in a stack-like fashion (e.g., given two contexts |a| and |b|,
     * it is not legal to do: push(a) push(b) pop(a)).
     */
    [noscript] void popContextPrincipal(in JSContextPtr cx);
};

///////////////////////////////////////////////////////////////////////////////
//  nsICacheService
///////////////////////////////////////////////////////////////////////////////


interface nsISimpleEnumerator;
interface nsICacheListener;
interface nsICacheSession;
interface nsICacheVisitor;
interface nsIEventTarget;
typedef long nsCacheStoragePolicy;

[scriptable, uuid(14dbe1e9-f3bc-45af-92f4-2c574fcd4e39)]
interface nsICacheService : nsISupports
{
    /**
     * Create a cache session
     *
     * A cache session represents a client's access into the cache.  The cache
     * session is not "owned" by the cache service.  Hence, it is possible to
     * create duplicate cache sessions.  Entries created by a cache session
     * are invisible to other cache sessions, unless the cache sessions are
     * equivalent.
     *
     * @param clientID - Specifies the name of the client using the cache.
     * @param storagePolicy - Limits the storage policy for all entries
     *   accessed via the returned session.  As a result, devices excluded
     *   by the storage policy will not be searched when opening entries
     *   from the returned session.
     * @param streamBased - Indicates whether or not the data being cached
     *   can be represented as a stream.  The storagePolicy must be 
     *   consistent with the value of this field.  For example, a non-stream-
     *   based cache entry can only have a storage policy of STORE_IN_MEMORY.
     * @return new cache session.
     */
    nsICacheSession createSession(in string                 clientID,
                                  in nsCacheStoragePolicy   storagePolicy,
                                  in boolean                streamBased);

    /**
     * Visit entries stored in the cache.  Used to implement about:cache.
     */
    void visitEntries(in nsICacheVisitor visitor);

    /**
     * Evicts all entries in all devices implied by the storage policy.
     *
     * @note This function may evict some items but will throw if it fails to evict
     *       everything.
     */
    void evictEntries(in nsCacheStoragePolicy  storagePolicy);

    /**
     * Event target which is used for I/O operations
     */
    readonly attribute nsIEventTarget cacheIOTarget;
};

///////////////////////////////////////////////////////////////////////////////
//  nsIScriptableUnicodeConverter
///////////////////////////////////////////////////////////////////////////////

interface nsIInputStream;

%{C++
// {0A698C44-3BFF-11d4-9649-00C0CA135B4E}
#define NS_ISCRIPTABLEUNICODECONVERTER_CID { 0x0A698C44, 0x3BFF, 0x11d4, { 0x96, 0x49, 0x00, 0xC0, 0xCA, 0x13, 0x5B, 0x4E } }
#define NS_ISCRIPTABLEUNICODECONVERTER_CONTRACTID "@mozilla.org/intl/scriptableunicodeconverter"
%}

/**
 * This interface is a unicode encoder for use by scripts
 *
 * @created         8/Jun/2000
 * @author          Makoto Kato [m_kato@ga2.so-net.ne.jp]
 */
[scriptable, uuid(f36ee324-5c1c-437f-ba10-2b4db7a18031)]
interface nsIScriptableUnicodeConverter : nsISupports
{
  /**
   * Converts the data from Unicode to one Charset.
   * Returns the converted string. After converting, Finish should be called
   * and its return value appended to this return value.
   */
  ACString ConvertFromUnicode(in AString aSrc);

  /**
   * Returns the terminator string.
   * Should be called after ConvertFromUnicode() and appended to that
   * function's return value.
   */
  ACString Finish();

  /**
   * Converts the data from one Charset to Unicode.
   */
  AString ConvertToUnicode(in ACString aSrc);

  /**
   * Converts an array of bytes to a unicode string.
   */
  AString convertFromByteArray([const,array,size_is(aCount)] in octet aData,
                               in unsigned long aCount);

  /**
   * Convert a unicode string to an array of bytes. Finish does not need to be
   * called.
   */
  void convertToByteArray(in AString aString,
                          [optional] out unsigned long aLen,
                          [array, size_is(aLen),retval] out octet aData);

  /**
   * Converts a unicode string to an input stream. The bytes in the stream are
   * encoded according to the charset attribute.
   * The returned stream will be nonblocking.
   */
  nsIInputStream convertToInputStream(in AString aString);

  /**
   * Current character set.
   *
   * @throw NS_ERROR_UCONV_NOCONV
   *        The requested charset is not supported.
   */
  attribute string charset;

  /**
   * Internal use
   *
   * When this attribute is set, all charsets may be accessed.
   * When it is not set (the default), charsets with the isXSSVulnerable flag
   *  may not be accessed
   */
  attribute boolean isInternal;
};



///////////////////////////////////////////////////////////////////////////////
//  nsIWebBrowser
///////////////////////////////////////////////////////////////////////////////


interface nsIInterfaceRequestor;
interface nsIWebBrowserChrome;
interface nsIURIContentListener;
interface nsIDOMWindow;
interface nsIWeakReference;

/**
 * The nsIWebBrowser interface is implemented by web browser objects.
 * Embedders use this interface during initialisation to associate
 * the new web browser instance with the embedders chrome and
 * to register any listeners. The interface may also be used at runtime
 * to obtain the content DOM window and from that the rest of the DOM.
 */
[scriptable, uuid(33e9d001-caab-4ba9-8961-54902f197202)]
interface nsIWebBrowser : nsISupports
{
    /**
     * Registers a listener of the type specified by the iid to receive
     * callbacks. The browser stores a weak reference to the listener
     * to avoid any circular dependencies.
     * Typically this method will be called to register an object
     * to receive <CODE>nsIWebProgressListener</CODE> or 
     * <CODE>nsISHistoryListener</CODE> notifications in which case the
     * the IID is that of the interface.
     *
     * @param aListener The listener to be added.
     * @param aIID      The IID of the interface that will be called
     *                  on the listener as appropriate.
     * @return          <CODE>NS_OK</CODE> for successful registration;
     *                  <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
     *                  supposed to be registered using this method;
     *                  <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
     *                  expose the interface specified by the IID, or some
     *                  other internal error occurred.
     *
     * @see removeWebBrowserListener
     * @see nsIWeakReference
     * @see nsIWebProgressListener
     * @see nsISHistoryListener
     *
     * @return <CODE>NS_OK</CODE>, listener was successfully added;
     *         <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
     *         invalid or the object did not implement the interface
     *         specified by the IID.
     */
    void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);

    /**
     * Removes a previously registered listener.
     *
     * @param aListener The listener to be removed.
     * @param aIID      The IID of the interface on the listener that will
     *                  no longer be called.
     *
     * @return <CODE>NS_OK</CODE>, listener was successfully removed;
     *         <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
     *         the object did not implement the interface specified by the IID.
     *
     * @see addWebBrowserListener
     * @see nsIWeakReference
     */
    void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);

    /**
     * The chrome object associated with the browser instance. The embedder
     * must create one chrome object for <I>each</I> browser object
     * that is instantiated. The embedder must associate the two by setting
     * this property to point to the chrome object before creating the browser
     * window via the browser's <CODE>nsIBaseWindow</CODE> interface. 
     *
     * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
     *
     * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
     * <CODE>nsIWebBrowserChromeFocus</CODE>,
     * <CODE>nsIContextMenuListener</CODE> and
     * <CODE>nsITooltipListener</CODE> to receive additional notifications
     * from the browser object.
     *
     * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE> 
     * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
     * <CODE>removeWebBrowserListener</CODE> to register a progress listener
     * object. If the implementation does this, it must also implement
     * <CODE>nsIWeakReference</CODE>.
     * 
     * @note The implementation should not refcount the supplied chrome
     *       object; it should assume that a non <CODE>nsnull</CODE> value is
     *       always valid. The embedder must explicitly set this value back
     *       to nsnull if the chrome object is destroyed before the browser
     *       object.
     *
     * @see nsIBaseWindow
     * @see nsIWebBrowserChrome
     * @see nsIEmbeddingSiteWindow
     * @see nsIInterfaceRequestor
     * @see nsIWebBrowserChromeFocus
     * @see nsIContextMenuListener
     * @see nsITooltipListener
     * @see nsIWeakReference
     * @see nsIWebProgressListener
     */
    attribute nsIWebBrowserChrome containerWindow;

    /**
     * URI content listener parent. The embedder may set this property to
     * their own implementation if they intend to override or prevent
     * how certain kinds of content are loaded.
     *
     * @note If this attribute is set to an object that implements
     *       nsISupportsWeakReference, the implementation should get the
     *       nsIWeakReference and hold that.  Otherwise, the implementation
     *       should not refcount this interface; it should assume that a non
     *       null value is always valid.  In that case, the embedder should
     *       explicitly set this value back to null if the parent content
     *       listener is destroyed before the browser object.
     *
     * @see nsIURIContentListener
     */
    attribute nsIURIContentListener parentURIContentListener;

    /**
     * The top-level DOM window. The embedder may walk the entire
     * DOM starting from this value.
     *
     * @see nsIDOMWindow
     */
    readonly attribute nsIDOMWindow contentDOMWindow;

    /**
     * Whether this web browser is active. Active means that it's visible
     * enough that we want to avoid certain optimizations like discarding
     * decoded image data and throttling the refresh driver. In Firefox,
     * this corresponds to the visible tab.
     *
     * Defaults to true. For optimal performance, set it to false when
     * appropriate.
     */
    attribute boolean isActive;
};


///////////////////////////////////////////////////////////////////////////////
//  nsIDocShell
///////////////////////////////////////////////////////////////////////////////


%{ C++
class nsPresContext;
class nsIPresShell;
%}

/**
 * The nsIDocShell interface.
 */

[ptr] native nsPresContext(nsPresContext);
[ptr] native nsIPresShell(nsIPresShell);

interface nsIURI;
interface nsIChannel;
interface nsIContentViewer;
interface nsIURIContentListener;
interface nsIDOMEventTarget;
interface nsIDocShellLoadInfo;
interface nsIDocumentCharsetInfo;
interface nsIWebNavigation;
interface nsISimpleEnumerator;
interface nsIInputStream;
interface nsIRequest;
interface nsISHEntry;
interface nsILayoutHistoryState;
interface nsISecureBrowserUI;
interface nsIDOMStorage;
interface nsIPrincipal;
interface nsIWebBrowserPrint;
interface nsIVariant;

[scriptable, uuid(98cdbcc4-2d81-4191-a63f-b6c52085edbc)]
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 PRUint32 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.
   */
  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;

  /**
   * The document charset info.  This is used by a load to determine priorities
   * for charset detection etc.
   */
  attribute nsIDocumentCharsetInfo documentCharsetInfo;

  /**
   * 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;

  /**
   * 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 domain.
   * If it doesn't already exist, a new one will be created.
   *
   * @param uri the uri of the storage object to retrieve
   * @param documentURI new storage will be created with reference to this
   *                    document.documentURI that will appear in storage event
   */
  nsIDOMStorage getSessionStorageForURI(in nsIURI uri,
                                        in DOMString documentURI);

  /*
   * 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);

  /**
   * 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;
};