зеркало из https://github.com/mozilla/gecko-dev.git
422 строки
17 KiB
Plaintext
422 строки
17 KiB
Plaintext
/* -*- Mode: C++; tab-width: 2; 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 nsILoadGroup;
|
|
interface nsIInterfaceRequestor;
|
|
interface nsIFile;
|
|
interface nsIStreamIO;
|
|
|
|
typedef unsigned long nsLoadFlags;
|
|
|
|
/**
|
|
* The nsIChannel interface allows the user to construct I/O 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:
|
|
*
|
|
* - AsyncRead and AsyncWrite allow for asynchronous requests, calling
|
|
* back the user's stream listener or observer,
|
|
* - OpenInputStream and OpenOutputStream allow for synchronous reads
|
|
* and writes 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.
|
|
*
|
|
* Note that a channel is really only valid for one request. Reusing a channel
|
|
* after a request has completed for a subsequent request may have undefined
|
|
* results, depending on the channel implementation.
|
|
*
|
|
* Also of note are a special kind of channel called "transports." Transports
|
|
* also implement the nsIChannel interface, but operate at a lower level from
|
|
* protocol channels. The socket and file transports are notable implementations
|
|
* of transports and allow higher level channels to be implemented. The cache
|
|
* may also behave as a transport, and possibly things like sound playing services
|
|
* etc. Transports usually operate in a separate thread and often multiplex
|
|
* multiple requests for the same kind of service or resources.
|
|
*/
|
|
[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 start offset from the beginning of the data from/to which
|
|
* reads/writes will occur. Users may set the transferOffset before making
|
|
* any of the following requests: asyncOpen, asyncRead, asyncWrite,
|
|
* openInputStream, openOutputstream.
|
|
*/
|
|
attribute unsigned long transferOffset;
|
|
|
|
/**
|
|
* Accesses the count of bytes to be transfered. For openInputStream and
|
|
* asyncRead, this specifies the amount to read, for asyncWrite, this
|
|
* specifies the amount to write (note that for openOutputStream, the
|
|
* end of the data can be signified simply by closing the stream).
|
|
* If the transferCount is set after reading has been initiated, the
|
|
* amount specified will become the current remaining amount to read
|
|
* before the channel is closed (this can be useful if the content
|
|
* length is encoded at the start of the stream).
|
|
*
|
|
* A transferCount value of -1 means the amount is unspecified, i.e.
|
|
* read or write all the data that is available.
|
|
*/
|
|
attribute long transferCount;
|
|
|
|
/**
|
|
* 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;
|
|
|
|
/**
|
|
* 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;
|
|
|
|
/**
|
|
* 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 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;
|
|
|
|
/**
|
|
* Accesses the buffer segment size. The buffer segment size is used as
|
|
* the initial size for any transfer buffers, and the increment size for
|
|
* whenever the buffer space needs to be grown.
|
|
* (Note this parameter is passed along to any underlying nsIPipe objects.)
|
|
* If unspecified, the channel implementation picks a default.
|
|
*/
|
|
attribute unsigned long bufferSegmentSize;
|
|
|
|
/**
|
|
* Accesses the buffer maximum size. The buffer maximum size is the limit
|
|
* size that buffer will be grown to before suspending the channel.
|
|
* (Note this parameter is passed along to any underlying nsIPipe objects.)
|
|
* If unspecified, the channel implementation picks a default.
|
|
*/
|
|
attribute unsigned long bufferMaxSize;
|
|
|
|
/**
|
|
* Returns true if the data from this channel should be cached. Local files
|
|
* report false because they exist on the local disk and need not be cached.
|
|
* Input stream channels, data protocol, datetime protocol and finger
|
|
* protocol channels also should not be cached. Http and ftp on the other
|
|
* hand should. Note that the value of this attribute doesn't reflect any
|
|
* http headers that may specify that this channel should not be cached.
|
|
*/
|
|
readonly attribute boolean shouldCache;
|
|
|
|
/**
|
|
* Setting pipeliningAllowed causes the load of a URL (issued via asyncOpen,
|
|
* asyncRead or asyncWrite) to be deferred in order to allow the request to
|
|
* be pipelined for greater throughput efficiency. Pipelined requests will
|
|
* be forced to load when the first non-pipelined request is issued.
|
|
*/
|
|
attribute boolean pipeliningAllowed;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Load attribute flags. These 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;
|
|
|
|
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;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// nsIChannel operations
|
|
////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
* Opens a blocking input stream to the URL's specified source.
|
|
* @param startPosition - The offset from the start of the data
|
|
* from which to read.
|
|
* @param readCount - The number of bytes to read. If -1, everything
|
|
* up to the end of the data is read. If greater than the end of
|
|
* the data, the amount available is returned in the stream.
|
|
*/
|
|
nsIInputStream openInputStream();
|
|
|
|
/**
|
|
* Opens a blocking output stream to the URL's specified destination.
|
|
* @param startPosition - The offset from the start of the data
|
|
* from which to begin writing.
|
|
*/
|
|
nsIOutputStream openOutputStream();
|
|
|
|
/**
|
|
* !!WARNING!!: this interface method has become obsolete....I don't believe
|
|
* anyone actually implements this anymore. Just go ahead and call AsyncRead
|
|
* directly.
|
|
*
|
|
* Opens the channel asynchronously. The nsIStreamObserver's OnStartRequest
|
|
* method is called back when the channel actually becomes open, providing
|
|
* the content type. Its OnStopRequest method is called when the channel
|
|
* becomes closed.
|
|
*/
|
|
void asyncOpen(in nsIStreamObserver observer,
|
|
in nsISupports ctxt);
|
|
|
|
/**
|
|
* Reads asynchronously from the URL's specified source. Notifications
|
|
* are provided to the stream listener on the thread of the specified
|
|
* event queue.
|
|
* The startPosition argument designates the offset in the source where
|
|
* the data will be read.
|
|
* If the readCount == -1 then all the available data is delivered to
|
|
* the stream listener.
|
|
*/
|
|
void asyncRead(in nsIStreamListener listener,
|
|
in nsISupports ctxt);
|
|
|
|
/**
|
|
* Writes asynchronously to the URL's specified destination. Notifications
|
|
* are provided to the stream observer on the thread of the specified
|
|
* event queue.
|
|
* The startPosition argument designates the offset in the destination where
|
|
* the data will be written.
|
|
* If the writeCount == -1, then all the available data in the input
|
|
* stream is written.
|
|
*/
|
|
void asyncWrite(in nsIInputStream fromStream,
|
|
in nsIStreamObserver observer,
|
|
in nsISupports ctxt);
|
|
};
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
// nsIStreamIOChannel
|
|
|
|
/**
|
|
* nsIStreamIOChannel specializes nsIChannel to allow a simple channel to be
|
|
* constructed from an nsIStreamIO object and a URL.
|
|
*/
|
|
[scriptable, uuid(308362ce-0d06-11d4-986e-00c04fa0cf4a)]
|
|
interface nsIStreamIOChannel : nsIChannel
|
|
{
|
|
void init(in nsIURI uri,
|
|
in nsIStreamIO io);
|
|
};
|
|
|
|
%{C++
|
|
|
|
#define NS_STREAMIOCHANNEL_CLASSNAME "Stream I/O Channel"
|
|
#define NS_STREAMIOCHANNEL_PROGID "component://netscape/network/stream-io-channel"
|
|
|
|
#define NS_STREAMIOCHANNEL_CID \
|
|
{ /* 6ddb050c-0d04-11d4-986e-00c04fa0cf4a */ \
|
|
0x6ddb050c, \
|
|
0x0d04, \
|
|
0x11d4, \
|
|
{0x98, 0x6e, 0x00, 0xc0, 0x4f, 0xa0, 0xcf, 0x4a} \
|
|
}
|
|
|
|
%}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
* nsIFileChannel is an interface that allows for the initialization
|
|
* of a simple nsIChannel that is constructed from a single nsIFile and
|
|
* associated content type.
|
|
*/
|
|
[scriptable, uuid(68a26506-f947-11d3-8cda-0060b0fc14a3)]
|
|
interface nsIFileChannel : nsIChannel
|
|
{
|
|
/**
|
|
* Values for ioFlags parameters to be or'd together.
|
|
* (From prio.h)
|
|
*/
|
|
const long NS_RDONLY = 0x01;
|
|
const long NS_WRONLY = 0x02;
|
|
const long NS_RDWR = 0x04;
|
|
const long NS_CREATE_FILE = 0x08;
|
|
const long NS_APPEND = 0x10;
|
|
const long NS_TRUNCATE = 0x20;
|
|
const long NS_SYNC = 0x40;
|
|
const long NS_EXCL = 0x80;
|
|
|
|
void init(in nsIFile file,
|
|
in long ioFlags,
|
|
in long perm);
|
|
|
|
readonly attribute nsIFile file;
|
|
attribute long ioFlags;
|
|
attribute long permissions;
|
|
};
|
|
|
|
%{C++
|
|
|
|
#define NS_LOCALFILECHANNEL_CLASSNAME "Local File Channel"
|
|
#define NS_LOCALFILECHANNEL_PROGID "component://netscape/network/local-file-channel"
|
|
|
|
#define NS_LOCALFILECHANNEL_CID \
|
|
{ /* 6d5b2d44-f947-11d3-8cda-0060b0fc14a3 */ \
|
|
0x6d5b2d44, \
|
|
0xf947, \
|
|
0x11d3, \
|
|
{0x8c, 0xda, 0x00, 0x60, 0xb0, 0xfc, 0x14, 0xa3} \
|
|
}
|
|
|
|
%}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|