ns_xulrunner_192.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(2e0e9ea1-72ab-4d9e-bdeb-ca64e1abeba4)]
interface nsIDOM3Document : nsIDOM3Node
{
  // 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;


[scriptable, uuid(73c5fa35-3add-4c87-a303-a850ccf4d65a)]
interface nsIDOMWindow2 : nsIDOMWindow
{
    [noscript] readonly attribute nsIDOMEventTarget windowRoot;
    readonly attribute nsIDOMOfflineResourceList applicationCache;
};


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


interface nsIMIMEInfo;
interface nsILocalFile;
interface nsICancelable;

[scriptable, uuid(23c51569-e9a1-4a92-adeb-3723db82ef7c)]
interface nsITransfer : nsIWebProgressListener2
{
    void init(in nsIURI source,
              in nsIURI target,
              in AString display_name,
              in nsIMIMEInfo mime_info,
              in PRTime start_time,
              in nsILocalFile temp_file,
              in nsICancelable cancelable);
};


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


interface nsIUTF8StringEnumerator;
interface nsMIMEInfoHandleAction;
interface nsIHandlerApp;
interface nsIMutableArray;
interface nsIArray;
typedef long nsHandlerInfoAction;




[scriptable, uuid(325e56a7-3762-4312-aec7-f1fcf84b4145)] 
interface nsIHandlerInfo : nsISupports
{
    const long saveToDisk = 0;
    const long alwaysAsk = 1;
    const long useHelperApp = 2;
    const long handleInternally = 3;
    const long useSystemDefault = 4;
    
    readonly attribute ACString type;
    attribute AString description;
    attribute nsIHandlerApp preferredApplicationHandler;
    readonly attribute nsIMutableArray possibleApplicationHandlers;
    readonly attribute boolean hasDefaultHandler;
    readonly attribute AString defaultDescription;

    void launchWithURI(in nsIURI uri,
                       [optional] in nsIInterfaceRequestor window_context);

    attribute nsHandlerInfoAction preferredAction;

    attribute boolean alwaysAskBeforeHandling;
};


[scriptable, uuid(cd7083f8-5fe9-4248-bb09-0b0e2982fde8)]
interface nsIMIMEInfo : nsIHandlerInfo
{
    nsIUTF8StringEnumerator getFileExtensions();
    
    void setFileExtensions(in AUTF8String extensions);
    boolean extensionExists(in AUTF8String extension);
    void appendExtension(in AUTF8String extension);
    
    attribute AUTF8String primaryExtension;
    readonly attribute ACString MIMEType;
    attribute PRUint32 macType;
    attribute PRUint32 macCreator;
    
    boolean equals(in nsIMIMEInfo mime_info);
    
    readonly attribute nsIArray possibleLocalHandlers;
    
    void launchWithFile(in nsIFile file);
};

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


interface nsIDOMHTMLFormElement;

[scriptable, uuid(a6cf9093-15b3-11d2-932e-00805f8add32)]
interface nsIDOMHTMLInputElement : nsIDOMHTMLElement
{
    attribute DOMString defaultValue;
    attribute boolean defaultChecked;
    readonly attribute nsIDOMHTMLFormElement form;
    attribute DOMString accept;
    attribute DOMString accessKey;
    attribute DOMString align;
    attribute DOMString alt;
    attribute boolean checked;
    attribute boolean disabled;
    attribute long maxLength;
    attribute DOMString name;
    attribute boolean readOnly;
    attribute unsigned long size;
    attribute DOMString src;
    attribute long tabIndex;
    attribute DOMString type;
    attribute DOMString useMap;
    attribute DOMString value;
    
