nsIHttpChannel.idl
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:12k
源码类别:
PlugIns编程
开发平台:
Visual C++
- /* -*- 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.
- *
- * The Initial Developer of the Original Code is
- * Netscape Communications.
- * Portions created by the Initial Developer are Copyright (C) 2001
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- * Gagan Saksena <gagan@netscape.com> (original author)
- * Darin Fisher <darin@netscape.com>
- *
- * 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 "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.
- *
- * @status FROZEN
- */
- [scriptable, uuid(9277fe09-f0cc-4cd9-bbce-581dd94b0260)]
- 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;
- /**
- * 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();
- };