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 nsICookie2;
michael@0: interface nsIURI;
michael@0: interface nsIChannel;
michael@0: 
michael@0: typedef long nsCookieAccess;
michael@0: 
michael@0: /**
michael@0:  * An interface to test for cookie permissions
michael@0:  */
michael@0: [scriptable, uuid(11ddd4ed-8f5b-40b3-b2a0-27c20ea1c88d)]
michael@0: interface nsICookiePermission : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * nsCookieAccess values
michael@0:    */
michael@0:   const nsCookieAccess ACCESS_DEFAULT = 0;
michael@0:   const nsCookieAccess ACCESS_ALLOW   = 1;
michael@0:   const nsCookieAccess ACCESS_DENY    = 2;
michael@0: 
michael@0:   /**
michael@0:    * additional values for nsCookieAccess which may not match
michael@0:    * nsIPermissionManager. Keep 3-7 available to allow nsIPermissionManager to
michael@0:    * add values without colliding. ACCESS_SESSION is not directly returned by
michael@0:    * any methods on this interface.
michael@0:    */
michael@0:   const nsCookieAccess ACCESS_SESSION = 8;
michael@0:   const nsCookieAccess ACCESS_ALLOW_FIRST_PARTY_ONLY = 9;
michael@0:   const nsCookieAccess ACCESS_LIMIT_THIRD_PARTY = 10;
michael@0: 
michael@0:   /**
michael@0:    * setAccess
michael@0:    *
michael@0:    * this method is called to block cookie access for the given URI.  this
michael@0:    * may result in other URIs being blocked as well (e.g., URIs which share
michael@0:    * the same host name).
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        the URI to block
michael@0:    * @param aAccess
michael@0:    *        the new cookie access for the URI.
michael@0:    */
michael@0:   void setAccess(in nsIURI         aURI,
michael@0:                  in nsCookieAccess aAccess);
michael@0: 
michael@0:   /**
michael@0:    * canAccess
michael@0:    *
michael@0:    * this method is called to test whether or not the given URI/channel may
michael@0:    * access the cookie database, either to set or get cookies.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        the URI trying to access cookies
michael@0:    * @param aChannel
michael@0:    *        the channel corresponding to aURI
michael@0:    *
michael@0:    * @return one of the following nsCookieAccess values:
michael@0:    *         ACCESS_DEFAULT, ACCESS_ALLOW, ACCESS_DENY, or
michael@0:    *         ACCESS_ALLOW_FIRST_PARTY_ONLY
michael@0:    */
michael@0:   nsCookieAccess canAccess(in nsIURI     aURI,
michael@0:                            in nsIChannel aChannel);
michael@0: 
michael@0:   /**
michael@0:    * canSetCookie
michael@0:    *
michael@0:    * this method is called to test whether or not the given URI/channel may
michael@0:    * set a specific cookie.  this method is always preceded by a call to
michael@0:    * canAccess. it may modify the isSession and expiry attributes of the
michael@0:    * cookie via the aIsSession and aExpiry parameters, in order to limit
michael@0:    * or extend the lifetime of the cookie. this is useful, for instance, to
michael@0:    * downgrade a cookie to session-only if it fails to meet certain criteria.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        the URI trying to set the cookie
michael@0:    * @param aChannel
michael@0:    *        the channel corresponding to aURI
michael@0:    * @param aCookie
michael@0:    *        the cookie being added to the cookie database
michael@0:    * @param aIsSession
michael@0:    *        when canSetCookie is invoked, this is the current isSession attribute
michael@0:    *        of the cookie. canSetCookie may leave this value unchanged to
michael@0:    *        preserve this attribute of the cookie.
michael@0:    * @param aExpiry
michael@0:    *        when canSetCookie is invoked, this is the current expiry time of
michael@0:    *        the cookie. canSetCookie may leave this value unchanged to
michael@0:    *        preserve this attribute of the cookie.
michael@0:    *
michael@0:    * @return true if the cookie can be set.
michael@0:    */
michael@0:   boolean canSetCookie(in nsIURI     aURI,
michael@0:                        in nsIChannel aChannel,
michael@0:                        in nsICookie2 aCookie,
michael@0:                        inout boolean aIsSession,
michael@0:                        inout int64_t aExpiry);
michael@0: };
michael@0: 
michael@0: %{ C++
michael@0: /**
michael@0:  * The nsICookiePermission implementation is an XPCOM service registered
michael@0:  * under the ContractID:
michael@0:  */
michael@0: #define NS_COOKIEPERMISSION_CONTRACTID "@mozilla.org/cookie/permission;1"
michael@0: %}