From 49204383e283c58535e5fa8465e340810e9c4cd7 Mon Sep 17 00:00:00 2001 From: Dan Witte Date: Thu, 16 Sep 2010 13:21:12 -0700 Subject: [PATCH] Bug 580448 - Document PCookieService.ipdl. r=jdm, a=fennec2.0+ --- netwerk/cookie/PCookieService.ipdl | 68 +++++++++++++++++++++++++++++ netwerk/cookie/nsICookieService.idl | 42 ++++++++++-------- 2 files changed, 91 insertions(+), 19 deletions(-) diff --git a/netwerk/cookie/PCookieService.ipdl b/netwerk/cookie/PCookieService.ipdl index 76f0fceb898..79ef1594ad6 100644 --- a/netwerk/cookie/PCookieService.ipdl +++ b/netwerk/cookie/PCookieService.ipdl @@ -47,16 +47,84 @@ 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, diff --git a/netwerk/cookie/nsICookieService.idl b/netwerk/cookie/nsICookieService.idl index aad6b990198..b5720d83886 100644 --- a/netwerk/cookie/nsICookieService.idl +++ b/netwerk/cookie/nsICookieService.idl @@ -88,10 +88,10 @@ 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 @@ -110,10 +110,10 @@ interface nsICookieService : nsISupports * 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. @@ -132,12 +132,14 @@ interface nsICookieService : nsISupports * 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 @@ -146,9 +148,6 @@ interface nsICookieService : nsISupports * 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); @@ -159,20 +158,25 @@ interface nsICookieService : nsISupports * 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