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 nsIWebProgress;
interface nsIRequest;
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 State 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     = 0x00000004;
  const unsigned long STATE_IS_BROKEN       = 0x00000001;
  const unsigned long STATE_IS_SECURE       = 0x00000002;

  const unsigned long STATE_SECURE_HIGH     = 0x00040000;
  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         Error status code associated with the state change.
  * This parameter should be ignored unless the status flag includes the
  * STATE_STOP bit. The status code will indicate success / failure of the
  * request associated with the state change.
  *
  * @return                NS_OK should always be returned.
  */
  void onStateChange(in nsIWebProgress aWebProgress,
                     in nsIRequest aRequest,
                     in unsigned long aStateFlags,
                     in nsresult 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.
  *
  * @return                    NS_OK should always be returned.
  */
  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.
  *
  * @return           NS_OK should always be returned.
  */
  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.
  *
  * @return           NS_OK should always be returned.
  */
  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.
  *
  * @return           NS_OK should always be returned.
  */


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