Mozilla

• About
• Developers
• Store
• Support
• Products

nsIRequest

---

This interface allows for control of a particular request, providing status information, including caching status, and the ability to stop, suspend, or resume loading. It is scriptable.

Methods

isPending

Checks whether a particular request is pending or has reached completion. Suspended requests are still considered pending.

Syntax:

boolean nsIRequest::isPending() 

Parameters:

None.

Returns:

TRUE if the request has yet to reach completion.

FALSE if the request has reached completion (e.g., after onStopRequest has been fired).

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.

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.

Syntax:

void nsIRequest::cancel(in nsresult aStatus) 

Parameters:

aStatus: The reason for canceling this request.

nsresult:

NS_OK if successful.

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.

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.

Syntax:

void nsIRequest::suspend()  

Parameters:

None.

nsresult:

NS_OK if successful.

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.

Syntax:

void nsIRequest::resume()  

Parameters:

None.

nsresult:

NS_OK if successful.

Attributes and Constants

readonly attribute AUTF8String nsIRequest::name

Gets the name of the request. Often this is the URI of the request.

readonly attribute nsresult nsIRequest::status

Gets the error status associated with the request.

attribute nsILoadGroup nsIRequest::loadGroup

Gets and sets 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.

attribute nsLoadFlags nsIRequest::loadFlags

Gets and sets 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.

See below for load flag values. They may be or'd together.

const unsigned long nsIRequest::LOAD_NORMAL=0

Indicates no special load flags.

const unsigned long nsIRequest::LOAD_BACKGROUND=1<<0

Don't deliver status notifications to the nsIProgressEventSink, or keep this load from completing the nsILoadGroup it may belong to.

const unsigned long nsIRequest::INHIBIT_CACHING=1<<7

Prevents caching of any kind. This flag does not, however, prevent cached content from being used to satisfy this request.

const unsigned long nsIRequest::INHIBIT_PERSISTENT_CACHING=1<<8

Prevents caching on disk (or other persistent media), which may be needed to preserve privacy. For HTTPS, this flag is set automatically.

const unsigned long nsIRequest::LOAD_BYPASS_CACHE=1<<9

Forces an end-to-end download of content data from the origin server. This flag is used for a shift-reload. It has higher precedence than nsIRequest::LOAD_FROM_CACHE below.

const unsigned long nsIRequest::LOAD_FROM_CACHE=1<<10

Loads 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.

const unsigned long nsIRequest::VALIDATE_ALWAYS=1<<11

Forces validation of any cached content independent of its expiration time

This set of three flags controls 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 to Implementors: 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.

const unsigned long nsIRequest::VALIDATE_NEVER=1<<12

Disables validation of expired content.

const unsigned long 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.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History