The Tor Browser: comparison netwerk/protocol/http/nsIHttpChannel.idl

--1:000000000000
+:59bd873fc331
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+#include "nsIChannel.idl"
+interface nsIHttpHeaderVisitor;
+/**
+* nsIHttpChannel
+*
+* This interface allows for the modification of HTTP request parameters and
+* the inspection of the resulting HTTP response status and headers when they
+* become available.
+*/
+[scriptable, uuid(a01362a0-5c45-11e2-bcfd-0800200c9a66)]
+interface nsIHttpChannel : nsIChannel
+{
+/**************************************************************************
+* REQUEST CONFIGURATION
+*
+* Modifying request parameters after asyncOpen has been called is an error.
+*/
+/**
+* Set/get the HTTP request method (default is "GET").  Setter is case
+* insensitive; getter returns an uppercase string.
+*
+* This attribute may only be set before the channel is opened.
+*
+* NOTE: The data for a "POST" or "PUT" request can be configured via
+* nsIUploadChannel; however, after setting the upload data, it may be
+* necessary to set the request method explicitly.  The documentation
+* for nsIUploadChannel has further details.
+*
+* @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
+*/
+attribute ACString requestMethod;
+/**
+* Get/set the HTTP referrer URI.  This is the address (URI) of the
+* resource from which this channel's URI was obtained (see RFC2616 section
+* 14.36).
+*
+* This attribute may only be set before the channel is opened.
+*
+* NOTE: The channel may silently refuse to set the Referer header if the
+* URI does not pass certain security checks (e.g., a "https://" URL will
+* never be sent as the referrer for a plaintext HTTP request).  The
+* implementation is not required to throw an exception when the referrer
+* URI is rejected.
+*
+* @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
+*/
+attribute nsIURI referrer;
+/**
+* Read the proxy URI, which, if non-null, will be used to resolve
+* proxies for this channel.
+*/
+readonly attribute nsIURI proxyURI;
+/**
+* Get the value of a particular request header.
+*
+* @param aHeader
+*        The case-insensitive name of the request header to query (e.g.,
+*        "Cache-Control").
+*
+* @return the value of the request header.
+* @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
+*/
+ACString getRequestHeader(in ACString aHeader);
+/**
+* Set the value of a particular request header.
+*
+* This method allows, for example, the cookies module to add "Cookie"
+* headers to the outgoing HTTP request.
+*
+* This method may only be called before the channel is opened.
+*
+* @param aHeader
+*        The case-insensitive name of the request header to set (e.g.,
+*        "Cookie").
+* @param aValue
+*        The request header value to set (e.g., "X=1").
+* @param aMerge
+*        If true, the new header value will be merged with any existing
+*        values for the specified header.  This flag is ignored if the
+*        specified header does not support merging (e.g., the "Content-
+*        Type" header can only have one value).  The list of headers for
+*        which this flag is ignored is an implementation detail.  If this
+*        flag is false, then the header value will be replaced with the
+*        contents of |aValue|.
+*
+* If aValue is empty and aMerge is false, the header will be cleared.
+*
+* @throws NS_ERROR_IN_PROGRESS if called after the channel has been
+*         opened.
+*/
+void setRequestHeader(in ACString aHeader,
+in ACString aValue,
+in boolean aMerge);
+/**
+* Call this method to visit all request headers.  Calling setRequestHeader
+* while visiting request headers has undefined behavior.  Don't do it!
+*
+* @param aVisitor
+*        the header visitor instance.
+*/
+void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
+/**
+* This attribute is a hint to the channel to indicate whether or not
+* the underlying HTTP transaction should be allowed to be pipelined
+* with other transactions.  This should be set to FALSE, for example,
+* if the application knows that the corresponding document is likely
+* to be very large.
+*
+* This attribute is true by default, though other factors may prevent
+* pipelining.
+*
+* This attribute may only be set before the channel is opened.
+*
+* @throws NS_ERROR_FAILURE if set after the channel has been opened.
+*/
+attribute boolean allowPipelining;
+/**
+* This attribute specifies the number of redirects this channel is allowed
+* to make.  If zero, the channel will fail to redirect and will generate
+* a NS_ERROR_REDIRECT_LOOP failure status.
+*
+* NOTE: An HTTP redirect results in a new channel being created.  If the
+* new channel supports nsIHttpChannel, then it will be assigned a value
+* to its |redirectionLimit| attribute one less than the value of the
+* redirected channel's |redirectionLimit| attribute.  The initial value
+* for this attribute may be a configurable preference (depending on the
+* implementation).
+*/
+attribute unsigned long redirectionLimit;
+/**************************************************************************
+* RESPONSE INFO
+*
+* Accessing response info before the onStartRequest event is an error.
+*/
+/**
+* Get the HTTP response code (e.g., 200).
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+*/
+readonly attribute unsigned long responseStatus;
+/**
+* Get the HTTP response status text (e.g., "OK").
+*
+* NOTE: This returns the raw (possibly 8-bit) text from the server.  There
+* are no assumptions made about the charset of the returned text.  You
+* have been warned!
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+*/
+readonly attribute ACString responseStatusText;
+/**
+* Returns true if the HTTP response code indicates success.  The value of
+* nsIRequest::status will be NS_OK even when processing a 404 response
+* because a 404 response may include a message body that (in some cases)
+* should be shown to the user.
+*
+* Use this attribute to distinguish server error pages from normal pages,
+* instead of comparing the response status manually against the set of
+* valid response codes, if that is required by your application.
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+*/
+readonly attribute boolean requestSucceeded;
+/**
+* Get the value of a particular response header.
+*
+* @param aHeader
+*        The case-insensitive name of the response header to query (e.g.,
+*        "Set-Cookie").
+*
+* @return the value of the response header.
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest) or if the header is
+*         not set in the response.
+*/
+ACString getResponseHeader(in ACString header);
+/**
+* Set the value of a particular response header.
+*
+* This method allows, for example, the HTML content sink to inform the HTTP
+* channel about HTTP-EQUIV headers found in HTML <META> tags.
+*
+* @param aHeader
+*        The case-insensitive name of the response header to set (e.g.,
+*        "Cache-control").
+* @param aValue
+*        The response header value to set (e.g., "no-cache").
+* @param aMerge
+*        If true, the new header value will be merged with any existing
+*        values for the specified header.  This flag is ignored if the
+*        specified header does not support merging (e.g., the "Content-
+*        Type" header can only have one value).  The list of headers for
+*        which this flag is ignored is an implementation detail.  If this
+*        flag is false, then the header value will be replaced with the
+*        contents of |aValue|.
+*
+* If aValue is empty and aMerge is false, the header will be cleared.
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+* @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
+*         header is not allowed.
+*/
+void setResponseHeader(in ACString header,
+in ACString value,
+in boolean merge);
+/**
+* Call this method to visit all response headers.  Calling
+* setResponseHeader while visiting response headers has undefined
+* behavior.  Don't do it!
+*
+* @param aVisitor
+*        the header visitor instance.
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+*/
+void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
+/**
+* Returns true if the server sent a "Cache-Control: no-store" response
+* header.
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+*/
+boolean isNoStoreResponse();
+/**
+* Returns true if the server sent the equivalent of a "Cache-control:
+* no-cache" response header.  Equivalent response headers include:
+* "Pragma: no-cache", "Expires: 0", and "Expires" with a date value
+* in the past relative to the value of the "Date" header.
+*
+* @throws NS_ERROR_NOT_AVAILABLE if called before the response
+*         has been received (before onStartRequest).
+*/
+boolean isNoCacheResponse();
+/**
+* Instructs the channel to immediately redirect to a new destination.
+* Can only be called on channels not yet opened.
+*
+* This method provides no explicit conflict resolution. The last
+* caller to call it wins.
+*
+* @throws NS_ERROR_ALREADY_OPENED if called after the channel
+*         has been opened.
+*/
+void redirectTo(in nsIURI aNewURI);
+};

The Tor Browser / file comparison

comparison: netwerk/protocol/http/nsIHttpChannel.idl

netwerk/protocol/http/nsIHttpChannel.idl