win/idl/nsICookieService.idl - chromium/deps/xulrunner-sdk - Git at Google

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
  * The contents of this file are subject to the Mozilla Public License Version
  * 1.1 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
  * http://www.mozilla.org/MPL/
  *
  * Software distributed under the License is distributed on an "AS IS" basis,
  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  * for the specific language governing rights and limitations under the
  * License.
  *
  * The Original Code is mozilla.org code.
  *
  * The Initial Developer of the Original Code is
  * Netscape Communications Corporation.
  * Portions created by the Initial Developer are Copyright (C) 1998
  * the Initial Developer. All Rights Reserved.
  *
  * Contributor(s):
  *
  * Alternatively, the contents of this file may be used under the terms of
  * either the GNU General Public License Version 2 or later (the "GPL"), or
  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  * in which case the provisions of the GPL or the LGPL are applicable instead
  * of those above. If you wish to allow use of your version of this file only
  * under the terms of either the GPL or the LGPL, and not to allow others to
  * use your version of this file under the terms of the MPL, indicate your
  * decision by deleting the provisions above and replace them with the notice
  * and other provisions required by the GPL or the LGPL. If you do not delete
  * the provisions above, a recipient may use your version of this file under
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */

 #include "nsISupports.idl"

 interface nsIURI;
 interface nsIPrompt;
 interface nsIChannel;

 /**
  * nsICookieService
  *
  * Provides methods for setting and getting cookies in the context of a
  * page load.  See nsICookieManager for methods to manipulate the cookie
  * database directly.  This separation of interface is mainly historical.
  *
  * This service broadcasts the following notifications when the cookie
  * list is changed, or a cookie is rejected:
  *
  * topic  : "cookie-changed"
  *          broadcast whenever the cookie list changes in some way. there
  *          are four possible data strings for this notification; one
  *          notification will be broadcast for each change, and will involve
  *          a single cookie.
  * subject: an nsICookie2 interface pointer representing the cookie object
  *          that changed.
  * data   : "deleted"
  *          a cookie was deleted. the subject is the deleted cookie.
  *          "added"
  *          a cookie was added. the subject is the added cookie.
  *          "changed"
  *          a cookie was changed. the subject is the new cookie.
  *          "cleared"
  *          the entire cookie list was cleared. the subject is null.
  *
  * topic  : "cookie-rejected"
  *          broadcast whenever a cookie was rejected from being set as a
  *          result of user prefs.
  * subject: an nsIURI interface pointer representing the URI that attempted
  *          to set the cookie.
  * data   : none.
  */
 [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.
    * @param aChannel
    *        the channel used to load the document.  this parameter may be null,
    *        but it is strongly recommended that a non-null value be provided to
    *        ensure that the cookie privacy preferences are honored.
    *
    * @return the resulting cookie string
    */
   string getCookieString(in nsIURI aURI, in nsIChannel aChannel);

   /*
    * 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.
    * @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 may be null,
    *        but it is strongly recommended that a non-null value be provided to
    *        ensure that the cookie privacy preferences are honored.
    *
    * @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.
    * @param aPrompt
    *        the prompt to use for all user-level cookie notifications.
    * @param aCookie
    *        the cookie string to set.
    * @param aChannel
    *        the channel used to load the document.  this parameter may be null,
    *        but it is strongly recommended that a non-null value be provided to
    *        ensure that the cookie privacy preferences are honored.
    *
    * 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.
    * @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.
    * @param aCookie
    *        the cookie string to set.
    * @param aServerTime
    *        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,
    *        but it is strongly recommended that a non-null value be provided to
    *        ensure that the cookie privacy preferences are honored.
    */
   void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);
 };
	/* -- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -- */
	/* *** BEGIN LICENSE BLOCK ***
	* Version: MPL 1.1/GPL 2.0/LGPL 2.1
	*
	* The contents of this file are subject to the Mozilla Public License Version
	* 1.1 (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	* http://www.mozilla.org/MPL/
	*
	* Software distributed under the License is distributed on an "AS IS" basis,
	* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
	* for the specific language governing rights and limitations under the
	* License.
	*
	* The Original Code is mozilla.org code.
	*
	* The Initial Developer of the Original Code is
	* Netscape Communications Corporation.
	* Portions created by the Initial Developer are Copyright (C) 1998
	* the Initial Developer. All Rights Reserved.
	*
	* Contributor(s):
	*
	* Alternatively, the contents of this file may be used under the terms of
	* either the GNU General Public License Version 2 or later (the "GPL"), or
	* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
	* in which case the provisions of the GPL or the LGPL are applicable instead
	* of those above. If you wish to allow use of your version of this file only
	* under the terms of either the GPL or the LGPL, and not to allow others to
	* use your version of this file under the terms of the MPL, indicate your
	* decision by deleting the provisions above and replace them with the notice
	* and other provisions required by the GPL or the LGPL. If you do not delete
	* the provisions above, a recipient may use your version of this file under
	* the terms of any one of the MPL, the GPL or the LGPL.
	*
	* *** END LICENSE BLOCK *** */

	#include "nsISupports.idl"

	interface nsIURI;
	interface nsIPrompt;
	interface nsIChannel;

	/**
	* nsICookieService
	*
	* Provides methods for setting and getting cookies in the context of a
	* page load. See nsICookieManager for methods to manipulate the cookie
	* database directly. This separation of interface is mainly historical.
	*
	* This service broadcasts the following notifications when the cookie
	* list is changed, or a cookie is rejected:
	*
	* topic : "cookie-changed"
	* broadcast whenever the cookie list changes in some way. there
	* are four possible data strings for this notification; one
	* notification will be broadcast for each change, and will involve
	* a single cookie.
	* subject: an nsICookie2 interface pointer representing the cookie object
	* that changed.
	* data : "deleted"
	* a cookie was deleted. the subject is the deleted cookie.
	* "added"
	* a cookie was added. the subject is the added cookie.
	* "changed"
	* a cookie was changed. the subject is the new cookie.
	* "cleared"
	* the entire cookie list was cleared. the subject is null.
	*
	* topic : "cookie-rejected"
	* broadcast whenever a cookie was rejected from being set as a
	* result of user prefs.
	* subject: an nsIURI interface pointer representing the URI that attempted
	* to set the cookie.
	* data : none.
	*/
	[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.
	* @param aChannel
	* the channel used to load the document. this parameter may be null,
	* but it is strongly recommended that a non-null value be provided to
	* ensure that the cookie privacy preferences are honored.
	*
	* @return the resulting cookie string
	*/
	string getCookieString(in nsIURI aURI, in nsIChannel aChannel);

	/*
	* 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.
	* @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 may be null,
	* but it is strongly recommended that a non-null value be provided to
	* ensure that the cookie privacy preferences are honored.
	*
	* @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.
	* @param aPrompt
	* the prompt to use for all user-level cookie notifications.
	* @param aCookie
	* the cookie string to set.
	* @param aChannel
	* the channel used to load the document. this parameter may be null,
	* but it is strongly recommended that a non-null value be provided to
	* ensure that the cookie privacy preferences are honored.
	*
	* 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.
	* @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.
	* @param aCookie
	* the cookie string to set.
	* @param aServerTime
	* 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,
	* but it is strongly recommended that a non-null value be provided to
	* ensure that the cookie privacy preferences are honored.
	*/
	void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);
	};