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 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 %{C++
  10 #include <windows.h>
  11 %}
  12
  13 native HKEY(HKEY);
  14
  15 /**
  16  * This interface is designed to provide scriptable access to the Windows
  17  * registry system ("With Great Power Comes Great Responsibility").  The
  18  * interface represents a single key in the registry.
  19  *
  20  * This interface is highly Win32 specific.
  21  */
  22 [scriptable, uuid(2555b930-d64f-437e-9be7-0a2cb252c1f4)]
  23 interface nsIWindowsRegKey : nsISupports
  24 {
  25   /**
  26    * Root keys.  The values for these keys correspond to the values from
  27    * WinReg.h in the MS Platform SDK.  The ROOT_KEY_ prefix corresponds to the
  28    * HKEY_ prefix in the MS Platform SDK.
  29    *
  30    * This interface is not restricted to using only these root keys.
  31    */
  32   const unsigned long ROOT_KEY_CLASSES_ROOT     = 0x80000000;
  33   const unsigned long ROOT_KEY_CURRENT_USER     = 0x80000001;
  34   const unsigned long ROOT_KEY_LOCAL_MACHINE    = 0x80000002;
  35
  36   /**
  37    * Values for the mode parameter passed to the open and create methods.
  38    * The values defined here correspond to the REGSAM values defined in
  39    * WinNT.h in the MS Platform SDK, where ACCESS_ is replaced with KEY_.
  40    *
  41    * This interface is not restricted to using only these access types.
  42    */
  43   const unsigned long ACCESS_BASIC              = 0x00020000;
  44   const unsigned long ACCESS_QUERY_VALUE        = 0x00000001;
  45   const unsigned long ACCESS_SET_VALUE          = 0x00000002;
  46   const unsigned long ACCESS_CREATE_SUB_KEY     = 0x00000004;
  47   const unsigned long ACCESS_ENUMERATE_SUB_KEYS = 0x00000008;
  48   const unsigned long ACCESS_NOTIFY             = 0x00000010;
  49   const unsigned long ACCESS_READ               = ACCESS_BASIC |
  50                                                   ACCESS_QUERY_VALUE |
  51                                                   ACCESS_ENUMERATE_SUB_KEYS |
  52                                                   ACCESS_NOTIFY;
  53   const unsigned long ACCESS_WRITE              = ACCESS_BASIC |
  54                                                   ACCESS_SET_VALUE |
  55                                                   ACCESS_CREATE_SUB_KEY;
  56   const unsigned long ACCESS_ALL                = ACCESS_READ |
  57                                                   ACCESS_WRITE;
  58   const unsigned long WOW64_32                  = 0x00000200;
  59   const unsigned long WOW64_64                  = 0x00000100;
  60
  61
  62   /**
  63    * Values for the type of a registry value.  The numeric values of these
  64    * constants are taken directly from WinNT.h in the MS Platform SDK.
  65    * The Microsoft documentation should be consulted for the exact meaning of
  66    * these value types.
  67    *
  68    * This interface is somewhat restricted to using only these value types.
  69    * There is no method that is directly equivalent to RegQueryValueEx or
  70    * RegSetValueEx.  In particular, this interface does not support the
  71    * REG_MULTI_SZ and REG_EXPAND_SZ value types.  It is still possible to
  72    * enumerate values that have other types (i.e., getValueType may return a
  73    * type not defined below).
  74    */
  75   const unsigned long TYPE_NONE   = 0;  // REG_NONE
  76   const unsigned long TYPE_STRING = 1;  // REG_SZ
  77   const unsigned long TYPE_BINARY = 3;  // REG_BINARY
  78   const unsigned long TYPE_INT    = 4;  // REG_DWORD
  79   const unsigned long TYPE_INT64  = 11; // REG_QWORD
  80
  81   /**
  82    * This method closes the key.  If the key is already closed, then this
  83    * method does nothing.
  84    */
  85   void close();
  86
  87   /**
  88    * This method opens an existing key.  This method fails if the key
  89    * does not exist.
  90    *
  91    * NOTE: On 32-bit Windows, it is valid to pass any HKEY as the rootKey
  92    * parameter of this function.  However, for compatibility with 64-bit
  93    * Windows, that usage should probably be avoided in favor of openChild.
  94    *
  95    * @param rootKey
  96    *        A root key defined above or any valid HKEY on 32-bit Windows.
  97    * @param relPath
  98    *        A relative path from the given root key.
  99    * @param mode
 100    *        Access mode, which is a bit-wise OR of the ACCESS_ values defined
 101    *        above.
 102    */
 103   void open(in unsigned long rootKey, in AString relPath, in unsigned long mode);
 104
 105   /**
 106    * This method opens an existing key or creates a new key.
 107    *
 108    * NOTE: On 32-bit Windows, it is valid to pass any HKEY as the rootKey
 109    * parameter of this function.  However, for compatibility with 64-bit
 110    * Windows, that usage should probably be avoided in favor of createChild.
 111    *
 112    * @param rootKey
 113    *        A root key defined above or any valid HKEY on 32-bit Windows.
 114    * @param relPath
 115    *        A relative path from the given root key.
 116    * @param mode
 117    *        Access mode, which is a bit-wise OR of the ACCESS_ values defined
 118    *        above.
 119    */
 120   void create(in unsigned long rootKey, in AString relPath, in unsigned long mode);
 121
 122   /**
 123    * This method opens a subkey relative to this key.  This method fails if the
 124    * key does not exist.
 125    *
 126    * @return nsIWindowsRegKey for the newly opened subkey.
 127    */
 128   nsIWindowsRegKey openChild(in AString relPath, in unsigned long mode);
 129
 130   /**
 131    * This method opens or creates a subkey relative to this key.
 132    *
 133    * @return nsIWindowsRegKey for the newly opened or created subkey.
 134    */
 135   nsIWindowsRegKey createChild(in AString relPath, in unsigned long mode);
 136
 137   /**
 138    * This attribute returns the number of child keys.
 139    */
 140   readonly attribute unsigned long childCount;
 141
 142   /**
 143    * This method returns the name of the n'th child key.
 144    *
 145    * @param index
 146    *        The index of the requested child key.
 147    */
 148   AString getChildName(in unsigned long index);
 149
 150   /**
 151    * This method checks to see if the key has a child by the given name.
 152    *
 153    * @param name
 154    *        The name of the requested child key.
 155    */
 156   boolean hasChild(in AString name);
 157
 158   /**
 159    * This attribute returns the number of values under this key.
 160    */
 161   readonly attribute unsigned long valueCount;
 162
 163   /**
 164    * This method returns the name of the n'th value under this key.
 165    *
 166    * @param index
 167    *        The index of the requested value.
 168    */
 169   AString getValueName(in unsigned long index);
 170
 171   /**
 172    * This method checks to see if the key has a value by the given name.
 173    *
 174    * @param name
 175    *        The name of the requested value.
 176    */
 177   boolean hasValue(in AString name);
 178
 179   /**
 180    * This method removes a child key and all of its values.  This method will
 181    * fail if the key has any children of its own.
 182    *
 183    * @param relPath
 184    *        The relative path from this key to the key to be removed.
 185    */
 186   void removeChild(in AString relPath);
 187
 188   /**
 189    * This method removes the value with the given name.
 190    *
 191    * @param name
 192    *        The name of the value to be removed.
 193    */
 194   void removeValue(in AString name);
 195
 196   /**
 197    * This method returns the type of the value with the given name.  The return
 198    * value is one of the "TYPE_" constants defined above.
 199    *
 200    * @param name
 201    *        The name of the value to query.
 202    */
 203   unsigned long getValueType(in AString name);
 204
 205   /**
 206    * This method reads the string contents of the named value as a Unicode
 207    * string.
 208    *
 209    * @param name
 210    *        The name of the value to query.  This parameter can be the empty
 211    *        string to request the key's default value.
 212    */
 213   AString readStringValue(in AString name);
 214
 215   /**
 216    * This method reads the integer contents of the named value.
 217    *
 218    * @param name
 219    *        The name of the value to query.
 220    */
 221   unsigned long readIntValue(in AString name);
 222
 223   /**
 224    * This method reads the 64-bit integer contents of the named value.
 225    *
 226    * @param name
 227    *        The name of the value to query.
 228    */
 229   unsigned long long readInt64Value(in AString name);
 230
 231   /**
 232    * This method reads the binary contents of the named value under this key.
 233    *
 234    * JavaScript callers should take care with the result of this method since
 235    * it will be byte-expanded to form a JS string.  (The binary data will be
 236    * treated as an ISO-Latin-1 character string, which it is not).
 237    *
 238    * @param name
 239    *        The name of the value to query.
 240    */
 241   ACString readBinaryValue(in AString name);
 242
 243   /**
 244    * This method writes the unicode string contents of the named value.  The
 245    * value will be created if it does not already exist.
 246    *
 247    * @param name
 248    *        The name of the value to modify.  This parameter can be the empty
 249    *        string to modify the key's default value.
 250    * @param data
 251    *        The data for the value to modify.
 252    */
 253   void writeStringValue(in AString name, in AString data);
 254
 255   /**
 256    * This method writes the integer contents of the named value.  The value
 257    * will be created if it does not already exist.
 258    *
 259    * @param name
 260    *        The name of the value to modify.
 261    * @param data
 262    *        The data for the value to modify.
 263    */
 264   void writeIntValue(in AString name, in unsigned long data);
 265
 266   /**
 267    * This method writes the 64-bit integer contents of the named value.  The
 268    * value will be created if it does not already exist.
 269    *
 270    * @param name
 271    *        The name of the value to modify.
 272    * @param data
 273    *        The data for the value to modify.
 274    */
 275   void writeInt64Value(in AString name, in unsigned long long data);
 276
 277   /**
 278    * This method writes the binary contents of the named value.  The value will
 279    * be created if it does not already exist.
 280    *
 281    * JavaScript callers should take care with the value passed to this method
 282    * since it will be truncated from a JS string (unicode) to a ISO-Latin-1
 283    * string.  (The binary data will be treated as an ISO-Latin-1 character
 284    * string, which it is not).  So, JavaScript callers should only pass
 285    * character values in the range \u0000 to \u00FF, or else data loss will
 286    * occur.
 287    *
 288    * @param name
 289    *        The name of the value to modify.
 290    * @param data
 291    *        The data for the value to modify.
 292    */
 293   void writeBinaryValue(in AString name, in ACString data);
 294 };