nsIWebProgressListener.idl
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:16k
源码类别:

PlugIns编程

开发平台:

Visual C++

  1. /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * ***** BEGIN LICENSE BLOCK *****
  4.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5.  *
  6.  * The contents of this file are subject to the Mozilla Public License Version
  7.  * 1.1 (the "License"); you may not use this file except in compliance with
  8.  * the License. You may obtain a copy of the License at
  9.  * http://www.mozilla.org/MPL/
  10.  *
  11.  * Software distributed under the License is distributed on an "AS IS" basis,
  12.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13.  * for the specific language governing rights and limitations under the
  14.  * License.
  15.  *
  16.  * The Original Code is the Mozilla browser.
  17.  *
  18.  * The Initial Developer of the Original Code is
  19.  * Netscape Communications, Inc.
  20.  * Portions created by the Initial Developer are Copyright (C) 1999
  21.  * the Initial Developer. All Rights Reserved.
  22.  *
  23.  * Contributor(s):
  24.  *   Travis Bogard <travis@netscape.com>
  25.  *   Darin Fisher <darin@meer.net>
  26.  *
  27.  * Alternatively, the contents of this file may be used under the terms of
  28.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30.  * in which case the provisions of the GPL or the LGPL are applicable instead
  31.  * of those above. If you wish to allow use of your version of this file only
  32.  * under the terms of either the GPL or the LGPL, and not to allow others to
  33.  * use your version of this file under the terms of the MPL, indicate your
  34.  * decision by deleting the provisions above and replace them with the notice
  35.  * and other provisions required by the GPL or the LGPL. If you do not delete
  36.  * the provisions above, a recipient may use your version of this file under
  37.  * the terms of any one of the MPL, the GPL or the LGPL.
  38.  *
  39.  * ***** END LICENSE BLOCK ***** */
  40. #include "nsISupports.idl"
  41. interface nsIWebProgress;
  42. interface nsIRequest;
  43. interface nsIURI;
  44. /**
  45.  * The nsIWebProgressListener interface is implemented by clients wishing to
  46.  * listen in on the progress associated with the loading of asynchronous
  47.  * requests in the context of a nsIWebProgress instance as well as any child
  48.  * nsIWebProgress instances.  nsIWebProgress.idl describes the parent-child
  49.  * relationship of nsIWebProgress instances.
  50.  *
  51.  * @status FROZEN
  52.  */
  53. [scriptable, uuid(570F39D1-EFD0-11d3-B093-00A024FFC08C)]
  54. interface nsIWebProgressListener : nsISupports
  55. {
  56.   /**
  57.    * State Transition Flags
  58.    *
  59.    * These flags indicate the various states that requests may transition
  60.    * through as they are being loaded.  These flags are mutually exclusive.
  61.    *
  62.    * For any given request, onStateChange is called once with the STATE_START
  63.    * flag, zero or more times with the STATE_TRANSFERRING flag or once with the
  64.    * STATE_REDIRECTING flag, and then finally once with the STATE_STOP flag.
  65.    * NOTE: For document requests, a second STATE_STOP is generated (see the
  66.    * description of STATE_IS_WINDOW for more details).
  67.    *
  68.    * STATE_START
  69.    *   This flag indicates the start of a request.  This flag is set when a
  70.    *   request is initiated.  The request is complete when onStateChange is
  71.    *   called for the same request with the STATE_STOP flag set.
  72.    *
  73.    * STATE_REDIRECTING
  74.    *   This flag indicates that a request is being redirected.  The request
  75.    *   passed to onStateChange is the request that is being redirected.  When a
  76.    *   redirect occurs, a new request is generated automatically to process the
  77.    *   new request.  Expect a corresponding STATE_START event for the new
  78.    *   request, and a STATE_STOP for the redirected request.
  79.    *
  80.    * STATE_TRANSFERRING
  81.    *   This flag indicates that data for a request is being transferred to an
  82.    *   end consumer.  This flag indicates that the request has been targeted,
  83.    *   and that the user may start seeing content corresponding to the request.
  84.    *
  85.    * STATE_NEGOTIATING
  86.    *   This flag is not used.
  87.    *
  88.    * STATE_STOP
  89.    *   This flag indicates the completion of a request.  The aStatus parameter
  90.    *   to onStateChange indicates the final status of the request.
  91.    */
  92.   const unsigned long STATE_START          = 0x00000001;
  93.   const unsigned long STATE_REDIRECTING    = 0x00000002;
  94.   const unsigned long STATE_TRANSFERRING   = 0x00000004;
  95.   const unsigned long STATE_NEGOTIATING    = 0x00000008;
  96.   const unsigned long STATE_STOP           = 0x00000010;
  97.   /**
  98.    * State Type Flags
  99.    *
  100.    * These flags further describe the entity for which the state transition is
  101.    * occuring.  These flags are NOT mutually exclusive (i.e., an onStateChange
  102.    * event may indicate some combination of these flags).
  103.    *
  104.    * STATE_IS_REQUEST
  105.    *   This flag indicates that the state transition is for a request, which
  106.    *   includes but is not limited to document requests.  (See below for a
  107.    *   description of document requests.)  Other types of requests, such as
  108.    *   requests for inline content (e.g., images and stylesheets) are
  109.    *   considered normal requests.
  110.    *
  111.    * STATE_IS_DOCUMENT
  112.    *   This flag indicates that the state transition is for a document request.
  113.    *   This flag is set in addition to STATE_IS_REQUEST.  A document request
  114.    *   supports the nsIChannel interface and its loadFlags attribute includes
  115.    *   the nsIChannel::LOAD_DOCUMENT_URI flag.
  116.    * 
  117.    *   A document request does not complete until all requests associated with
  118.    *   the loading of its corresponding document have completed.  This includes
  119.    *   other document requests (e.g., corresponding to HTML <iframe> elements).
  120.    *   The document corresponding to a document request is available via the
  121.    *   DOMWindow attribute of onStateChange's aWebProgress parameter.
  122.    *
  123.    * STATE_IS_NETWORK
  124.    *   This flag indicates that the state transition corresponds to the start
  125.    *   or stop of activity in the indicated nsIWebProgress instance.  This flag
  126.    *   is accompanied by either STATE_START or STATE_STOP, and it may be
  127.    *   combined with other State Type Flags.
  128.    *
  129.    *   Unlike STATE_IS_WINDOW, this flag is only set when activity within the
  130.    *   nsIWebProgress instance being observed starts or stops.  If activity
  131.    *   only occurs in a child nsIWebProgress instance, then this flag will be
  132.    *   set to indicate the start and stop of that activity.
  133.    *
  134.    *   For example, in the case of navigation within a single frame of a HTML
  135.    *   frameset, a nsIWebProgressListener instance attached to the
  136.    *   nsIWebProgress of the frameset window will receive onStateChange calls
  137.    *   with the STATE_IS_NETWORK flag set to indicate the start and stop of
  138.    *   said navigation.  In other words, an observer of an outer window can
  139.    *   determine when activity, that may be constrained to a child window or
  140.    *   set of child windows, starts and stops.
  141.    *
  142.    * STATE_IS_WINDOW
  143.    *   This flag indicates that the state transition corresponds to the start
  144.    *   or stop of activity in the indicated nsIWebProgress instance.  This flag
  145.    *   is accompanied by either STATE_START or STATE_STOP, and it may be
  146.    *   combined with other State Type Flags.
  147.    *
  148.    *   This flag is similar to STATE_IS_DOCUMENT.  However, when a document
  149.    *   request completes, two onStateChange calls with STATE_STOP are
  150.    *   generated.  The document request is passed as aRequest to both calls.
  151.    *   The first has STATE_IS_REQUEST and STATE_IS_DOCUMENT set, and the second
  152.    *   has the STATE_IS_WINDOW flag set (and possibly the STATE_IS_NETWORK flag
  153.    *   set as well -- see above for a description of when the STATE_IS_NETWORK
  154.    *   flag may be set).  This second STATE_STOP event may be useful as a way
  155.    *   to partition the work that occurs when a document request completes.
  156.    */
  157.   const unsigned long STATE_IS_REQUEST     = 0x00010000;
  158.   const unsigned long STATE_IS_DOCUMENT    = 0x00020000;
  159.   const unsigned long STATE_IS_NETWORK     = 0x00040000;
  160.   const unsigned long STATE_IS_WINDOW      = 0x00080000;
  161.   /**
  162.    * State Modifier Flags
  163.    *
  164.    * These flags further describe the transition which is occuring.  These
  165.    * flags are NOT mutually exclusive (i.e., an onStateChange event may
  166.    * indicate some combination of these flags).
  167.    *
  168.    * STATE_RESTORING
  169.    *   This flag indicates that the state transition corresponds to the start
  170.    *   or stop of activity for restoring a previously-rendered presentation.
  171.    *   As such, there is no actual network activity associated with this
  172.    *   request, and any modifications made to the document or presentation
  173.    *   when it was originally loaded will still be present.
  174.    */
  175.   const unsigned long STATE_RESTORING      = 0x01000000;
  176.   /**
  177.    * State Security Flags
  178.    *
  179.    * These flags describe the security state reported by a call to the
  180.    * onSecurityChange method.  These flags are mutually exclusive.
  181.    *
  182.    * STATE_IS_INSECURE
  183.    *   This flag indicates that the data corresponding to the request
  184.    *   was received over an insecure channel.
  185.    *
  186.    * STATE_IS_BROKEN
  187.    *   This flag indicates an unknown security state.  This may mean that the
  188.    *   request is being loaded as part of a page in which some content was
  189.    *   received over an insecure channel.
  190.    *
  191.    * STATE_IS_SECURE
  192.    *   This flag indicates that the data corresponding to the request was
  193.    *   received over a secure channel.  The degree of security is expressed by
  194.    *   STATE_SECURE_HIGH, STATE_SECURE_MED, or STATE_SECURE_LOW.
  195.    */
  196.   const unsigned long STATE_IS_INSECURE     = 0x00000004;
  197.   const unsigned long STATE_IS_BROKEN       = 0x00000001;
  198.   const unsigned long STATE_IS_SECURE       = 0x00000002;
  199.   /**
  200.    * Security Strength Flags
  201.    *
  202.    * These flags describe the security strength and accompany STATE_IS_SECURE
  203.    * in a call to the onSecurityChange method.  These flags are mutually
  204.    * exclusive.
  205.    *
  206.    * These flags are not meant to provide a precise description of data
  207.    * transfer security.  These are instead intended as a rough indicator that
  208.    * may be used to, for example, color code a security indicator or otherwise
  209.    * provide basic data transfer security feedback to the user.
  210.    *
  211.    * STATE_SECURE_HIGH
  212.    *   This flag indicates a high degree of security.
  213.    *
  214.    * STATE_SECURE_MED
  215.    *   This flag indicates a medium degree of security.
  216.    *
  217.    * STATE_SECURE_LOW
  218.    *   This flag indicates a low degree of security.
  219.    */
  220.   const unsigned long STATE_SECURE_HIGH     = 0x00040000;
  221.   const unsigned long STATE_SECURE_MED      = 0x00010000;
  222.   const unsigned long STATE_SECURE_LOW      = 0x00020000;
  223.   /**
  224.    * Notification indicating the state has changed for one of the requests
  225.    * associated with aWebProgress.
  226.    *
  227.    * @param aWebProgress
  228.    *        The nsIWebProgress instance that fired the notification
  229.    * @param aRequest
  230.    *        The nsIRequest that has changed state.
  231.    * @param aStateFlags
  232.    *        Flags indicating the new state.  This value is a combination of one
  233.    *        of the State Transition Flags and one or more of the State Type
  234.    *        Flags defined above.  Any undefined bits are reserved for future
  235.    *        use.
  236.    * @param aStatus
  237.    *        Error status code associated with the state change.  This parameter
  238.    *        should be ignored unless aStateFlags includes the STATE_STOP bit.
  239.    *        The status code indicates success or failure of the request
  240.    *        associated with the state change.  NOTE: aStatus may be a success
  241.    *        code even for server generated errors, such as the HTTP 404 error.
  242.    *        In such cases, the request itself should be queried for extended
  243.    *        error information (e.g., for HTTP requests see nsIHttpChannel).
  244.    */
  245.   void onStateChange(in nsIWebProgress aWebProgress,
  246.                      in nsIRequest aRequest,
  247.                      in unsigned long aStateFlags,
  248.                      in nsresult aStatus);
  249.   /**
  250.    * Notification that the progress has changed for one of the requests
  251.    * associated with aWebProgress.  Progress totals are reset to zero when all
  252.    * requests in aWebProgress complete (corresponding to onStateChange being
  253.    * called with aStateFlags including the STATE_STOP and STATE_IS_WINDOW
  254.    * flags).
  255.    *
  256.    * @param aWebProgress
  257.    *        The nsIWebProgress instance that fired the notification.
  258.    * @param aRequest
  259.    *        The nsIRequest that has new progress.
  260.    * @param aCurSelfProgress
  261.    *        The current progress for aRequest.
  262.    * @param aMaxSelfProgress
  263.    *        The maximum progress for aRequest.
  264.    * @param aCurTotalProgress
  265.    *        The current progress for all requests associated with aWebProgress.
  266.    * @param aMaxTotalProgress
  267.    *        The total progress for all requests associated with aWebProgress.
  268.    *
  269.    * NOTE: If any progress value is unknown, or if its value would exceed the
  270.    * maximum value of type long, then its value is replaced with -1.
  271.    *
  272.    * NOTE: If the object also implements nsIWebProgressListener2 and the caller
  273.    * knows about that interface, this function will not be called. Instead,
  274.    * nsIWebProgressListener2::onProgressChange64 will be called.
  275.    */
  276.   void onProgressChange(in nsIWebProgress aWebProgress,
  277.                         in nsIRequest aRequest,
  278.                         in long aCurSelfProgress,
  279.                         in long aMaxSelfProgress,
  280.                         in long aCurTotalProgress,
  281.                         in long aMaxTotalProgress);
  282.   /**
  283.    * Called when the location of the window being watched changes.  This is not
  284.    * when a load is requested, but rather once it is verified that the load is
  285.    * going to occur in the given window.  For instance, a load that starts in a
  286.    * window might send progress and status messages for the new site, but it
  287.    * will not send the onLocationChange until we are sure that we are loading
  288.    * this new page here.
  289.    *
  290.    * @param aWebProgress
  291.    *        The nsIWebProgress instance that fired the notification.
  292.    * @param aRequest
  293.    *        The associated nsIRequest.  This may be null in some cases.
  294.    * @param aLocation
  295.    *        The URI of the location that is being loaded.
  296.    */
  297.   void onLocationChange(in nsIWebProgress aWebProgress,
  298.                         in nsIRequest aRequest,
  299.                         in nsIURI aLocation);
  300.   /**
  301.    * Notification that the status of a request has changed.  The status message
  302.    * is intended to be displayed to the user (e.g., in the status bar of the
  303.    * browser).
  304.    *
  305.    * @param aWebProgress
  306.    *        The nsIWebProgress instance that fired the notification.
  307.    * @param aRequest
  308.    *        The nsIRequest that has new status.
  309.    * @param aStatus
  310.    *        This value is not an error code.  Instead, it is a numeric value
  311.    *        that indicates the current status of the request.  This interface
  312.    *        does not define the set of possible status codes.  NOTE: Some
  313.    *        status values are defined by nsITransport and nsISocketTransport.
  314.    * @param aMessage
  315.    *        Localized text corresponding to aStatus.
  316.    */
  317.   void onStatusChange(in nsIWebProgress aWebProgress,
  318.                       in nsIRequest aRequest,
  319.                       in nsresult aStatus,
  320.                       in wstring aMessage);
  321.   /**
  322.    * Notification called for security progress.  This method will be called on
  323.    * security transitions (eg HTTP -> HTTPS, HTTPS -> HTTP, FOO -> HTTPS) and
  324.    * after document load completion.  It might also be called if an error
  325.    * occurs during network loading.
  326.    *
  327.    * @param aWebProgress
  328.    *        The nsIWebProgress instance that fired the notification.
  329.    * @param aRequest
  330.    *        The nsIRequest that has new security state.
  331.    * @param aState
  332.    *        A value composed of the Security State Flags and the Security
  333.    *        Strength Flags listed above.  Any undefined bits are reserved for
  334.    *        future use.
  335.    *
  336.    * NOTE: These notifications will only occur if a security package is
  337.    * installed.
  338.    */
  339.   void onSecurityChange(in nsIWebProgress aWebProgress,
  340.                         in nsIRequest aRequest,
  341.                         in unsigned long aState);
  342. };