1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/protocol/http/nsIHttpChannel.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,278 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsIChannel.idl"
1.10 +
1.11 +interface nsIHttpHeaderVisitor;
1.12 +
1.13 +/**
1.14 + * nsIHttpChannel
1.15 + *
1.16 + * This interface allows for the modification of HTTP request parameters and
1.17 + * the inspection of the resulting HTTP response status and headers when they
1.18 + * become available.
1.19 + */
1.20 +[scriptable, uuid(a01362a0-5c45-11e2-bcfd-0800200c9a66)]
1.21 +interface nsIHttpChannel : nsIChannel
1.22 +{
1.23 + /**************************************************************************
1.24 + * REQUEST CONFIGURATION
1.25 + *
1.26 + * Modifying request parameters after asyncOpen has been called is an error.
1.27 + */
1.28 +
1.29 + /**
1.30 + * Set/get the HTTP request method (default is "GET"). Setter is case
1.31 + * insensitive; getter returns an uppercase string.
1.32 + *
1.33 + * This attribute may only be set before the channel is opened.
1.34 + *
1.35 + * NOTE: The data for a "POST" or "PUT" request can be configured via
1.36 + * nsIUploadChannel; however, after setting the upload data, it may be
1.37 + * necessary to set the request method explicitly. The documentation
1.38 + * for nsIUploadChannel has further details.
1.39 + *
1.40 + * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
1.41 + */
1.42 + attribute ACString requestMethod;
1.43 +
1.44 + /**
1.45 + * Get/set the HTTP referrer URI. This is the address (URI) of the
1.46 + * resource from which this channel's URI was obtained (see RFC2616 section
1.47 + * 14.36).
1.48 + *
1.49 + * This attribute may only be set before the channel is opened.
1.50 + *
1.51 + * NOTE: The channel may silently refuse to set the Referer header if the
1.52 + * URI does not pass certain security checks (e.g., a "https://" URL will
1.53 + * never be sent as the referrer for a plaintext HTTP request). The
1.54 + * implementation is not required to throw an exception when the referrer
1.55 + * URI is rejected.
1.56 + *
1.57 + * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
1.58 + */
1.59 + attribute nsIURI referrer;
1.60 +
1.61 + /**
1.62 + * Read the proxy URI, which, if non-null, will be used to resolve
1.63 + * proxies for this channel.
1.64 + */
1.65 + readonly attribute nsIURI proxyURI;
1.66 +
1.67 + /**
1.68 + * Get the value of a particular request header.
1.69 + *
1.70 + * @param aHeader
1.71 + * The case-insensitive name of the request header to query (e.g.,
1.72 + * "Cache-Control").
1.73 + *
1.74 + * @return the value of the request header.
1.75 + * @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
1.76 + */
1.77 + ACString getRequestHeader(in ACString aHeader);
1.78 +
1.79 + /**
1.80 + * Set the value of a particular request header.
1.81 + *
1.82 + * This method allows, for example, the cookies module to add "Cookie"
1.83 + * headers to the outgoing HTTP request.
1.84 + *
1.85 + * This method may only be called before the channel is opened.
1.86 + *
1.87 + * @param aHeader
1.88 + * The case-insensitive name of the request header to set (e.g.,
1.89 + * "Cookie").
1.90 + * @param aValue
1.91 + * The request header value to set (e.g., "X=1").
1.92 + * @param aMerge
1.93 + * If true, the new header value will be merged with any existing
1.94 + * values for the specified header. This flag is ignored if the
1.95 + * specified header does not support merging (e.g., the "Content-
1.96 + * Type" header can only have one value). The list of headers for
1.97 + * which this flag is ignored is an implementation detail. If this
1.98 + * flag is false, then the header value will be replaced with the
1.99 + * contents of |aValue|.
1.100 + *
1.101 + * If aValue is empty and aMerge is false, the header will be cleared.
1.102 + *
1.103 + * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
1.104 + * opened.
1.105 + */
1.106 + void setRequestHeader(in ACString aHeader,
1.107 + in ACString aValue,
1.108 + in boolean aMerge);
1.109 +
1.110 + /**
1.111 + * Call this method to visit all request headers. Calling setRequestHeader
1.112 + * while visiting request headers has undefined behavior. Don't do it!
1.113 + *
1.114 + * @param aVisitor
1.115 + * the header visitor instance.
1.116 + */
1.117 + void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
1.118 +
1.119 + /**
1.120 + * This attribute is a hint to the channel to indicate whether or not
1.121 + * the underlying HTTP transaction should be allowed to be pipelined
1.122 + * with other transactions. This should be set to FALSE, for example,
1.123 + * if the application knows that the corresponding document is likely
1.124 + * to be very large.
1.125 + *
1.126 + * This attribute is true by default, though other factors may prevent
1.127 + * pipelining.
1.128 + *
1.129 + * This attribute may only be set before the channel is opened.
1.130 + *
1.131 + * @throws NS_ERROR_FAILURE if set after the channel has been opened.
1.132 + */
1.133 + attribute boolean allowPipelining;
1.134 +
1.135 + /**
1.136 + * This attribute specifies the number of redirects this channel is allowed
1.137 + * to make. If zero, the channel will fail to redirect and will generate
1.138 + * a NS_ERROR_REDIRECT_LOOP failure status.
1.139 + *
1.140 + * NOTE: An HTTP redirect results in a new channel being created. If the
1.141 + * new channel supports nsIHttpChannel, then it will be assigned a value
1.142 + * to its |redirectionLimit| attribute one less than the value of the
1.143 + * redirected channel's |redirectionLimit| attribute. The initial value
1.144 + * for this attribute may be a configurable preference (depending on the
1.145 + * implementation).
1.146 + */
1.147 + attribute unsigned long redirectionLimit;
1.148 +
1.149 +
1.150 + /**************************************************************************
1.151 + * RESPONSE INFO
1.152 + *
1.153 + * Accessing response info before the onStartRequest event is an error.
1.154 + */
1.155 +
1.156 + /**
1.157 + * Get the HTTP response code (e.g., 200).
1.158 + *
1.159 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.160 + * has been received (before onStartRequest).
1.161 + */
1.162 + readonly attribute unsigned long responseStatus;
1.163 +
1.164 + /**
1.165 + * Get the HTTP response status text (e.g., "OK").
1.166 + *
1.167 + * NOTE: This returns the raw (possibly 8-bit) text from the server. There
1.168 + * are no assumptions made about the charset of the returned text. You
1.169 + * have been warned!
1.170 + *
1.171 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.172 + * has been received (before onStartRequest).
1.173 + */
1.174 + readonly attribute ACString responseStatusText;
1.175 +
1.176 + /**
1.177 + * Returns true if the HTTP response code indicates success. The value of
1.178 + * nsIRequest::status will be NS_OK even when processing a 404 response
1.179 + * because a 404 response may include a message body that (in some cases)
1.180 + * should be shown to the user.
1.181 + *
1.182 + * Use this attribute to distinguish server error pages from normal pages,
1.183 + * instead of comparing the response status manually against the set of
1.184 + * valid response codes, if that is required by your application.
1.185 + *
1.186 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.187 + * has been received (before onStartRequest).
1.188 + */
1.189 + readonly attribute boolean requestSucceeded;
1.190 +
1.191 + /**
1.192 + * Get the value of a particular response header.
1.193 + *
1.194 + * @param aHeader
1.195 + * The case-insensitive name of the response header to query (e.g.,
1.196 + * "Set-Cookie").
1.197 + *
1.198 + * @return the value of the response header.
1.199 + *
1.200 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.201 + * has been received (before onStartRequest) or if the header is
1.202 + * not set in the response.
1.203 + */
1.204 + ACString getResponseHeader(in ACString header);
1.205 +
1.206 + /**
1.207 + * Set the value of a particular response header.
1.208 + *
1.209 + * This method allows, for example, the HTML content sink to inform the HTTP
1.210 + * channel about HTTP-EQUIV headers found in HTML <META> tags.
1.211 + *
1.212 + * @param aHeader
1.213 + * The case-insensitive name of the response header to set (e.g.,
1.214 + * "Cache-control").
1.215 + * @param aValue
1.216 + * The response header value to set (e.g., "no-cache").
1.217 + * @param aMerge
1.218 + * If true, the new header value will be merged with any existing
1.219 + * values for the specified header. This flag is ignored if the
1.220 + * specified header does not support merging (e.g., the "Content-
1.221 + * Type" header can only have one value). The list of headers for
1.222 + * which this flag is ignored is an implementation detail. If this
1.223 + * flag is false, then the header value will be replaced with the
1.224 + * contents of |aValue|.
1.225 + *
1.226 + * If aValue is empty and aMerge is false, the header will be cleared.
1.227 + *
1.228 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.229 + * has been received (before onStartRequest).
1.230 + * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
1.231 + * header is not allowed.
1.232 + */
1.233 + void setResponseHeader(in ACString header,
1.234 + in ACString value,
1.235 + in boolean merge);
1.236 +
1.237 + /**
1.238 + * Call this method to visit all response headers. Calling
1.239 + * setResponseHeader while visiting response headers has undefined
1.240 + * behavior. Don't do it!
1.241 + *
1.242 + * @param aVisitor
1.243 + * the header visitor instance.
1.244 + *
1.245 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.246 + * has been received (before onStartRequest).
1.247 + */
1.248 + void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
1.249 +
1.250 + /**
1.251 + * Returns true if the server sent a "Cache-Control: no-store" response
1.252 + * header.
1.253 + *
1.254 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.255 + * has been received (before onStartRequest).
1.256 + */
1.257 + boolean isNoStoreResponse();
1.258 +
1.259 + /**
1.260 + * Returns true if the server sent the equivalent of a "Cache-control:
1.261 + * no-cache" response header. Equivalent response headers include:
1.262 + * "Pragma: no-cache", "Expires: 0", and "Expires" with a date value
1.263 + * in the past relative to the value of the "Date" header.
1.264 + *
1.265 + * @throws NS_ERROR_NOT_AVAILABLE if called before the response
1.266 + * has been received (before onStartRequest).
1.267 + */
1.268 + boolean isNoCacheResponse();
1.269 +
1.270 + /**
1.271 + * Instructs the channel to immediately redirect to a new destination.
1.272 + * Can only be called on channels not yet opened.
1.273 + *
1.274 + * This method provides no explicit conflict resolution. The last
1.275 + * caller to call it wins.
1.276 + *
1.277 + * @throws NS_ERROR_ALREADY_OPENED if called after the channel
1.278 + * has been opened.
1.279 + */
1.280 + void redirectTo(in nsIURI aNewURI);
1.281 +};
