Bug 580448 - Document PCookieService.ipdl. r=jdm, a=fennec2.0+
authorDan Witte <dwitte@mozilla.com>
Thu, 16 Sep 2010 13:21:12 -0700
changeset 54195 ae219ca8c0a1980bd4b4a5c859cba425f17f9734
parent 54194 e36e9e20741fffc7157a8e7cc95dabf554fa7048
child 54196 b1827f807513324b2e84866cdb0149c54c79641d
push id15798
push userdwitte@mozilla.com
push dateThu, 16 Sep 2010 20:26:57 +0000
treeherdermozilla-central@9566518a9601 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjdm, fennec2.0
bugs580448
milestone2.0b7pre
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 580448 - Document PCookieService.ipdl. r=jdm, a=fennec2.0+
netwerk/cookie/PCookieService.ipdl
netwerk/cookie/nsICookieService.idl
--- a/netwerk/cookie/PCookieService.ipdl
+++ b/netwerk/cookie/PCookieService.ipdl
@@ -42,26 +42,94 @@ include protocol PNecko;
 
 include "mozilla/net/NeckoMessageUtils.h";
 
 using IPC::URI;
 
 namespace mozilla {
 namespace net {
 
+/**
+ * PCookieService
+ *
+ * Provides IPDL methods for setting and getting cookies. These are stored on
+ * and managed by the parent; the child process goes through the parent for
+ * all cookie operations. Lower-level programmatic operations (i.e. those
+ * provided by the nsICookieManager and nsICookieManager2 interfaces) are not
+ * currently implemented and requesting these interfaces in the child will fail.
+ *
+ * @see nsICookieService
+ * @see nsICookiePermission
+ */
+
 sync protocol PCookieService
 {
   manager PNecko;
 
 parent:
+
+  /*
+   * Get the complete cookie string associated with the URI. This is a sync
+   * call in order to avoid race conditions -- for instance, an HTTP response
+   * on the parent and script access on the child.
+   *
+   * @param host
+   *        Same as the 'aURI' argument to nsICookieService.getCookieString.
+   * @param originating
+   *        The originating URI associated with the request. This is used
+   *        to determine whether the request is first or third party, for
+   *        purposes of allowing access to cookies. This should be obtained
+   *        from nsICookiePermission.getOriginatingURI. This parameter may
+   *        be null; in this case, the request is assumed to be third party
+   *        and may be rejected depending on user preferences. In
+   *        nsICookieService.getCookieString, this argument is determined
+   *        from the aChannel argument.
+   * @param fromHttp
+   *        Whether the result is for an HTTP request header. This should be
+   *        true for nsICookieService.getCookieStringFromHttp calls, false
+   *        otherwise.
+   *
+   * @see nsICookieService.getCookieString
+   * @see nsICookieService.getCookieStringFromHttp
+   * @see nsICookiePermission.getOriginatingURI
+   *
+   * @return the resulting cookie string.
+   */
   sync GetCookieString(URI host,
                        URI originating,
                        bool fromHttp)
        returns (nsCString result);
 
+  /*
+   * Set a cookie string.
+   *
+   * @param host
+   *        Same as the 'aURI' argument to nsICookieService.setCookieString.
+   * @param originating
+   *        The originating URI associated with the request. This is used
+   *        to determine whether the request is first or third party, for
+   *        purposes of allowing access to cookies. This should be obtained
+   *        from nsICookiePermission.getOriginatingURI. This parameter may
+   *        be null; in this case, the request is assumed to be third party
+   *        and may be rejected depending on user preferences.
+   * @param cookieString
+   *        Same as the 'aCookie' argument to nsICookieService.setCookieString.
+   * @param serverTime
+   *        Same as the 'aServerTime' argument to
+   *        nsICookieService.setCookieStringFromHttp. If the string is empty or
+   *        null (e.g. for non-HTTP requests), the current local time is used.
+   * @param fromHttp
+   *        Whether the result is for an HTTP request header. This should be
+   *        true for nsICookieService.setCookieStringFromHttp calls, false
+   *        otherwise.
+   *
+   * @see nsICookieService.setCookieString
+   * @see nsICookieService.setCookieStringFromHttp
+   * @see nsICookiePermission.getOriginatingURI
+   */
   SetCookieString(URI host,
                   URI originating,
                   nsCString cookieString,
                   nsCString serverTime,
                   bool fromHttp);
 
   __delete__();
 };
--- a/netwerk/cookie/nsICookieService.idl
+++ b/netwerk/cookie/nsICookieService.idl
@@ -83,20 +83,20 @@ interface nsIChannel;
  */
 [scriptable, uuid(2aaa897a-293c-4d2b-a657-8c9b7136996d)]
 interface nsICookieService : nsISupports
 {
   /*
    * Get the complete cookie string associated with the URI.
    *
    * @param aURI
-   *        the URI of the document for which cookies are being queried.
-   *        file:// URI's (i.e. with an empty host) are allowed, but any other
+   *        The URI of the document for which cookies are being queried.
+   *        file:// URIs (i.e. with an empty host) are allowed, but any other
    *        scheme must have a non-empty host. A trailing dot in the host
-   *        is acceptable, and will be stripped.
+   *        is acceptable, and will be stripped. This argument must not be null.
    * @param aChannel
    *        the channel used to load the document.  this parameter should not
    *        be null, otherwise the cookies will not be returned if third-party
    *        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,20 +105,20 @@ interface nsICookieService : nsISupports
 
   /*
    * Get the complete cookie string associated with the URI.
    *
    * This function is NOT redundant with getCookieString, as the result
    * will be different based on httponly (see bug 178993)
    *
    * @param aURI
-   *        the URI of the document for which cookies are being queried.
-   *        file:// URI's (i.e. with an empty host) are allowed, but any other
+   *        The URI of the document for which cookies are being queried.
+   *        file:// URIs (i.e. with an empty host) are allowed, but any other
    *        scheme must have a non-empty host. A trailing dot in the host
-   *        is acceptable, and will be stripped.
+   *        is acceptable, and will be stripped. This argument must not be null.
    * @param aFirstURI
    *        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 should not
    *        be null, otherwise the cookies will not be returned if third-party
    *        cookies have been disabled by the user. (the channel is used
    *        to determine the originating URI of the document; if it is not
@@ -127,57 +127,61 @@ interface nsICookieService : nsISupports
    * @return the resulting cookie string
    */
   string getCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIChannel aChannel);
 
   /*
    * Set the cookie string associated with the URI.
    *
    * @param aURI
-   *        the URI of the document for which cookies are being set.
-   *        file:// URI's (i.e. with an empty host) are allowed, but any other
+   *        The URI of the document for which cookies are being queried.
+   *        file:// URIs (i.e. with an empty host) are allowed, but any other
    *        scheme must have a non-empty host. A trailing dot in the host
-   *        is acceptable, and will be stripped.
+   *        is acceptable, and will be stripped. This argument must not be null.
    * @param aPrompt
-   *        the prompt to use for all user-level cookie notifications.
+   *        the prompt to use for all user-level cookie notifications. This is
+   *        presently ignored and can be null. (Prompt information is determined
+   *        from the channel if necessary.)
    * @param aCookie
    *        the cookie string to set.
    * @param aChannel
    *        the channel used to load the document.  this parameter should not
    *        be null, otherwise the cookies will not be set if third-party
    *        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.
    */
   void setCookieString(in nsIURI aURI, in nsIPrompt aPrompt, in string aCookie, in nsIChannel aChannel);
 
   /*
    * Set the cookie string and expires associated with the URI.
    *
    * This function is NOT redundant with setCookieString, as the result
    * will be different based on httponly (see bug 178993)
    *
    * @param aURI
-   *        the URI of the document for which cookies are being set.
-   *        file:// URI's (i.e. with an empty host) are allowed, but any other
+   *        The URI of the document for which cookies are being queried.
+   *        file:// URIs (i.e. with an empty host) are allowed, but any other
    *        scheme must have a non-empty host. A trailing dot in the host
-   *        is acceptable, and will be stripped.
+   *        is acceptable, and will be stripped. This argument must not be null.
    * @param aFirstURI
    *        the URI that the user originally typed in or clicked on to initiate
    *        the load of the document referenced by aURI.
    * @param aPrompt
-   *        the prompt to use for all user-level cookie notifications.
+   *        the prompt to use for all user-level cookie notifications. This is
+   *        presently ignored and can be null. (Prompt information is determined
+   *        from the channel if necessary.)
    * @param aCookie
    *        the cookie string to set.
    * @param aServerTime
-   *        the expiry information of the cookie (the Date header from the HTTP
-   *        response).
+   *        the current time reported by the server, if available. This should
+   *        be the string from the Date header in an HTTP response. If the
+   *        string is empty or null, server time is assumed to be the current
+   *        local time. If provided, it will be used to calculate the expiry
+   *        time of the cookie relative to the server's local time.
    * @param aChannel
    *        the channel used to load the document.  this parameter should not
    *        be null, otherwise the cookies will not be set if third-party
    *        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);