netwerk/base/nsIRequest.idlScriptable
This interface is used by the request initiator to control the request.
Inherits from: nsISupports Last changed in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

For example nsIChannel typically passes itself as the nsIRequest argument to the nsIStreamListener on each onStartRequest, onDataAvaliable, and onStopRequest invocation.

Method overview

void cancel(in nsresult aStatus);
boolean isPending();
void resume();
void suspend();

Attributes

Attribute Type Description
loadFlags nsLoadFlags

The load flags of this request. Bits 0-15 are reserved.

When added to a load group, this request's load flags are merged with the load flags of the load group.
loadGroup nsILoadGroup The load group of this request. While pending, the request is a member of the load group. It is the responsibility of the request to implement this policy.
name AUTF8String The name of the request. Often this is the URI of the request. Read only.
status nsresult The error status associated with the request. Read only.

Constants

Various load flags which may be or'd together.

Constant Value Description
LOAD_NORMAL 0 No special load flags.
LOAD_BACKGROUND 1 << 0 Do not deliver status notifications to the nsIProgressEventSink, or keep this load from completing the nsILoadGroup it may belong to.

The following flags control the flow of data into the cache.

Constant Value Description
INHIBIT_CACHING 1 << 7 This flag prevents caching of any kind. It does not, however, prevent cached content from being used to satisfy this request.
INHIBIT_PERSISTENT_CACHING 1 << 8 This flag prevents caching on disk (or other persistent media), which may be needed to preserve privacy. For HTTPS, this flag is set automatically.

The following flags control what happens when the cache contains data that could perhaps satisfy this request. They are listed in descending order of precedence.

Constant Value Description
LOAD_BYPASS_CACHE 1 << 9 Force an end-to-end download of content data from the origin server. This flag is used for a shift-reload.
LOAD_FROM_CACHE 1 << 10 Load from the cache, bypassing protocol specific validation logic. This flag is used when browsing via history. It is not recommended for normal browsing as it may likely violate reasonable assumptions made by the server and confuse users.

The following flags control the frequency of cached content validation when neither LOAD_BYPASS_CACHE or LOAD_FROM_CACHE are set. By default, cached content is automatically validated if necessary before reuse.

Note: These flags are intended for normal browsing, and they should therefore not apply to content that must be validated before each use. Consider, for example, a HTTP response with a "Cache-control: no-cache" header. According to RFC2616, this response must be validated before it can be taken from a cache. Breaking this requirement could result in incorrect and potentially undesirable side-effects.

Constant Value Description
VALIDATE_ALWAYS 1 << 11 Forces validation of any cached content independent of its expiration time.
VALIDATE_NEVER 1 << 12 Disables validation of expired content.
VALIDATE_ONCE_PER_SESSION 1 << 13 Disables validation of expired content, provided it has already been validated (at least once) since the start of this session.
Constant Value Description
LOAD_ANONYMOUS 1 << 14

When set, this flag indicates that no user-specific data should be added to the request when opened. This means that things like authorization tokens or cookie headers should not be added.

Note: This will prevent proxy authentications from working, so use this flag with caution.

Methods

cancel()

Cancels the current request. This will close any open input or output streams and terminate any async requests. Users should normally pass NS_BINDING_ABORTED, although other errors may also be passed. The error passed in will become the value of the status attribute.

Implementations must not send any notifications (for example via nsIRequestObserver) synchronously from this function. Similarly, removal from the load group (if any) must also happen asynchronously.

Requests that use nsIStreamListener must not call onDataAvailable anymore after cancel has been called.

Note: Most nsIRequest implementations expect aStatus to be a failure code; however, some implementations may allow aStatus to be a success code such as NS_OK. In general, aStatus should be a failure code.

void cancel(
  in nsresult aStatus
);
Parameters
aStatus
The reason for canceling this request.

isPending()

Indicates whether the request is pending. isPending is true when there is an outstanding asynchronous event that will make the request no longer be pending. Requests do not necessarily start out pending; in some cases, requests have to be explicitly initiated (for example nsIChannel implementations are only pending once asyncOpen returns successfully).

Requests can become pending multiple times during their lifetime.

Note: Suspended requests are still considered pending.

boolean isPending();
Parameters

None.

Return value

true if the request has yet to reach completion.

resume()

Resumes the current request. This may have the effect of re-opening any underlying transport and will resume the delivery of data to any open streams.

void resume();
Parameters

None.

suspend()

Suspends the current request. This may have the effect of closing any underlying transport (in order to free up resources), although any open streams remain logically opened and will continue delivering data when the transport is resumed.

Calling cancel() on a suspended request must not send any notifications (such as onstopRequest) until the request is resumed.

Note: Some implementations are unable to immediately suspend, and may continue to deliver events already posted to an event queue. In general, callers should be capable of handling events even after suspending a request.

void suspend();
Parameters

None.