mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-08 04:27:37 +00:00
238 lines
9.0 KiB
Plaintext
238 lines
9.0 KiB
Plaintext
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
|
|
*
|
|
* The contents of this file are subject to the Netscape Public
|
|
* License Version 1.1 (the "License"); you may not use this file
|
|
* except in compliance with the License. You may obtain a copy of
|
|
* the License at http://www.mozilla.org/NPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS
|
|
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
* implied. See the License for the specific language governing
|
|
* rights and limitations under the License.
|
|
*
|
|
* The Original Code is mozilla.org code.
|
|
*
|
|
* The Initial Developer of the Original Code is Netscape
|
|
* Communications Corporation. Portions created by Netscape are
|
|
* Copyright (C) 1998 Netscape Communications Corporation. All
|
|
* Rights Reserved.
|
|
*
|
|
* Contributor(s):
|
|
*/
|
|
|
|
#include "nsIRequest.idl"
|
|
|
|
interface nsIURI;
|
|
interface nsIInputStream;
|
|
interface nsIOutputStream;
|
|
interface nsIStreamObserver;
|
|
interface nsIStreamListener;
|
|
interface nsIStreamProvider;
|
|
interface nsILoadGroup;
|
|
interface nsIInterfaceRequestor;
|
|
interface nsIStreamIO;
|
|
|
|
typedef unsigned long nsLoadFlags;
|
|
|
|
/**
|
|
* The nsIChannel interface allows the user to construct get requests for
|
|
* specific protocols, and manage them in a uniform way. Once a channel
|
|
* is created (via nsIIOService::NewChannel), parameters for that request
|
|
* may be set by using the channel attributes, or by QueryInterfacing to a
|
|
* subclass of nsIChannel for protocol-specific parameters. Then the actual
|
|
* request can be issued in one of several ways:
|
|
*
|
|
* - AsyncOpen is used for asynchronous reading, calling back the
|
|
* user's stream listener.
|
|
* - Open is used for synchronous read on the underlying channel.
|
|
*
|
|
* After a request has been completed, the channel is still valid for
|
|
* accessing protocol-specific results. For example, QueryInterfacing to
|
|
* nsIHTTPChannel allows response headers to be retrieved that result from
|
|
* http transactions.
|
|
*
|
|
*/
|
|
|
|
[scriptable, uuid(1788e79e-f947-11d3-8cda-0060b0fc14a3)]
|
|
interface nsIChannel : nsIRequest
|
|
{
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// nsIChannel accessors
|
|
////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
* Returns the original URL used to construct the channel.
|
|
* This is used in the case of a redirect or URI "resolution" (e.g.
|
|
* resolving a resource: URI to a file: URI) so that the original
|
|
* pre-redirect URI can still be obtained.
|
|
*
|
|
* Note that this is distinctly different from the http referrer
|
|
* (referring URI) which is typically the page that contained the
|
|
* original URI (accessible from nsIHTTPChannel).
|
|
*/
|
|
attribute nsIURI originalURI;
|
|
|
|
/**
|
|
* Returns the URL to which the channel currently refers. If a redirect
|
|
* or URI resolution occurs, this accessor returns the current location
|
|
* to which the channel is referring.
|
|
*/
|
|
attribute nsIURI URI;
|
|
|
|
/**
|
|
* Accesses the owner corresponding to the entity that is
|
|
* responsible for this channel. Used by security code to grant
|
|
* or deny privileges to mobile code loaded from this channel.
|
|
*
|
|
* Note: This is a strong reference to the owner, so if the owner is also
|
|
* holding a pointer to the channel, care must be taken to explicitly drop
|
|
* its reference to the channel -- otherwise a leak will result.
|
|
*/
|
|
attribute nsISupports owner;
|
|
|
|
/**
|
|
* Accesses the load group in which the channel is a currently a member.
|
|
*/
|
|
attribute nsILoadGroup loadGroup;
|
|
|
|
/**
|
|
* Accesses the load attributes for the channel. E.g. setting the load
|
|
* attributes with the LOAD_QUIET bit set causes the loading process to
|
|
* not deliver status notifications to the program performing the load,
|
|
* and to not contribute to keeping any nsILoadGroup it may be contained
|
|
* in from firing its OnLoadComplete notification.
|
|
*/
|
|
attribute nsLoadFlags loadAttributes;
|
|
|
|
/**
|
|
* Accesses the capabilities callbacks of the channel. This is set by clients
|
|
* who wish to provide a means to receive progress, status and protocol-specific
|
|
* notifications.
|
|
*/
|
|
attribute nsIInterfaceRequestor notificationCallbacks;
|
|
|
|
/**
|
|
* Any security information about this channel. This can be null.
|
|
*/
|
|
readonly attribute nsISupports securityInfo;
|
|
|
|
/**
|
|
* Returns the content MIME type of the channel if available. Note that the
|
|
* content type can often be wrongly specified (wrong file extension, wrong
|
|
* MIME type, wrong document type stored on a server, etc.) and the caller
|
|
* most likely wants to verify with the actual data.
|
|
*/
|
|
attribute string contentType;
|
|
|
|
/**
|
|
* Returns the length of the data associated with the channel if available.
|
|
* If the length is unknown then -1 is returned.
|
|
*/
|
|
attribute long contentLength;
|
|
|
|
/**
|
|
* Open is used for synchronous read on the channel.
|
|
**/
|
|
nsIInputStream open();
|
|
|
|
/** AsyncOpen is used for asynchronous reading, calling back the
|
|
* user's stream listener.
|
|
**/
|
|
void asyncOpen(in nsIStreamListener listener, in nsISupports ctxt);
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Below are Load attribute flags which may be or'd together.
|
|
////////////////////////////////////////////////////////////////////////////
|
|
/**
|
|
* Note that more will follow for each protocol's implementation of a channel,
|
|
* although channel writers have to be careful to not let the flag bits
|
|
* overlap. Otherwise, users won't be able to create a single flag word
|
|
* of load attributes that applies to a number of different channel types.
|
|
*/
|
|
|
|
/**
|
|
* No special load attributes -- use defaults:
|
|
*/
|
|
const unsigned long LOAD_NORMAL = 0;
|
|
|
|
/**
|
|
* Don't deliver status notifications to the nsIProgressEventSink, or keep
|
|
* this load from completing the nsILoadGroup it may belong to:
|
|
*/
|
|
const unsigned long LOAD_BACKGROUND = 1 << 0;
|
|
|
|
/**
|
|
* Used exclusively by the uriloader and docshell to indicate whether or
|
|
* not this channel corresponds to the toplevel document.
|
|
*/
|
|
const unsigned long LOAD_DOCUMENT_URI = 1 << 1;
|
|
|
|
/**
|
|
* If the end consumer for this load has been retargeted after discovering
|
|
* it's content, this flag will be set:
|
|
*/
|
|
const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 2;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
/**
|
|
* The following flags control caching behavior. Not all protocols pay
|
|
* attention to all these flags, but they are applicable to more than one
|
|
* protocol, so they are defined here.
|
|
*/
|
|
|
|
/**
|
|
* Don't store data in the disk cache. This can be used to preserve
|
|
* privacy, e.g. so that no https transactions are recorded, or to avoid
|
|
* caching a stream to disk that is already stored in a local file,
|
|
* e.g. the mailbox: protocol.
|
|
*/
|
|
const unsigned long INHIBIT_PERSISTENT_CACHING = 1 << 8;
|
|
|
|
/**
|
|
* Force an end-to-end download of content data from the origin server (and
|
|
* any intervening proxies that sit between it and the client), e.g. this
|
|
* flag is used for a shift-reload.
|
|
*/
|
|
const unsigned long FORCE_RELOAD = 1 << 9;
|
|
|
|
/**
|
|
* Force revalidation with server (or proxy) to verify that cached content
|
|
* is up-to-date, e.g. by comparing last-modified date on server with that
|
|
* of the cached version. For example, this flag is used when the reload
|
|
* button is pressed.
|
|
*/
|
|
const unsigned long FORCE_VALIDATION = 1 << 10;
|
|
|
|
/**
|
|
* If the CACHE_AS_FILE flag is set, any stream content is stored in the
|
|
* cache as a single disk file. Content will not be cached in the memory
|
|
* cache nor will it be stored in any other type of cache, e.g. a flat-file
|
|
* cache database. This is used to implement the jar protocol handler and
|
|
* to provide the stream-as-file semantics required by the classic browser
|
|
* plugin API.
|
|
*/
|
|
const unsigned long CACHE_AS_FILE = 1 << 11;
|
|
|
|
/**
|
|
* When cache data is potentially out of date, it can be revalidated with
|
|
* the origin server to see if the content needs to be reloaded. The
|
|
* following four flags control how often this validation occurs.
|
|
* These flags are commonly used for "normal" loading. Note that
|
|
* the VALIDATE_HEURISTICALLY and VALIDATE_ONCE_PER_SESSION flags can be
|
|
* combined to validate heuristically but no more than once per session.
|
|
*/
|
|
const unsigned long VALIDATE_NEVER = 1 << 12;
|
|
const unsigned long VALIDATE_ALWAYS = 1 << 13;
|
|
const unsigned long VALIDATE_ONCE_PER_SESSION = 1 << 14;
|
|
const unsigned long VALIDATE_HEURISTICALLY = 1 << 15;
|
|
|
|
/**
|
|
* This flag is used to tell the webshell not to cancel the load in cases
|
|
* when the channel is receiving multipart/replace document
|
|
*/
|
|
const unsigned long LOAD_REPLACE = 1 << 16;
|
|
|
|
|
|
};
|
|
|