gecko-dev/uriloader/base/nsIWebProgressListener.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Mozilla browser.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications, Inc.  Portions created by Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Travis Bogard <travis@netscape.com>
 */

#include "nsISupports.idl"

/**
 * The nsIWebProgressListener interface is implemented by clients wishing to 
 * listen in on the progress associated with the loading of documents.
 *
 * @status UNDER_REVIEW
 */

interface nsIRequest;
interface nsIWebProgress;
interface nsIChannel;
interface nsIURI;

[scriptable, uuid(570F39D1-EFD0-11d3-B093-00A024FFC08C)]
interface nsIWebProgressListener : nsISupports
{
  /**
   * Progress state transition bits.
   * These flags indicate the various states that documents and requests
   * may transition through as they are being loaded.
   */
   const unsigned long STATE_START          = 0x00000001;
   const unsigned long STATE_REDIRECTING    = 0x00000002;
   const unsigned long STATE_TRANSFERRING   = 0x00000004;
   const unsigned long STATE_NEGOTIATING    = 0x00000008;
   const unsigned long STATE_STOP           = 0x00000010;

   /**
    * Progress type bits.
    * These flags indicate whether the transition is occuring on a document
    * or an individual request within the document.
    */
   const unsigned long STATE_IS_REQUEST     = 0x00010000;
   const unsigned long STATE_IS_DOCUMENT    = 0x00020000;
   const unsigned long STATE_IS_NETWORK     = 0x00040000;
   const unsigned long STATE_IS_WINDOW      = 0x00080000;
  
   /**
    * Security state bits
    */
   const unsigned long STATE_IS_INSECURE     = 0x00000000;
   const unsigned long STATE_IS_BROKEN       = 0x00000001;
   const unsigned long STATE_IS_SECURE       = 0x00000002;

   const unsigned long STATE_SECURE_HIGH     = 0x00000000;
   const unsigned long STATE_SECURE_MED      = 0x00010000;
   const unsigned long STATE_SECURE_LOW      = 0x00020000;


  /**
   * Notification indicating the state has changed for one of the requests
   * associated with the document loaded.
   *
   * @param aWebProgress    The nsIWebProgress instance that fired the
   *                        notification
   *
   * @param aRequest        The nsIRequest which has changed state.
   *
   * @param aStateFlags     Flags indicating the state change.
   *
   * @param aStatus         Status code for the state change.
   */
   void onStateChange(in nsIWebProgress aWebProgress,
                      in nsIRequest aRequest,
                      in long aStateFlags, // XXX TODO unsigned long
                      in unsigned long aStatus);

  /**
   * Notification that the progress has changed for one of the requests being
   * monitored.
   *
   * @param aWebProgress        The nsIWebProgress instance that fired the
   *                            notification
   *
   * @param aRequest            The nsIRequest that has new progress.
   *
   * @param aCurSelfProgress    The current progress for aRequest.
   *
   * @param aMaxSelfProgress    The maximum progress for aRequest.  If this
   *                            value is not known then -1 is passed.
   *
   * @param aCurTotalProgress   The current progress for all the requests
   *                            being monitored.
   *
   * @param aMaxTotalProgress   The total progress for all the requests being
   *                            monitored.  If this value is not known then
   *                            -1 is passed.
   */
   void onProgressChange(in nsIWebProgress aWebProgress,
                         in nsIRequest aRequest,
                         in long aCurSelfProgress,
                         in long aMaxSelfProgress,
                         in long aCurTotalProgress,
                         in long aMaxTotalProgress);
	/*
	Called when the window being watched changes the location that is currently.
	This is not when a load is requested, but rather once it is verified that 
	the load is going to occur in the given window.  For instance, a load that
	starts in a window might send progress and status messages, for the new site
	but it will not send the onLocationChange until we are sure we are loading
	this new page here.

	@param location - The URI of the location that is being loaded.
	*/
	void onLocationChange(in nsIWebProgress aWebProgress,
                          in nsIRequest aRequest,
                          in nsIURI location);

    /**
     * Notification that the status has changed. The status message is usually
     * printed in the status bar of the browser.
     */
    void onStatusChange(in nsIWebProgress aWebProgress,
                        in nsIRequest aRequest,
                        in nsresult aStatus,
                        in wstring aMessage);


    /**
     * Notification called for security progress.  
     * This method will be called on security transitions (eg HTTP -> HTTPS, 
     * HTTPS -> HTTP, FOO -> https) and after document load completion.  
     * It might also be called if an error occurs during network loading.
     *
     * These notification will only occur if a security package is installed.
     */


    void onSecurityChange(in nsIWebProgress aWebProgress,
                          in nsIRequest aRequest,
                          in long state);
};