netwerk/base/nsILoadGroup.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsIRequest.idl"
   7
   8 interface nsISimpleEnumerator;
   9 interface nsIRequestObserver;
  10 interface nsIInterfaceRequestor;
  11 interface nsIRequestContext;
  12
  13 /**
  14  * A load group maintains a collection of nsIRequest objects.
  15  * This is used in lots of places where groups of requests need to be tracked.
  16  * For example, Document::mDocumentLoadGroup is used to track all requests
  17  * made for subdocuments in order to track page load progress and allow all
  18  * requests made on behalf of the document to be stopped, etc.
  19  */
  20 [builtinclass, scriptable, uuid(f0c87725-7a35-463c-9ceb-2c07f23406cc)]
  21 interface nsILoadGroup : nsIRequest
  22 {
  23     /**
  24      * The group observer is notified when requests are added to and removed
  25      * from this load group.  The groupObserver is weak referenced.
  26      */
  27     attribute nsIRequestObserver groupObserver;
  28
  29     /**
  30      * Accesses the default load request for the group.  Each time a number
  31      * of requests are added to a group, the defaultLoadRequest may be set
  32      * to indicate that all of the requests are related to a base request.
  33      *
  34      * The load group inherits its load flags from the default load request.
  35      * If the default load request is NULL, then the group's load flags are
  36      * not changed.
  37      */
  38     attribute nsIRequest defaultLoadRequest;
  39
  40     /**
  41      * Adds a new request to the group.  This will cause the default load
  42      * flags to be applied to the request.  If this is a foreground
  43      * request then the groupObserver's onStartRequest will be called.
  44      *
  45      * If the request is the default load request or if the default load
  46      * request is null, then the load group will inherit its load flags from
  47      * the request.
  48      */
  49     void addRequest(in nsIRequest aRequest,
  50                     in nsISupports aContext);
  51
  52     /**
  53      * Removes a request from the group.  If this is a foreground request
  54      * then the groupObserver's onStopRequest will be called.
  55      *
  56      * By the time this call ends, aRequest will have been removed from the
  57      * loadgroup, even if this function throws an exception.
  58      */
  59     void removeRequest(in nsIRequest aRequest,
  60                        in nsISupports aContext,
  61                        in nsresult aStatus);
  62
  63     /**
  64      * Returns the requests contained directly in this group.
  65      * Enumerator element type: nsIRequest.
  66      */
  67     readonly attribute nsISimpleEnumerator requests;
  68
  69     /**
  70      * Returns the count of "active" requests (ie. requests without the
  71      * LOAD_BACKGROUND bit set).
  72      */
  73     readonly attribute unsigned long activeCount;
  74
  75     /**
  76      * Notification callbacks for the load group.
  77      */
  78     attribute nsIInterfaceRequestor notificationCallbacks;
  79
  80     /**
  81      * Context for managing things like js/css connection blocking,
  82      * and per-tab connection grouping.
  83      */
  84     readonly attribute unsigned long long requestContextID;
  85
  86     /**
  87      * The set of load flags that will be added to all new requests added to
  88      * this group. Any existing requests in the load group are not modified,
  89      * so it is expected these flags will be added before requests are added
  90      * to the group - typically via nsIDocShell::defaultLoadFlags on a new
  91      * docShell.
  92      * Note that these flags are *not* added to the default request for the
  93      * load group; it is expected the default request will already have these
  94      * flags (again, courtesy of setting nsIDocShell::defaultLoadFlags before
  95      * the docShell has created the default request.)
  96      */
  97     attribute nsLoadFlags defaultLoadFlags;
  98
  99     /**
 100      * Returns true if the loadGroup belongs to a discarded context, such as, a
 101      * terminated private browsing session.
 102      */
 103     [infallible]
 104     readonly attribute boolean isBrowsingContextDiscarded;
 105 };