Adding some documentation on what exceptions get thrown in what circumstances.

netwerk/protocol/http/public/nsIHttpChannel.idl

@@ -63,10 +63,14 @@ interface nsIHttpChannel : nsIChannel
      * 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;
 
@@ -75,11 +79,15 @@ interface nsIHttpChannel : nsIChannel
      * 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;
 
@@ -91,6 +99,7 @@ interface nsIHttpChannel : nsIChannel
      *        "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);
 
@@ -100,6 +109,8 @@ interface nsIHttpChannel : nsIChannel
      * 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").
@@ -115,6 +126,9 @@ interface nsIHttpChannel : nsIChannel
      *        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,
@@ -138,6 +152,10 @@ interface nsIHttpChannel : nsIChannel
      *
      * 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;
 
@@ -164,6 +182,9 @@ interface nsIHttpChannel : nsIChannel
 
     /**
      * 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;
 
@@ -173,6 +194,9 @@ interface nsIHttpChannel : nsIChannel
      * 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;
 
@@ -185,6 +209,9 @@ interface nsIHttpChannel : nsIChannel
      * 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;
 
@@ -196,6 +223,10 @@ interface nsIHttpChannel : nsIChannel
      *        "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);
 
@@ -220,6 +251,11 @@ interface nsIHttpChannel : nsIChannel
      *        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,
@@ -232,12 +268,18 @@ interface nsIHttpChannel : nsIChannel
      *
      * @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();
 
@@ -246,6 +288,9 @@ interface nsIHttpChannel : nsIChannel
      * 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();
 };