    void blur();
    void focus();
    void select();
    void click();
};



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


interface nsIDOMHTMLFormElement;


[scriptable, uuid(a6cf9095-15b3-11d2-932e-00805f8add32)]
interface nsIDOMHTMLButtonElement : nsIDOMHTMLElement
{
    readonly attribute nsIDOMHTMLFormElement form;
    attribute DOMString accessKey;
    attribute boolean disabled;
    attribute DOMString name;
    attribute long tabIndex;
    [noscript] readonly attribute DOMString type;
    attribute DOMString value;
};

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


[scriptable, uuid(a6cf90aa-15b3-11d2-932e-00805f8add32)]
interface nsIDOMHTMLAnchorElement : nsIDOMHTMLElement
{
    attribute DOMString accessKey;
    attribute DOMString charset;
    attribute DOMString coords;
    attribute DOMString href;
    attribute DOMString hreflang;
    attribute DOMString name;
    attribute DOMString rel;
    attribute DOMString rev;
    attribute DOMString shape;
    attribute long tabIndex;
    attribute DOMString target;
    attribute DOMString type;

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



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


interface nsIDOMHTMLFormElement;
interface nsIDOMHTMLOptionsCollection;

[scriptable, uuid(a6cf9090-15b3-11d2-932e-00805f8add32)]
interface nsIDOMHTMLSelectElement : nsIDOMHTMLElement
{
    readonly attribute DOMString type;
    attribute long selectedIndex;
    attribute DOMString value;
    attribute unsigned long length;
    readonly attribute nsIDOMHTMLFormElement form;
    readonly attribute nsIDOMHTMLOptionsCollection options;
    attribute boolean disabled;
    attribute boolean multiple;
    attribute DOMString name;
    attribute long size;
    attribute long tabIndex;
    
    void add(in nsIDOMHTMLElement element,
             in nsIDOMHTMLElement before)
             raises(DOMException);
    
    void remove(in long index);
    void blur();
    void focus();
};


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


interface nsIDOMHTMLFormElement;


[scriptable, uuid(a6cf9092-15b3-11d2-932e-00805f8add32)]
interface nsIDOMHTMLOptionElement : nsIDOMHTMLElement
{
    readonly attribute nsIDOMHTMLFormElement form;
    attribute boolean defaultSelected;
    readonly attribute DOMString text;
    readonly attribute long index;
    attribute boolean disabled;
    attribute DOMString label;
    attribute boolean selected;
    attribute DOMString value;
};

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

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



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

[scriptable, uuid(f8e350b9-9f31-451a-8c8f-d10fea26b780)]
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 JSVal aProperty,
                                        in PRUint32 aAction);

    /**
     * Checks whether the running script is allowed to connect to aTargetURI
     */
    [noscript] void checkConnect(in JSContextPtr aJSContext,
                                 in nsIURI aTargetURI,
                                 in string aClassName,
                                 in string aProperty);

    /**
     * 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.
     */
    [noscript] 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);
};

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


typedef long nsCacheStoragePolicy;
interface nsICacheSession;
interface nsICacheVisitor;

[scriptable, uuid(de114eb4-29fc-4959-b2f7-2d03eb9bc771)]
interface nsICacheService : nsISupports
{
    nsICacheSession createSession(in string clientID,
                        in nsCacheStoragePolicy storagePolicy,
                        in boolean streamBased);
    void visitEntries(in nsICacheVisitor visitor);
    void evictEntries(in nsCacheStoragePolicy storagePolicy);
};

///////////////////////////////////////////////////////////////////////////////
//  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(1ea19c6c-c59f-4fd7-9fc7-151e946baca0)]
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,
                          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;
};




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


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

[scriptable, uuid(69e5df00-7b8b-11d3-af61-00a024ffc08c)]
interface nsIWebBrowser : nsISupports
{
    void addWebBrowserListener(in nsIWeakReference listener, in nsIIDRef iid);
    void removeWebBrowserListener(in nsIWeakReference listener, in nsIIDRef iid);
    
    attribute nsIWebBrowserChrome containerWindow;
    attribute nsIURIContentListener parentURIContentListener;
    readonly attribute nsIDOMWindow contentDOMWindow;
};


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

[scriptable, uuid(8ADFB831-1053-4A19-884D-BCDAD7277B4B)]
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);

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

  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
   */
  nsIDOMStorage getSessionStorageForURI(in nsIURI uri);

  /*
   * Retrieves the WebApps session storage object for the supplied principal.
   *
   * @param principal returns a storage for this principal
   * @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 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;    
};