Source code

Revision control

Other Tools

1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this
4
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6
#include "nsIRequest.idl"
7
#include "nsILoadInfo.idl"
8
9
interface nsIURI;
10
interface nsIInterfaceRequestor;
11
interface nsIInputStream;
12
interface nsIStreamListener;
13
14
%{C++
15
#include "nsCOMPtr.h"
16
%}
17
18
/**
19
* The nsIChannel interface allows clients to construct "GET" requests for
20
* specific protocols, and manage them in a uniform way. Once a channel is
21
* created (via nsIIOService::newChannel), parameters for that request may
22
* be set by using the channel attributes, or by QI'ing to a subclass of
23
* nsIChannel for protocol-specific parameters. Then, the URI can be fetched
24
* by calling nsIChannel::open or nsIChannel::asyncOpen.
25
*
26
* After a request has been completed, the channel is still valid for accessing
27
* protocol-specific results. For example, QI'ing to nsIHttpChannel allows
28
* response headers to be retrieved for the corresponding http transaction.
29
*
30
* This interface must be used only from the XPCOM main thread.
31
*/
32
[scriptable, uuid(2c389865-23db-4aa7-9fe5-60cc7b00697e)]
33
interface nsIChannel : nsIRequest
34
{
35
/**
36
* The original URI used to construct the channel. This is used in
37
* the case of a redirect or URI "resolution" (e.g. resolving a
38
* resource: URI to a file: URI) so that the original pre-redirect
39
* URI can still be obtained. This is never null. Attempts to
40
* set it to null must throw.
41
*
42
* NOTE: this is distinctly different from the http Referer (referring URI),
43
* which is typically the page that contained the original URI (accessible
44
* from nsIHttpChannel).
45
*/
46
attribute nsIURI originalURI;
47
48
/**
49
* The URI corresponding to the channel. Its value is immutable.
50
*/
51
readonly attribute nsIURI URI;
52
53
/**
54
* The owner, corresponding to the entity that is responsible for this
55
* channel. Used by the security manager to grant or deny privileges to
56
* mobile code loaded from this channel.
57
*
58
* NOTE: this is a strong reference to the owner, so if the owner is also
59
* holding a strong reference to the channel, care must be taken to
60
* explicitly drop its reference to the channel.
61
*/
62
attribute nsISupports owner;
63
64
/**
65
* The notification callbacks for the channel. This is set by clients, who
66
* wish to provide a means to receive progress, status and protocol-specific
67
* notifications. If this value is NULL, the channel implementation may use
68
* the notification callbacks from its load group. The channel may also
69
* query the notification callbacks from its load group if its notification
70
* callbacks do not supply the requested interface.
71
*
72
* Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
73
* and nsIAuthPrompt/nsIAuthPrompt2.
74
*
75
* When the channel is done, it must not continue holding references to
76
* this object.
77
*
78
* NOTE: A channel implementation should take care when "caching" an
79
* interface pointer queried from its notification callbacks. If the
80
* notification callbacks are changed, then a cached interface pointer may
81
* become invalid and may therefore need to be re-queried.
82
*/
83
attribute nsIInterfaceRequestor notificationCallbacks;
84
85
/**
86
* Transport-level security information (if any) corresponding to the
87
* channel.
88
*
89
* NOTE: In some circumstances TLS information is propagated onto
90
* non-nsIHttpChannel objects to indicate that their contents were likely
91
* delivered over TLS all the same.
92
*
93
* FIXME(bz, bug 1528449) is that still true now that
94
* document.open() doesn't do this?
95
*/
96
readonly attribute nsISupports securityInfo;
97
98
/**
99
* The MIME type of the channel's content if available.
100
*
101
* NOTE: the content type can often be wrongly specified (e.g., wrong file
102
* extension, wrong MIME type, wrong document type stored on a server, etc.),
103
* and the caller most likely wants to verify with the actual data.
104
*
105
* Setting contentType before the channel has been opened provides a hint
106
* to the channel as to what the MIME type is. The channel may ignore this
107
* hint in deciding on the actual MIME type that it will report.
108
*
109
* Setting contentType after onStartRequest has been fired or after open()
110
* is called will override the type determined by the channel.
111
*
112
* Setting contentType between the time that asyncOpen() is called and the
113
* time when onStartRequest is fired has undefined behavior at this time.
114
*
115
* The value of the contentType attribute is a lowercase string. A value
116
* assigned to this attribute will be parsed and normalized as follows:
117
* 1- any parameters (delimited with a ';') will be stripped.
118
* 2- if a charset parameter is given, then its value will replace the
119
* the contentCharset attribute of the channel.
120
* 3- the stripped contentType will be lowercased.
121
* Any implementation of nsIChannel must follow these rules.
122
*/
123
attribute ACString contentType;
124
125
/**
126
* The character set of the channel's content if available and if applicable.
127
* This attribute only applies to textual data.
128
*
129
* The value of the contentCharset attribute is a mixedcase string.
130
*/
131
attribute ACString contentCharset;
132
133
/**
134
* The length of the data associated with the channel if available. A value
135
* of -1 indicates that the content length is unknown. Note that this is a
136
* 64-bit value and obsoletes the "content-length" property used on some
137
* channels.
138
*/
139
attribute int64_t contentLength;
140
141
/**
142
* Synchronously open the channel.
143
*
144
* @return blocking input stream to the channel's data.
145
*
146
* NOTE: nsIChannel implementations are not required to implement this
147
* method. Moreover, since this method may block the calling thread, it
148
* should not be called on a thread that processes UI events. Like any
149
* other nsIChannel method it must not be called on any thread other
150
* than the XPCOM main thread.
151
*
152
* NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
153
* is reopened.
154
*/
155
nsIInputStream open();
156
157
/**
158
* Asynchronously open this channel. Data is fed to the specified stream
159
* listener as it becomes available. The stream listener's methods are
160
* called on the thread that calls asyncOpen and are not called until
161
* after asyncOpen returns. If asyncOpen returns successfully, the
162
* channel promises to call at least onStartRequest and onStopRequest.
163
*
164
* If the nsIRequest object passed to the stream listener's methods is not
165
* this channel, an appropriate onChannelRedirect notification needs to be
166
* sent to the notification callbacks before onStartRequest is called.
167
* Once onStartRequest is called, all following method calls on aListener
168
* will get the request that was passed to onStartRequest.
169
*
170
* If the channel's and loadgroup's notification callbacks do not provide
171
* an nsIChannelEventSink when onChannelRedirect would be called, that's
172
* equivalent to having called onChannelRedirect.
173
*
174
* If asyncOpen returns successfully, the channel is responsible for
175
* keeping itself alive until it has called onStopRequest on aListener or
176
* called onChannelRedirect.
177
*
178
* Implementations are allowed to synchronously add themselves to the
179
* associated load group (if any).
180
*
181
* NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
182
* channel is reopened.
183
* NOTE: Implementations should throw an error if the channel has been
184
* cancelled prior asyncOpen being called.
185
*
186
* @param aListener the nsIStreamListener implementation
187
* @see nsIChannelEventSink for onChannelRedirect
188
*/
189
void asyncOpen(in nsIStreamListener aListener);
190
191
/**************************************************************************
192
* Channel specific load flags:
193
*
194
* Bits 16-31 are reserved for future use by this interface or one of its
195
* derivatives (e.g., see nsICachingChannel).
196
*/
197
198
/**
199
* Set (e.g., by the docshell) to indicate whether or not the channel
200
* corresponds to a document URI.
201
* While setting this flag is sufficient to mark a channel as a document
202
* load, _checking_ whether the channel is a document load requires the use
203
* of the new channel.isDocument
204
*/
205
const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
206
207
/**
208
* If the end consumer for this load has been retargeted after discovering
209
* its content, this flag will be set:
210
*/
211
const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
212
213
/**
214
* This flag is set to indicate that this channel is replacing another
215
* channel. This means that:
216
*
217
* 1) the stream listener this channel will be notifying was initially
218
* passed to the asyncOpen method of some other channel
219
*
220
* and
221
*
222
* 2) this channel's URI is a better identifier of the resource being
223
* accessed than this channel's originalURI.
224
*
225
* This flag can be set, for example, for redirects or for cases when a
226
* single channel has multiple parts to it (and thus can follow
227
* onStopRequest with another onStartRequest/onStopRequest pair, each pair
228
* for a different request).
229
*/
230
const unsigned long LOAD_REPLACE = 1 << 18;
231
232
/**
233
* Set (e.g., by the docshell) to indicate whether or not the channel
234
* corresponds to an initial document URI load (e.g., link click).
235
*/
236
const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
237
238
/**
239
* Set (e.g., by the URILoader) to indicate whether or not the end consumer
240
* for this load has been determined.
241
*/
242
const unsigned long LOAD_TARGETED = 1 << 20;
243
244
/**
245
* If this flag is set, the channel should call the content sniffers as
246
* described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
247
*
248
* Note: Channels may ignore this flag; however, new channel implementations
249
* should only do so with good reason.
250
*/
251
const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;
252
253
/**
254
* This flag tells the channel to bypass URL classifier service check
255
* when opening the channel.
256
*/
257
const unsigned long LOAD_BYPASS_URL_CLASSIFIER = 1 << 22;
258
259
/**
260
* If this flag is set, the media-type content sniffer will be allowed
261
* to override any server-set content-type. Otherwise it will only
262
* be allowed to override "no content type" and application/octet-stream.
263
*/
264
const unsigned long LOAD_MEDIA_SNIFFER_OVERRIDES_CONTENT_TYPE = 1 << 23;
265
266
/**
267
* Set to let explicitely provided credentials be used over credentials
268
* we have cached previously. In some situations like form login using HTTP
269
* auth via XMLHttpRequest we need to let consumers override the cached
270
* credentials explicitely. For form login 403 response instead of 401 is
271
* usually used to prevent an auth dialog. But any code other then 401/7
272
* will leave original credentials in the cache and there is then no way
273
* to override them for the same user name.
274
*/
275
const unsigned long LOAD_EXPLICIT_CREDENTIALS = 1 << 24;
276
277
/**
278
* Set to force bypass of any service worker interception of the channel.
279
*/
280
const unsigned long LOAD_BYPASS_SERVICE_WORKER = 1 << 25;
281
282
// nsICachingChannel load flags begin at bit 26.
283
284
/**
285
* Access to the type implied or stated by the Content-Disposition header
286
* if available and if applicable. This allows determining inline versus
287
* attachment.
288
*
289
* Setting contentDisposition provides a hint to the channel about the
290
* disposition. If a normal Content-Disposition header is present its
291
* value will always be used. If it is missing the hinted value will
292
* be used if set.
293
*
294
* Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
295
* doesn't exist for this type of channel or is empty, and return
296
* DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present.
297
*/
298
attribute unsigned long contentDisposition;
299
const unsigned long DISPOSITION_INLINE = 0;
300
const unsigned long DISPOSITION_ATTACHMENT = 1;
301
302
/**
303
* Access to the filename portion of the Content-Disposition header if
304
* available and if applicable. This allows getting the preferred filename
305
* without having to parse it out yourself.
306
*
307
* Setting contentDispositionFilename provides a hint to the channel about
308
* the disposition. If a normal Content-Disposition header is present its
309
* value will always be used. If it is missing the hinted value will be
310
* used if set.
311
*
312
* Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't
313
* exist for this type of channel, if the header is empty, if the header
314
* doesn't contain a filename portion, or the value of the filename
315
* attribute is empty/missing.
316
*/
317
attribute AString contentDispositionFilename;
318
319
/**
320
* Access to the raw Content-Disposition header if available and applicable.
321
*
322
* Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
323
* doesn't exist for this type of channel or is empty.
324
*
325
* @deprecated Use contentDisposition/contentDispositionFilename instead.
326
*/
327
readonly attribute ACString contentDispositionHeader;
328
329
/**
330
* The LoadInfo object contains information about a network load, why it
331
* was started, and how we plan on using the resulting response.
332
* If a network request is redirected, the new channel will receive a new
333
* LoadInfo object. The new object will contain mostly the same
334
* information as the pre-redirect one, but updated as appropriate.
335
* For detailed information about what parts of LoadInfo are updated on
336
* redirect, see documentation on individual properties.
337
*/
338
attribute nsILoadInfo loadInfo;
339
340
/**
341
* Returns true if the channel is used to create a document.
342
* It returns true if the loadFlags have LOAD_DOCUMENT_URI set, or if
343
* LOAD_HTML_OBJECT_DATA is set and the channel has the appropriate
344
* MIME type.
345
* Note: May have the wrong value if called before OnStartRequest as we
346
* don't know the MIME type yet.
347
*/
348
readonly attribute bool isDocument;
349
350
%{ C++
351
inline bool IsDocument()
352
{
353
bool isDocument = false;
354
if (NS_SUCCEEDED(GetIsDocument(&isDocument)) && isDocument) {
355
return true;
356
}
357
return false;
358
}
359
360
inline already_AddRefed<nsILoadInfo> LoadInfo()
361
{
362
nsCOMPtr<nsILoadInfo> result;
363
mozilla::DebugOnly<nsresult> rv = GetLoadInfo(getter_AddRefs(result));
364
MOZ_ASSERT(NS_SUCCEEDED(rv) && result);
365
return result.forget();
366
}
367
%}
368
369
};
370
371
[builtinclass, scriptable, uuid(1ebbff64-d742-4f4a-aad5-4df2d1eb937a)]
372
interface nsIIdentChannel : nsIChannel
373
{
374
/**
375
* Unique ID of the channel, shared between parent and child. Needed if
376
* the channel activity needs to be monitored across process boundaries,
377
* like in devtools net monitor. See bug 1274556.
378
*/
379
[must_use] attribute uint64_t channelId;
380
381
%{ C++
382
inline uint64_t ChannelId()
383
{
384
uint64_t value = 0;
385
if (NS_SUCCEEDED(GetChannelId(&value))) {
386
return value;
387
}
388
return 0;
389
}
390
%}
391
};