netwerk/protocol/http/nsIHttpChannel.idl@6474c204b198
netwerk/protocol/http/nsIHttpChannel.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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/. */
6 #include "nsIChannel.idl"
8 interface nsIHttpHeaderVisitor;
10 /**
11 * nsIHttpChannel
12 *
13 * This interface allows for the modification of HTTP request parameters and
14 * the inspection of the resulting HTTP response status and headers when they
15 * become available.
16 */
17 [scriptable, uuid(a01362a0-5c45-11e2-bcfd-0800200c9a66)]
18 interface nsIHttpChannel : nsIChannel
19 {
20 /**************************************************************************
21 * REQUEST CONFIGURATION
22 *
23 * Modifying request parameters after asyncOpen has been called is an error.
24 */
26 /**
27 * Set/get the HTTP request method (default is "GET"). Setter is case
28 * insensitive; getter returns an uppercase string.
29 *
30 * This attribute may only be set before the channel is opened.
31 *
32 * NOTE: The data for a "POST" or "PUT" request can be configured via
33 * nsIUploadChannel; however, after setting the upload data, it may be
34 * necessary to set the request method explicitly. The documentation
35 * for nsIUploadChannel has further details.
36 *
37 * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
38 */
39 attribute ACString requestMethod;
41 /**
42 * Get/set the HTTP referrer URI. This is the address (URI) of the
43 * resource from which this channel's URI was obtained (see RFC2616 section
44 * 14.36).
45 *
46 * This attribute may only be set before the channel is opened.
47 *
48 * NOTE: The channel may silently refuse to set the Referer header if the
49 * URI does not pass certain security checks (e.g., a "https://" URL will
50 * never be sent as the referrer for a plaintext HTTP request). The
51 * implementation is not required to throw an exception when the referrer
52 * URI is rejected.
53 *
54 * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
55 */
56 attribute nsIURI referrer;
58 /**
59 * Read the proxy URI, which, if non-null, will be used to resolve
60 * proxies for this channel.
61 */
62 readonly attribute nsIURI proxyURI;
64 /**
65 * Get the value of a particular request header.
66 *
67 * @param aHeader
68 * The case-insensitive name of the request header to query (e.g.,
69 * "Cache-Control").
70 *
71 * @return the value of the request header.
72 * @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
73 */
74 ACString getRequestHeader(in ACString aHeader);
76 /**
77 * Set the value of a particular request header.
78 *
79 * This method allows, for example, the cookies module to add "Cookie"
80 * headers to the outgoing HTTP request.
81 *
82 * This method may only be called before the channel is opened.
83 *
84 * @param aHeader
85 * The case-insensitive name of the request header to set (e.g.,
86 * "Cookie").
87 * @param aValue
88 * The request header value to set (e.g., "X=1").
89 * @param aMerge
90 * If true, the new header value will be merged with any existing
91 * values for the specified header. This flag is ignored if the
92 * specified header does not support merging (e.g., the "Content-
93 * Type" header can only have one value). The list of headers for
94 * which this flag is ignored is an implementation detail. If this
95 * flag is false, then the header value will be replaced with the
96 * contents of |aValue|.
97 *
98 * If aValue is empty and aMerge is false, the header will be cleared.
99 *
100 * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
101 * opened.
102 */
103 void setRequestHeader(in ACString aHeader,
104 in ACString aValue,
105 in boolean aMerge);
107 /**
108 * Call this method to visit all request headers. Calling setRequestHeader
109 * while visiting request headers has undefined behavior. Don't do it!
110 *
111 * @param aVisitor
112 * the header visitor instance.
113 */
114 void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
116 /**
117 * This attribute is a hint to the channel to indicate whether or not
118 * the underlying HTTP transaction should be allowed to be pipelined
119 * with other transactions. This should be set to FALSE, for example,
120 * if the application knows that the corresponding document is likely
121 * to be very large.
122 *
123 * This attribute is true by default, though other factors may prevent
124 * pipelining.
125 *
126 * This attribute may only be set before the channel is opened.
127 *
128 * @throws NS_ERROR_FAILURE if set after the channel has been opened.
129 */
130 attribute boolean allowPipelining;
132 /**
133 * This attribute specifies the number of redirects this channel is allowed
134 * to make. If zero, the channel will fail to redirect and will generate
135 * a NS_ERROR_REDIRECT_LOOP failure status.
136 *
137 * NOTE: An HTTP redirect results in a new channel being created. If the
138 * new channel supports nsIHttpChannel, then it will be assigned a value
139 * to its |redirectionLimit| attribute one less than the value of the
140 * redirected channel's |redirectionLimit| attribute. The initial value
141 * for this attribute may be a configurable preference (depending on the
142 * implementation).
143 */
144 attribute unsigned long redirectionLimit;
147 /**************************************************************************
148 * RESPONSE INFO
149 *
150 * Accessing response info before the onStartRequest event is an error.
151 */
153 /**
154 * Get the HTTP response code (e.g., 200).
155 *
156 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
157 * has been received (before onStartRequest).
158 */
159 readonly attribute unsigned long responseStatus;
161 /**
162 * Get the HTTP response status text (e.g., "OK").
163 *
164 * NOTE: This returns the raw (possibly 8-bit) text from the server. There
165 * are no assumptions made about the charset of the returned text. You
166 * have been warned!
167 *
168 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
169 * has been received (before onStartRequest).
170 */
171 readonly attribute ACString responseStatusText;
173 /**
174 * Returns true if the HTTP response code indicates success. The value of
175 * nsIRequest::status will be NS_OK even when processing a 404 response
176 * because a 404 response may include a message body that (in some cases)
177 * should be shown to the user.
178 *
179 * Use this attribute to distinguish server error pages from normal pages,
180 * instead of comparing the response status manually against the set of
181 * valid response codes, if that is required by your application.
182 *
183 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
184 * has been received (before onStartRequest).
185 */
186 readonly attribute boolean requestSucceeded;
188 /**
189 * Get the value of a particular response header.
190 *
191 * @param aHeader
192 * The case-insensitive name of the response header to query (e.g.,
193 * "Set-Cookie").
194 *
195 * @return the value of the response header.
196 *
197 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
198 * has been received (before onStartRequest) or if the header is
199 * not set in the response.
200 */
201 ACString getResponseHeader(in ACString header);
203 /**
204 * Set the value of a particular response header.
205 *
206 * This method allows, for example, the HTML content sink to inform the HTTP
207 * channel about HTTP-EQUIV headers found in HTML <META> tags.
208 *
209 * @param aHeader
210 * The case-insensitive name of the response header to set (e.g.,
211 * "Cache-control").
212 * @param aValue
213 * The response header value to set (e.g., "no-cache").
214 * @param aMerge
215 * If true, the new header value will be merged with any existing
216 * values for the specified header. This flag is ignored if the
217 * specified header does not support merging (e.g., the "Content-
218 * Type" header can only have one value). The list of headers for
219 * which this flag is ignored is an implementation detail. If this
220 * flag is false, then the header value will be replaced with the
221 * contents of |aValue|.
222 *
223 * If aValue is empty and aMerge is false, the header will be cleared.
224 *
225 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
226 * has been received (before onStartRequest).
227 * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
228 * header is not allowed.
229 */
230 void setResponseHeader(in ACString header,
231 in ACString value,
232 in boolean merge);
234 /**
235 * Call this method to visit all response headers. Calling
236 * setResponseHeader while visiting response headers has undefined
237 * behavior. Don't do it!
238 *
239 * @param aVisitor
240 * the header visitor instance.
241 *
242 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
243 * has been received (before onStartRequest).
244 */
245 void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
247 /**
248 * Returns true if the server sent a "Cache-Control: no-store" response
249 * header.
250 *
251 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
252 * has been received (before onStartRequest).
253 */
254 boolean isNoStoreResponse();
256 /**
257 * Returns true if the server sent the equivalent of a "Cache-control:
258 * no-cache" response header. Equivalent response headers include:
259 * "Pragma: no-cache", "Expires: 0", and "Expires" with a date value
260 * in the past relative to the value of the "Date" header.
261 *
262 * @throws NS_ERROR_NOT_AVAILABLE if called before the response
263 * has been received (before onStartRequest).
264 */
265 boolean isNoCacheResponse();
267 /**
268 * Instructs the channel to immediately redirect to a new destination.
269 * Can only be called on channels not yet opened.
270 *
271 * This method provides no explicit conflict resolution. The last
272 * caller to call it wins.
273 *
274 * @throws NS_ERROR_ALREADY_OPENED if called after the channel
275 * has been opened.
276 */
277 void redirectTo(in nsIURI aNewURI);
278 };
