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 |
|
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.
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.
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.
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.
void suspend();
Parameters
None.