1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIRequest.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,217 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsILoadGroup;
1.12 +
1.13 +typedef unsigned long nsLoadFlags;
1.14 +
1.15 +/**
1.16 + * nsIRequest
1.17 + */
1.18 +[scriptable, uuid(ef6bfbd2-fd46-48d8-96b7-9f8f0fd387fe)]
1.19 +interface nsIRequest : nsISupports
1.20 +{
1.21 + /**
1.22 + * The name of the request. Often this is the URI of the request.
1.23 + */
1.24 + readonly attribute AUTF8String name;
1.25 +
1.26 + /**
1.27 + * Indicates whether the request is pending. nsIRequest::isPending is
1.28 + * true when there is an outstanding asynchronous event that will make
1.29 + * the request no longer be pending. Requests do not necessarily start
1.30 + * out pending; in some cases, requests have to be explicitly initiated
1.31 + * (e.g. nsIChannel implementations are only pending once asyncOpen
1.32 + * returns successfully).
1.33 + *
1.34 + * Requests can become pending multiple times during their lifetime.
1.35 + *
1.36 + * @return TRUE if the request has yet to reach completion.
1.37 + * @return FALSE if the request has reached completion (e.g., after
1.38 + * OnStopRequest has fired).
1.39 + * @note Suspended requests are still considered pending.
1.40 + */
1.41 + boolean isPending();
1.42 +
1.43 + /**
1.44 + * The error status associated with the request.
1.45 + */
1.46 + readonly attribute nsresult status;
1.47 +
1.48 + /**
1.49 + * Cancels the current request. This will close any open input or
1.50 + * output streams and terminate any async requests. Users should
1.51 + * normally pass NS_BINDING_ABORTED, although other errors may also
1.52 + * be passed. The error passed in will become the value of the
1.53 + * status attribute.
1.54 + *
1.55 + * Implementations must not send any notifications (e.g. via
1.56 + * nsIRequestObserver) synchronously from this function. Similarly,
1.57 + * removal from the load group (if any) must also happen asynchronously.
1.58 + *
1.59 + * Requests that use nsIStreamListener must not call onDataAvailable
1.60 + * anymore after cancel has been called.
1.61 + *
1.62 + * @param aStatus the reason for canceling this request.
1.63 + *
1.64 + * NOTE: most nsIRequest implementations expect aStatus to be a
1.65 + * failure code; however, some implementations may allow aStatus to
1.66 + * be a success code such as NS_OK. In general, aStatus should be
1.67 + * a failure code.
1.68 + */
1.69 + void cancel(in nsresult aStatus);
1.70 +
1.71 + /**
1.72 + * Suspends the current request. This may have the effect of closing
1.73 + * any underlying transport (in order to free up resources), although
1.74 + * any open streams remain logically opened and will continue delivering
1.75 + * data when the transport is resumed.
1.76 + *
1.77 + * Calling cancel() on a suspended request must not send any
1.78 + * notifications (such as onstopRequest) until the request is resumed.
1.79 + *
1.80 + * NOTE: some implementations are unable to immediately suspend, and
1.81 + * may continue to deliver events already posted to an event queue. In
1.82 + * general, callers should be capable of handling events even after
1.83 + * suspending a request.
1.84 + */
1.85 + void suspend();
1.86 +
1.87 + /**
1.88 + * Resumes the current request. This may have the effect of re-opening
1.89 + * any underlying transport and will resume the delivery of data to
1.90 + * any open streams.
1.91 + */
1.92 + void resume();
1.93 +
1.94 + /**
1.95 + * The load group of this request. While pending, the request is a
1.96 + * member of the load group. It is the responsibility of the request
1.97 + * to implement this policy.
1.98 + */
1.99 + attribute nsILoadGroup loadGroup;
1.100 +
1.101 + /**
1.102 + * The load flags of this request. Bits 0-15 are reserved.
1.103 + *
1.104 + * When added to a load group, this request's load flags are merged with
1.105 + * the load flags of the load group.
1.106 + */
1.107 + attribute nsLoadFlags loadFlags;
1.108 +
1.109 + /**
1.110 + * Mask defining the bits reserved for nsIRequest LoadFlags
1.111 + */
1.112 + const unsigned long LOAD_REQUESTMASK = 0xFFFF;
1.113 +
1.114 + /**************************************************************************
1.115 + * Listed below are the various load flags which may be or'd together.
1.116 + */
1.117 +
1.118 + /**
1.119 + * No special load flags:
1.120 + */
1.121 + const unsigned long LOAD_NORMAL = 0;
1.122 +
1.123 + /**
1.124 + * Don't deliver status notifications to the nsIProgressEventSink, or keep
1.125 + * this load from completing the nsILoadGroup it may belong to.
1.126 + */
1.127 + const unsigned long LOAD_BACKGROUND = 1 << 0;
1.128 +
1.129 + /**************************************************************************
1.130 + * The following flags control the flow of data into the cache.
1.131 + */
1.132 +
1.133 + /**
1.134 + * This flag prevents loading of the request with an HTTP pipeline.
1.135 + * Generally this is because the resource is expected to take a
1.136 + * while to load and may cause head of line blocking problems.
1.137 + */
1.138 + const unsigned long INHIBIT_PIPELINE = 1 << 6;
1.139 +
1.140 + /**
1.141 + * This flag prevents caching of any kind. It does not, however, prevent
1.142 + * cached content from being used to satisfy this request.
1.143 + */
1.144 + const unsigned long INHIBIT_CACHING = 1 << 7;
1.145 +
1.146 + /**
1.147 + * This flag prevents caching on disk (or other persistent media), which
1.148 + * may be needed to preserve privacy. For HTTPS, this flag is set auto-
1.149 + * matically.
1.150 + */
1.151 + const unsigned long INHIBIT_PERSISTENT_CACHING = 1 << 8;
1.152 +
1.153 + /**************************************************************************
1.154 + * The following flags control what happens when the cache contains data
1.155 + * that could perhaps satisfy this request. They are listed in descending
1.156 + * order of precidence.
1.157 + */
1.158 +
1.159 + /**
1.160 + * Force an end-to-end download of content data from the origin server.
1.161 + * This flag is used for a shift-reload.
1.162 + */
1.163 + const unsigned long LOAD_BYPASS_CACHE = 1 << 9;
1.164 +
1.165 + /**
1.166 + * Attempt to force a load from the cache, bypassing ALL validation logic
1.167 + * (note: this is stronger than VALIDATE_NEVER, which still validates for
1.168 + * certain conditions).
1.169 + *
1.170 + * If the resource is not present in cache, it will be loaded from the
1.171 + * network. Combine this flag with LOAD_ONLY_FROM_CACHE if you wish to
1.172 + * perform cache-only loads without validation checks.
1.173 + *
1.174 + * This flag is used when browsing via history. It is not recommended for
1.175 + * normal browsing as it may likely violate reasonable assumptions made by
1.176 + * the server and confuse users.
1.177 + */
1.178 + const unsigned long LOAD_FROM_CACHE = 1 << 10;
1.179 +
1.180 + /**
1.181 + * The following flags control the frequency of cached content validation
1.182 + * when neither LOAD_BYPASS_CACHE or LOAD_FROM_CACHE are set. By default,
1.183 + * cached content is automatically validated if necessary before reuse.
1.184 + *
1.185 + * VALIDATE_ALWAYS forces validation of any cached content independent of
1.186 + * its expiration time.
1.187 + *
1.188 + * VALIDATE_NEVER disables validation of cached content, unless it arrived
1.189 + * with the "Cache: no-store" header, or arrived via HTTPS with the
1.190 + * "Cache: no-cache" header.
1.191 + *
1.192 + * VALIDATE_ONCE_PER_SESSION disables validation of expired content,
1.193 + * provided it has already been validated (at least once) since the start
1.194 + * of this session.
1.195 + *
1.196 + * NOTE TO IMPLEMENTORS:
1.197 + * These flags are intended for normal browsing, and they should therefore
1.198 + * not apply to content that must be validated before each use. Consider,
1.199 + * for example, a HTTP response with a "Cache-control: no-cache" header.
1.200 + * According to RFC2616, this response must be validated before it can
1.201 + * be taken from a cache. Breaking this requirement could result in
1.202 + * incorrect and potentially undesirable side-effects.
1.203 + */
1.204 + const unsigned long VALIDATE_ALWAYS = 1 << 11;
1.205 + const unsigned long VALIDATE_NEVER = 1 << 12;
1.206 + const unsigned long VALIDATE_ONCE_PER_SESSION = 1 << 13;
1.207 +
1.208 + /**
1.209 + * When set, this flag indicates that no user-specific data should be added
1.210 + * to the request when opened. This means that things like authorization
1.211 + * tokens or cookie headers should not be added.
1.212 + */
1.213 + const unsigned long LOAD_ANONYMOUS = 1 << 14;
1.214 +
1.215 + /**
1.216 + * When set, this flag indicates that caches of network connections,
1.217 + * particularly HTTP persistent connections, should not be used.
1.218 + */
1.219 + const unsigned long LOAD_FRESH_CONNECTION = 1 << 15;
1.220 +};
