update comments to clarify that (get|set)CookieString[FromHTTP] should be passed a channel so that cookies are correctly get/set when third-party cookies are disabled by the user; rs=bzbarsky

--HG--
extra : rebase_source : bba695d76a8bdef06a64772e67dc6c8feaf656f8

netwerk/cookie/public/nsICookieService.idl

@@ -85,9 +85,11 @@ interface nsICookieService : nsISupports
    * @param aURI
    *        the URI of the document for which cookies are being queried.
    * @param aChannel
-   *        the channel used to load the document.  this parameter may be null,
+   *        the channel used to load the document.  this parameter should not
-   *        but it is strongly recommended that a non-null value be provided to
+   *        be null, otherwise the cookies will not be returned if third-party
-   *        ensure that the cookie privacy preferences are honored.
+   *        cookies have been disabled by the user. (the channel is used
+   *        to determine the originating URI of the document; if it is not
+   *        provided, the cookies will be assumed third-party.)
    *
    * @return the resulting cookie string
    */
@@ -105,9 +107,11 @@ interface nsICookieService : nsISupports
    *        the URI that the user originally typed in or clicked on to initiate
    *        the load of the document referenced by aURI.
    * @param aChannel
-   *        the channel used to load the document.  this parameter may be null,
+   *        the channel used to load the document.  this parameter should not
-   *        but it is strongly recommended that a non-null value be provided to
+   *        be null, otherwise the cookies will not be returned if third-party
-   *        ensure that the cookie privacy preferences are honored.
+   *        cookies have been disabled by the user. (the channel is used
+   *        to determine the originating URI of the document; if it is not
+   *        provided, the cookies will be assumed third-party.)
    *
    * @return the resulting cookie string
    */
@@ -123,9 +127,11 @@ interface nsICookieService : nsISupports
    * @param aCookie
    *        the cookie string to set.
    * @param aChannel
-   *        the channel used to load the document.  this parameter may be null,
+   *        the channel used to load the document.  this parameter should not
-   *        but it is strongly recommended that a non-null value be provided to
+   *        be null, otherwise the cookies will not be set if third-party
-   *        ensure that the cookie privacy preferences are honored.
+   *        cookies have been disabled by the user. (the channel is used
+   *        to determine the originating URI of the document; if it is not
+   *        provided, the cookies will be assumed third-party.)
    *
    * XXX should be able to allow null aPrompt, since nsIPrompt can be queryied
    * from aChannel.
@@ -151,9 +157,11 @@ interface nsICookieService : nsISupports
    *        the expiry information of the cookie (the Date header from the HTTP
    *        response).
    * @param aChannel
-   *        the channel used to load the document.  this parameter may be null,
+   *        the channel used to load the document.  this parameter should not
-   *        but it is strongly recommended that a non-null value be provided to
+   *        be null, otherwise the cookies will not be set if third-party
-   *        ensure that the cookie privacy preferences are honored.
+   *        cookies have been disabled by the user. (the channel is used
+   *        to determine the originating URI of the document; if it is not
+   *        provided, the cookies will be assumed third-party.)
    */
   void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);
 };