modules/libpref/public/nsISecurityPref.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 /**
  41  * Interface for accessing preferences, bypassing the usual security check on
  42  * preferences starting with "capability". This interface is used by
  43  * nsScriptSecurityManager which needs unchecked access to security prefs.
  44  * *PLEASE* do not call this interface from any other file, as this
  45  * would be insecure.
  46  *
  47  * THIS INTERFACE SHOULD NEVER BE MADE SCRIPTABLE
  48  *
  49  * @see nsIPrefBranch
  50  */
  51
  52 [uuid(94afd973-8045-4c6c-89e6-75bdced4209e)]
  53 interface nsISecurityPref : nsISupports {
  54
  55   /**
  56    * Called to get the state of a "capability" boolean preference.
  57    *
  58    * @param pref     The boolean preference to get the state of.
  59    *
  60    * @return boolean The value of the requested boolean preference.
  61    *
  62    * @see securitySetBoolPref
  63    */
  64   boolean securityGetBoolPref(in string pref);
  65
  66   /**
  67    * Called to set the state of a "capability" boolean preference.
  68    *
  69    * @param pref   The boolean preference to set the state of.
  70    * @param value  The boolean value to set the preference to.
  71    *
  72    * @return NS_OK The value was successfully set.
  73    * @return Other The value was not set or is the wrong type.
  74    *
  75    * @see securityGetBoolPref
  76    */
  77   void securitySetBoolPref(in string pref, in boolean value);
  78
  79   /**
  80    * Called to get the state of a "capability" string preference.
  81    *
  82    * @param pref    The string preference to retrieve.
  83    *
  84    * @return string The value of the requested string preference.
  85    *
  86    * @see securitySetCharPref
  87    */
  88   string securityGetCharPref(in string pref);
  89
  90   /**
  91    * Called to set the state of a "capability" string preference.
  92    *
  93    * @param pref   The string preference to set.
  94    * @param value  The string value to set the preference to.
  95    *
  96    * @return NS_OK The value was successfully set.
  97    * @return Other The value was not set or is the wrong type.
  98    *
  99    * @see securityGetCharPref
 100    */
 101   void securitySetCharPref(in string pref, in string value);
 102
 103   /**
 104    * Called to get the state of a "capability" integer preference.
 105    *
 106    * @param pref  The integer preference to get the value of.
 107    *
 108    * @return long The value of the requested integer preference.
 109    *
 110    * @see securitySetIntPref
 111    */
 112   long securityGetIntPref(in string pref);
 113
 114   /**
 115    * Called to set the state of a "capability" integer preference.
 116    *
 117    * @param pref   The integer preference to set the value of.
 118    * @param value  The integer value to set the preference to.
 119    *
 120    * @return NS_OK The value was successfully set.
 121    * @return Other The value was not set or is the wrong type.
 122    *
 123    * @see securityGetIntPref
 124    */
 125   void securitySetIntPref(in string pref, in long value);
 126
 127   /**
 128    * Called to clear a user set value from a "capability" preference. This
 129    * will, in effect, reset the value to the default value. If no default value
 130    * exists the preference will cease to exist.
 131    *
 132    * @param pref_name The preference to be cleared.
 133    *
 134    * @note
 135    * This method does nothing if this object is a default branch.
 136    *
 137    * @return NS_OK The user preference was successfully cleared.
 138    * @return Other The preference does not exist or have a user set value.
 139    */
 140   void securityClearUserPref(in string pref_name);
 141
 142 };
 143
 144 /**
 145  * This interface allows checking whether getting capability prefs is allowed.
 146  */
 147 [uuid(c73c9a05-92ce-46e1-8f69-90a2a3a36104)]
 148 interface nsIPrefSecurityCheck : nsISupports {
 149   /**
 150    * Checks whether the currently executing script (if any) can access security
 151    * preferences. Corresponds to CapabilityPreferencesAccess.
 152    *
 153    * Exceptions from this method should be treated like a return value of false.
 154    */
 155   boolean canAccessSecurityPreferences();
 156 };
 157