1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla 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/MPL/
*
* 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 the Initial Developer are Copyright (C) 1998
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsIRequest.idl"
interface nsIURI;
interface nsIInterfaceRequestor;
interface nsIInputStream;
interface nsIStreamListener;
/**
* The nsIChannel interface allows clients 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 QI'ing to a subclass of
* nsIChannel for protocol-specific parameters. Then, the URI can be fetched
* by calling nsIChannel::open or nsIChannel::asyncOpen.
*
* After a request has been completed, the channel is still valid for accessing
* protocol-specific results. For example, QI'ing to nsIHttpChannel allows
* response headers to be retrieved for the corresponding http transaction.
*
* @status FROZEN
*/
[scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
interface nsIChannel : nsIRequest
{
/**
* The original URI 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: this is distinctly different from the http Referer (referring URI),
* which is typically the page that contained the original URI (accessible
* from nsIHttpChannel).
*/
attribute nsIURI originalURI;
/**
* The URI corresponding to the channel. Its value is immutable.
*/
readonly attribute nsIURI URI;
/**
* The owner, corresponding to the entity that is responsible for this
* channel. Used by the security manager 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 strong reference to the channel, care must be taken to
* explicitly drop its reference to the channel.
*/
attribute nsISupports owner;
/**
* The notification callbacks for the channel. This is set by clients, who
* wish to provide a means to receive progress, status and protocol-specific
* notifications. If this value is NULL, the channel implementation may use
* the notification callbacks from its load group. The channel may also
* query the notification callbacks from its load group if its notification
* callbacks do not supply the requested interface.
*
* Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
* and nsIAuthPrompt.
*
* When the channel is done, it must not continue holding references to
* this object.
*
* NOTE: A channel implementation should take care when "caching" an
* interface pointer queried from its notification callbacks. If the
* notification callbacks are changed, then a cached interface pointer may
* become invalid and may therefore need to be re-queried.
*/
attribute nsIInterfaceRequestor notificationCallbacks;
/**
* Transport-level security information (if any) corresponding to the channel.
*/
readonly attribute nsISupports securityInfo;
/**
* The MIME type of the channel's content if available.
*
* NOTE: the content type can often be wrongly specified (e.g., 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.
*
* Setting contentType before the channel has been opened provides a hint
* to the channel as to what the MIME type is. The channel may ignore this
* hint in deciding on the actual MIME type that it will report.
*
* Setting contentType after onStartRequest has been fired or after open()
* is called will override the type determined by the channel.
*
* Setting contentType between the time that asyncOpen() is called and the
* time when onStartRequest is fired has undefined behavior at this time.
*
* The value of the contentType attribute is a lowercase string. A value
* assigned to this attribute will be parsed and normalized as follows:
* 1- any parameters (delimited with a ';') will be stripped.
* 2- if a charset parameter is given, then its value will replace the
* the contentCharset attribute of the channel.
* 3- the stripped contentType will be lowercased.
* Any implementation of nsIChannel must follow these rules.
*/
attribute ACString contentType;
/**
* The character set of the channel's content if available and if applicable.
* This attribute only applies to textual data.
*
* The value of the contentCharset attribute is a mixedcase string.
*/
attribute ACString contentCharset;
/**
* The length of the data associated with the channel if available. A value
* of -1 indicates that the content length is unknown.
*
* Callers should prefer getting the "content-length" property
* as 64-bit value by QIing the channel to nsIPropertyBag2,
* if that interface is exposed by the channel.
*/
attribute long contentLength;
/**
* Synchronously open the channel.
*
* @return blocking input stream to the channel's data.
*
* NOTE: nsIChannel implementations are not required to implement this
* method. Moreover, since this method may block the calling thread, it
* should not be called on a thread that processes UI events.
*/
nsIInputStream open();
/**
* Asynchronously open this channel. Data is fed to the specified stream
* listener as it becomes available. The stream listener's methods are
* called on the thread that calls asyncOpen and are not called until
* after asyncOpen returns.
*
* @param aListener the nsIStreamListener implementation
* @param aContext an opaque parameter forwarded to aListener's methods
*/
void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
/**************************************************************************
* Channel specific load flags:
*
* Bits 21-31 are reserved for future use by this interface or one of its
* derivatives (e.g., see nsICachingChannel).
*/
/**
* Set (e.g., by the docshell) to indicate whether or not the channel
* corresponds to a document URI.
*/
const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
/**
* 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 << 17;
/**
* This flag is set to indicate that onStopRequest may be followed by
* another onStartRequest/onStopRequest pair. This flag is, for example,
* used by the multipart/replace stream converter.
*/
const unsigned long LOAD_REPLACE = 1 << 18;
/**
* Set (e.g., by the docshell) to indicate whether or not the channel
* corresponds to an initial document URI load (e.g., link click).
*/
const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
/**
* Set (e.g., by the URILoader) to indicate whether or not the end consumer
* for this load has been determined.
*/
const unsigned long LOAD_TARGETED = 1 << 20;
};
|
