WARNING: Most of this content (with the exception of the Mozilla 1.9 XPCOM reference) is very old, and can be expected to be out of date and possibly obsolete. For better XUL documentation, please visit the XUL hub at the Mozilla Developer Center.

nsIRequest

IID:ef6bfbd2-fd46-48d8-96b7-9f8f0fd387fe
Inherits From:nsISupports
Status:FROZEN

This interface is implemented by the following components:

Constants

No special load flags:
PRUint32 LOAD_NORMAL = 0
Don't deliver status notifications to the nsIProgressEventSink, or keep this load from completing the nsILoadGroup it may belong to.
PRUint32 LOAD_BACKGROUND = 1
This flag prevents caching of any kind. It does not, however, prevent cached content from being used to satisfy this request.
PRUint32 INHIBIT_CACHING = 128
This flag prevents caching on disk (or other persistent media), which may be needed to preserve privacy. For HTTPS, this flag is set auto- matically.
PRUint32 INHIBIT_PERSISTENT_CACHING = 256
Force an end-to-end download of content data from the origin server. This flag is used for a shift-reload.
PRUint32 LOAD_BYPASS_CACHE = 512
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.
PRUint32 LOAD_FROM_CACHE = 1024
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.

VALIDATE_ALWAYS forces validation of any cached content independent of its expiration time.

VALIDATE_NEVER disables validation of expired content.

VALIDATE_ONCE_PER_SESSION disables validation of expired content, provided it has already been validated (at least once) since the start of this session.

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.

PRUint32 VALIDATE_ALWAYS = 2048
PRUint32 VALIDATE_NEVER = 4096
PRUint32 VALIDATE_ONCE_PER_SESSION = 8192

Properties

nsLoadFlags loadFlags

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.

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

readonly AUTF8String name

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

readonly nsresult status

The error status associated with the request.

Methods

void cancel ( nsresult status ) PRBool isPending ( ) void resume ( ) void suspend ( )

void cancel ( nsresult status )

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 (e.g. 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 status to be a failure code; however, some implementations may allow status to be a success code such as NS_OK. In general, status should be a failure code.

Arguments:
status: the reason for canceling this request.

PRBool isPending ( )

Indicates whether the request is pending. nsIRequest::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 (e.g. nsIChannel implementations are only pending once asyncOpen returns successfully).

Requests can become pending multiple times during their lifetime.

Returns:
FALSE if the request has reached completion (e.g., after OnStopRequest has fired).

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

References

This interface is the type of the following properties:

nsILoadGroup.defaultLoadRequest, nsIMsgSend.runningRequest, nsIStreamLoader.request

This interface is passed as an argument to the following methods:

nsIContentHandler.handleContent, nsIContentSniffer.getMIMETypeFromContent, nsIDirIndexListener.onIndexAvailable, nsIDirIndexListener.onInformationAvailable, nsIDocNavStartProgressCallback.onDocNavStart, nsIDocShell.internalLoad, nsIDownloadObserver.onDownloadComplete, nsIDownloadProgressListener.onProgressChange, nsIDownloadProgressListener.onSecurityChange, nsIDownloadProgressListener.onStateChange, nsIExternalHelperAppService.doContent, nsILoadGroup.addRequest, nsILoadGroup.removeRequest, nsIProgressEventSink.onProgress, nsIProgressEventSink.onStatus, nsIRequestObserver.onStartRequest, nsIRequestObserver.onStopRequest, nsISmtpService.SendMailMessage, nsIStreamListener.onDataAvailable, nsIURIContentListener.doContent, nsIUnicharStreamListener.onUnicharDataAvailable, nsIWebContentConverterService.loadPreferredHandler, nsIWebProgressListener.onLocationChange, nsIWebProgressListener.onProgressChange, nsIWebProgressListener.onSecurityChange, nsIWebProgressListener.onStateChange, nsIWebProgressListener.onStatusChange, nsIWebProgressListener2.onProgressChange64

Reference documentation is generated from Mozilla's source.