xpcom/ds/nsIWindowsRegKey.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is mozilla.org code.
  17  *
  18  * The Initial Developer of the Original Code is Google Inc.
  19  * Portions created by the Initial Developer are Copyright (C) 2005
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *  Darin Fisher <darin@meer.net>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 native HKEY(HKEY);
  42
  43 /**
  44  * This interface is designed to provide scriptable access to the Windows
  45  * registry system ("With Great Power Comes Great Responsibility").  The
  46  * interface represents a single key in the registry.
  47  *
  48  * This interface is highly Win32 specific.
  49  */
  50 [scriptable, uuid(2555b930-d64f-437e-9be7-0a2cb252c1f4)]
  51 interface nsIWindowsRegKey : nsISupports
  52 {
  53   /**
  54    * Root keys.  The values for these keys correspond to the values from
  55    * WinReg.h in the MS Platform SDK.  The ROOT_KEY_ prefix corresponds to the
  56    * HKEY_ prefix in the MS Platform SDK.
  57    *
  58    * This interface is not restricted to using only these root keys.
  59    */
  60   const unsigned long ROOT_KEY_CLASSES_ROOT     = 0x80000000;
  61   const unsigned long ROOT_KEY_CURRENT_USER     = 0x80000001;
  62   const unsigned long ROOT_KEY_LOCAL_MACHINE    = 0x80000002;
  63
  64   /**
  65    * Values for the mode parameter passed to the open and create methods.
  66    * The values defined here correspond to the REGSAM values defined in
  67    * WinNT.h in the MS Platform SDK, where ACCESS_ is replaced with KEY_.
  68    *
  69    * This interface is not restricted to using only these access types.
  70    */
  71   const unsigned long ACCESS_BASIC              = 0x00020000;
  72   const unsigned long ACCESS_QUERY_VALUE        = 0x00000001;
  73   const unsigned long ACCESS_SET_VALUE          = 0x00000002;
  74   const unsigned long ACCESS_CREATE_SUB_KEY     = 0x00000004;
  75   const unsigned long ACCESS_ENUMERATE_SUB_KEYS = 0x00000008;
  76   const unsigned long ACCESS_NOTIFY             = 0x00000010;
  77   const unsigned long ACCESS_READ               = ACCESS_BASIC |
  78                                                   ACCESS_QUERY_VALUE |
  79                                                   ACCESS_ENUMERATE_SUB_KEYS |
  80                                                   ACCESS_NOTIFY;
  81   const unsigned long ACCESS_WRITE              = ACCESS_BASIC |
  82                                                   ACCESS_SET_VALUE |
  83                                                   ACCESS_CREATE_SUB_KEY;
  84   const unsigned long ACCESS_ALL                = ACCESS_READ |
  85                                                   ACCESS_WRITE;
  86
  87   /**
  88    * Values for the type of a registry value.  The numeric values of these
  89    * constants are taken directly from WinNT.h in the MS Platform SDK.
  90    * The Microsoft documentation should be consulted for the exact meaning of
  91    * these value types.
  92    *
  93    * This interface is somewhat restricted to using only these value types.
  94    * There is no method that is directly equivalent to RegQueryValueEx or
  95    * RegSetValueEx.  In particular, this interface does not support the
  96    * REG_MULTI_SZ and REG_EXPAND_SZ value types.  It is still possible to
  97    * enumerate values that have other types (i.e., getValueType may return a
  98    * type not defined below).
  99    */
 100   const unsigned long TYPE_NONE   = 0;  // REG_NONE
 101   const unsigned long TYPE_STRING = 1;  // REG_SZ
 102   const unsigned long TYPE_BINARY = 3;  // REG_BINARY
 103   const unsigned long TYPE_INT    = 4;  // REG_DWORD
 104   const unsigned long TYPE_INT64  = 11; // REG_QWORD
 105
 106   /**
 107    * This attribute exposes the native HKEY and is available to provide C++
 108    * consumers with the flexibility of making other Windows registry API calls
 109    * that are not exposed via this interface.
 110    *
 111    * It is possible to initialize this object by setting an HKEY on it.  In
 112    * that case, it is the responsibility of the consumer setting the HKEY to
 113    * ensure that it is a valid HKEY.
 114    *
 115    * WARNING: Setting the key does not close the old key.
 116    */
 117   [noscript] attribute HKEY key;
 118
 119   /**
 120    * This method closes the key.  If the key is already closed, then this
 121    * method does nothing.
 122    */
 123   void close();
 124
 125   /**
 126    * This method opens an existing key.  This method fails if the key
 127    * does not exist.
 128    *
 129    * NOTE: On 32-bit Windows, it is valid to pass any HKEY as the rootKey
 130    * parameter of this function.  However, for compatibility with 64-bit
 131    * Windows, that usage should probably be avoided in favor of openChild.
 132    *
 133    * @param rootKey
 134    *        A root key defined above or any valid HKEY on 32-bit Windows.
 135    * @param relPath
 136    *        A relative path from the given root key.
 137    * @param mode
 138    *        Access mode, which is a bit-wise OR of the ACCESS_ values defined
 139    *        above.
 140    */
 141   void open(in unsigned long rootKey, in AString relPath, in unsigned long mode);
 142
 143   /**
 144    * This method opens an existing key or creates a new key.
 145    *
 146    * NOTE: On 32-bit Windows, it is valid to pass any HKEY as the rootKey
 147    * parameter of this function.  However, for compatibility with 64-bit
 148    * Windows, that usage should probably be avoided in favor of createChild.
 149    *
 150    * @param rootKey
 151    *        A root key defined above or any valid HKEY on 32-bit Windows.
 152    * @param relPath
 153    *        A relative path from the given root key.
 154    * @param mode
 155    *        Access mode, which is a bit-wise OR of the ACCESS_ values defined
 156    *        above.
 157    */
 158   void create(in unsigned long rootKey, in AString relPath, in unsigned long mode);
 159
 160   /**
 161    * This method opens a subkey relative to this key.  This method fails if the
 162    * key does not exist.
 163    *
 164    * @return nsIWindowsRegKey for the newly opened subkey.
 165    */
 166   nsIWindowsRegKey openChild(in AString relPath, in unsigned long mode);
 167
 168   /**
 169    * This method opens or creates a subkey relative to this key.
 170    *
 171    * @return nsIWindowsRegKey for the newly opened or created subkey.
 172    */
 173   nsIWindowsRegKey createChild(in AString relPath, in unsigned long mode);
 174
 175   /**
 176    * This attribute returns the number of child keys.
 177    */
 178   readonly attribute unsigned long childCount;
 179
 180   /**
 181    * This method returns the name of the n'th child key.
 182    *
 183    * @param index
 184    *        The index of the requested child key.
 185    */
 186   AString getChildName(in unsigned long index);
 187
 188   /**
 189    * This method checks to see if the key has a child by the given name.
 190    *
 191    * @param name
 192    *        The name of the requested child key.
 193    */
 194   boolean hasChild(in AString name);
 195
 196   /**
 197    * This attribute returns the number of values under this key.
 198    */
 199   readonly attribute unsigned long valueCount;
 200
 201   /**
 202    * This method returns the name of the n'th value under this key.
 203    *
 204    * @param index
 205    *        The index of the requested value.
 206    */
 207   AString getValueName(in unsigned long index);
 208
 209   /**
 210    * This method checks to see if the key has a value by the given name.
 211    *
 212    * @param name
 213    *        The name of the requested value.
 214    */
 215   boolean hasValue(in AString name);
 216
 217   /**
 218    * This method removes a child key and all of its values.  This method will
 219    * fail if the key has any children of its own.
 220    *
 221    * @param relPath
 222    *        The relative path from this key to the key to be removed.
 223    */
 224   void removeChild(in AString relPath);
 225
 226   /**
 227    * This method removes the value with the given name.
 228    *
 229    * @param name
 230    *        The name of the value to be removed.
 231    */
 232   void removeValue(in AString name);
 233
 234   /**
 235    * This method returns the type of the value with the given name.  The return
 236    * value is one of the "TYPE_" constants defined above.
 237    *
 238    * @param name
 239    *        The name of the value to query.
 240    */
 241   unsigned long getValueType(in AString name);
 242
 243   /**
 244    * This method reads the string contents of the named value as a Unicode
 245    * string.
 246    *
 247    * @param name
 248    *        The name of the value to query.  This parameter can be the empty
 249    *        string to request the key's default value.
 250    */
 251   AString readStringValue(in AString name);
 252
 253   /**
 254    * This method reads the integer contents of the named value.
 255    *
 256    * @param name
 257    *        The name of the value to query.
 258    */
 259   unsigned long readIntValue(in AString name);
 260
 261   /**
 262    * This method reads the 64-bit integer contents of the named value.
 263    *
 264    * @param name
 265    *        The name of the value to query.
 266    */
 267   unsigned long long readInt64Value(in AString name);
 268
 269   /**
 270    * This method reads the binary contents of the named value under this key.
 271    *
 272    * JavaScript callers should take care with the result of this method since
 273    * it will be byte-expanded to form a JS string.  (The binary data will be
 274    * treated as an ISO-Latin-1 character string, which it is not).
 275    *
 276    * @param name
 277    *        The name of the value to query.
 278    */
 279   ACString readBinaryValue(in AString name);
 280
 281   /**
 282    * This method writes the unicode string contents of the named value.  The
 283    * value will be created if it does not already exist.
 284    *
 285    * @param name
 286    *        The name of the value to modify.  This parameter can be the empty
 287    *        string to modify the key's default value.
 288    * @param data
 289    *        The data for the value to modify.
 290    */
 291   void writeStringValue(in AString name, in AString data);
 292
 293   /**
 294    * This method writes the integer contents of the named value.  The value
 295    * will be created if it does not already exist.
 296    *
 297    * @param name
 298    *        The name of the value to modify.
 299    * @param data
 300    *        The data for the value to modify.
 301    */
 302   void writeIntValue(in AString name, in unsigned long data);
 303
 304   /**
 305    * This method writes the 64-bit integer contents of the named value.  The
 306    * value will be created if it does not already exist.
 307    *
 308    * @param name
 309    *        The name of the value to modify.
 310    * @param data
 311    *        The data for the value to modify.
 312    */
 313   void writeInt64Value(in AString name, in unsigned long long data);
 314
 315   /**
 316    * This method writes the binary contents of the named value.  The value will
 317    * be created if it does not already exist.
 318    *
 319    * JavaScript callers should take care with the value passed to this method
 320    * since it will be truncated from a JS string (unicode) to a ISO-Latin-1
 321    * string.  (The binary data will be treated as an ISO-Latin-1 character
 322    * string, which it is not).  So, JavaScript callers should only pass
 323    * character values in the range \u0000 to \u00FF, or else data loss will
 324    * occur.
 325    *
 326    * @param name
 327    *        The name of the value to modify.
 328    * @param data
 329    *        The data for the value to modify.
 330    */
 331   void writeBinaryValue(in AString name, in ACString data);
 332
 333   /**
 334    * This method starts watching the key to see if any of its values have
 335    * changed.  The key must have been opened with mode including ACCESS_NOTIFY.
 336    * If recurse is true, then this key and any of its descendant keys are
 337    * watched.  Otherwise, only this key is watched.
 338    *
 339    * @param recurse
 340    *        Indicates whether or not to also watch child keys.
 341    */
 342   void startWatching(in boolean recurse);
 343
 344   /**
 345    * This method stops any watching of the key initiated by a call to
 346    * startWatching.  This method does nothing if the key is not being watched.
 347    */
 348   void stopWatching();
 349
 350   /**
 351    * This method returns true if the key is being watched for changes (i.e.,
 352    * if startWatching() was called).
 353    */
 354   boolean isWatching();
 355
 356   /**
 357    * This method returns true if the key has changed and false otherwise.
 358    * This method will always return false if startWatching was not called.
 359    */
 360   boolean hasChanged();
 361 };