michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: interface nsIPrompt;
michael@0: interface nsIChannel;
michael@0: 
michael@0: /**
michael@0:  * nsICookieService
michael@0:  *
michael@0:  * Provides methods for setting and getting cookies in the context of a
michael@0:  * page load.  See nsICookieManager for methods to manipulate the cookie
michael@0:  * database directly.  This separation of interface is mainly historical.
michael@0:  *
michael@0:  * This service broadcasts the notifications detailed below when the cookie
michael@0:  * list is changed, or a cookie is rejected.
michael@0:  *
michael@0:  * NOTE: observers of these notifications *must* not attempt to change profile
michael@0:  *       or switch into or out of private browsing mode from within the
michael@0:  *       observer. Doing so will cause undefined behavior. Mutating the cookie
michael@0:  *       list (e.g. by calling methods on nsICookieService and friends) is
michael@0:  *       allowed, but beware that there may be pending notifications you haven't
michael@0:  *       seen yet -- for instance, a "batch-deleted" notification will likely be
michael@0:  *       immediately followed by "added". You may check the state of the cookie
michael@0:  *       list to determine if this is the case.
michael@0:  *
michael@0:  * topic  : "cookie-changed"
michael@0:  *          broadcast whenever the cookie list changes in some way. see
michael@0:  *          explanation of data strings below.
michael@0:  * subject: see below.
michael@0:  * data   : "deleted"
michael@0:  *          a cookie was deleted. the subject is an nsICookie2 representing
michael@0:  *          the deleted cookie.
michael@0:  *          "added"
michael@0:  *          a cookie was added. the subject is an nsICookie2 representing
michael@0:  *          the added cookie.
michael@0:  *          "changed"
michael@0:  *          a cookie was changed. the subject is an nsICookie2 representing
michael@0:  *          the new cookie. (note that host, path, and name are invariant
michael@0:  *          for a given cookie; other parameters may change.)
michael@0:  *          "batch-deleted"
michael@0:  *          a set of cookies was purged (typically, because they have either
michael@0:  *          expired or because the cookie list has grown too large). The subject
michael@0:  *          is an nsIArray of nsICookie2's representing the deleted cookies.
michael@0:  *          Note that the array could contain a single cookie.
michael@0:  *          "cleared"
michael@0:  *          the entire cookie list was cleared. the subject is null.
michael@0:  *          "reload"
michael@0:  *          the entire cookie list should be reloaded.  the subject is null.
michael@0:  *
michael@0:  * topic  : "cookie-rejected"
michael@0:  *          broadcast whenever a cookie was rejected from being set as a
michael@0:  *          result of user prefs.
michael@0:  * subject: an nsIURI interface pointer representing the URI that attempted
michael@0:  *          to set the cookie.
michael@0:  * data   : none.
michael@0:  *
michael@0:  * topic  : "third-party-cookie-accepted"
michael@0:  *           broadcast whenever a third party cookie was accepted
michael@0:  * subject:  an nsIURI interface pointer representing the URI that attempted
michael@0:  *           to set the cookie.
michael@0:  * data   :  the referrer, or "?" if unknown
michael@0:  *
michael@0:  * topic  : "third-party-cookie-rejected"
michael@0:  *           broadcast whenever a third party cookie was rejected
michael@0:  * subject:  an nsIURI interface pointer representing the URI that attempted
michael@0:  *           to set the cookie.
michael@0:  * data   :  the referrer, or "?" if unknown
michael@0:  */
michael@0: [scriptable, uuid(2aaa897a-293c-4d2b-a657-8c9b7136996d)]
michael@0: interface nsICookieService : nsISupports
michael@0: {
michael@0:   /*
michael@0:    * Get the complete cookie string associated with the URI.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        The URI of the document for which cookies are being queried.
michael@0:    *        file:// URIs (i.e. with an empty host) are allowed, but any other
michael@0:    *        scheme must have a non-empty host. A trailing dot in the host
michael@0:    *        is acceptable, and will be stripped. This argument must not be null.
michael@0:    * @param aChannel
michael@0:    *        the channel used to load the document.  this parameter should not
michael@0:    *        be null, otherwise the cookies will not be returned if third-party
michael@0:    *        cookies have been disabled by the user. (the channel is used
michael@0:    *        to determine the originating URI of the document; if it is not
michael@0:    *        provided, the cookies will be assumed third-party.)
michael@0:    *
michael@0:    * @return the resulting cookie string
michael@0:    */
michael@0:   string getCookieString(in nsIURI aURI, in nsIChannel aChannel);
michael@0: 
michael@0:   /*
michael@0:    * Get the complete cookie string associated with the URI.
michael@0:    *
michael@0:    * This function is NOT redundant with getCookieString, as the result
michael@0:    * will be different based on httponly (see bug 178993)
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        The URI of the document for which cookies are being queried.
michael@0:    *        file:// URIs (i.e. with an empty host) are allowed, but any other
michael@0:    *        scheme must have a non-empty host. A trailing dot in the host
michael@0:    *        is acceptable, and will be stripped. This argument must not be null.
michael@0:    * @param aFirstURI
michael@0:    *        the URI that the user originally typed in or clicked on to initiate
michael@0:    *        the load of the document referenced by aURI.
michael@0:    * @param aChannel
michael@0:    *        the channel used to load the document.  this parameter should not
michael@0:    *        be null, otherwise the cookies will not be returned if third-party
michael@0:    *        cookies have been disabled by the user. (the channel is used
michael@0:    *        to determine the originating URI of the document; if it is not
michael@0:    *        provided, the cookies will be assumed third-party.)
michael@0:    *
michael@0:    * @return the resulting cookie string
michael@0:    */
michael@0:   string getCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIChannel aChannel);
michael@0: 
michael@0:   /*
michael@0:    * Set the cookie string associated with the URI.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        The URI of the document for which cookies are being queried.
michael@0:    *        file:// URIs (i.e. with an empty host) are allowed, but any other
michael@0:    *        scheme must have a non-empty host. A trailing dot in the host
michael@0:    *        is acceptable, and will be stripped. This argument must not be null.
michael@0:    * @param aPrompt
michael@0:    *        the prompt to use for all user-level cookie notifications. This is
michael@0:    *        presently ignored and can be null. (Prompt information is determined
michael@0:    *        from the channel if necessary.)
michael@0:    * @param aCookie
michael@0:    *        the cookie string to set.
michael@0:    * @param aChannel
michael@0:    *        the channel used to load the document.  this parameter should not
michael@0:    *        be null, otherwise the cookies will not be set if third-party
michael@0:    *        cookies have been disabled by the user. (the channel is used
michael@0:    *        to determine the originating URI of the document; if it is not
michael@0:    *        provided, the cookies will be assumed third-party.)
michael@0:    */
michael@0:   void setCookieString(in nsIURI aURI, in nsIPrompt aPrompt, in string aCookie, in nsIChannel aChannel);
michael@0: 
michael@0:   /*
michael@0:    * Set the cookie string and expires associated with the URI.
michael@0:    *
michael@0:    * This function is NOT redundant with setCookieString, as the result
michael@0:    * will be different based on httponly (see bug 178993)
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        The URI of the document for which cookies are being queried.
michael@0:    *        file:// URIs (i.e. with an empty host) are allowed, but any other
michael@0:    *        scheme must have a non-empty host. A trailing dot in the host
michael@0:    *        is acceptable, and will be stripped. This argument must not be null.
michael@0:    * @param aFirstURI
michael@0:    *        the URI that the user originally typed in or clicked on to initiate
michael@0:    *        the load of the document referenced by aURI.
michael@0:    * @param aPrompt
michael@0:    *        the prompt to use for all user-level cookie notifications. This is
michael@0:    *        presently ignored and can be null. (Prompt information is determined
michael@0:    *        from the channel if necessary.)
michael@0:    * @param aCookie
michael@0:    *        the cookie string to set.
michael@0:    * @param aServerTime
michael@0:    *        the current time reported by the server, if available. This should
michael@0:    *        be the string from the Date header in an HTTP response. If the
michael@0:    *        string is empty or null, server time is assumed to be the current
michael@0:    *        local time. If provided, it will be used to calculate the expiry
michael@0:    *        time of the cookie relative to the server's local time.
michael@0:    * @param aChannel
michael@0:    *        the channel used to load the document.  this parameter should not
michael@0:    *        be null, otherwise the cookies will not be set if third-party
michael@0:    *        cookies have been disabled by the user. (the channel is used
michael@0:    *        to determine the originating URI of the document; if it is not
michael@0:    *        provided, the cookies will be assumed third-party.)
michael@0:    */
michael@0:   void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);
michael@0: };