# 22.2 `_winreg` - Windows レジストリへのアクセス

利用可能な条件: Windows.

バージョン2.0 以降で新規追加された 仕様です。

これらの関数は Windows レジストリ API を Python で使えるようにします。 プログラマがレジストリハンドルのクローズを失念した場合でも、確実に ハンドルがクローズされるようにするために、整数値をレジストリハンドル として使う代わりにハンドルオブジェクトが使われます。

このモジュールは Windows レジストリ操作のための非常に低レベルの インタフェースを使えるようにします; 将来、より高レベルの レジストリ API インタフェースを提供するような、新たな `winreg` モジュールが作られるよう期待します。

このモジュールでは以下の関数を提供します:

`CloseKey`( | hkey)

  以前開かれたレジストリキーを閉じます。 hkey 引数には以前開かれたレジストリキーを特定します。

  このメソッド (または `handle.Close()`) を使って hkey が 閉じられなかった場合、Python が hkey オブジェクトを破壊 する際に閉じられるので注意してください。

`ConnectRegistry`( | computer_name, key)

  他の計算機上にある既定のレジストリハンドル接続を確立し、 ハンドルオブジェクト (handle object) を返します。

  computer_name はリモートコンピュータの名前で、 `r"\\computername"` の形式をとります。`None` の場合、ローカルの計算機が使われます。

  key は接続したい既定のハンドルです。

  戻り値は開かれたキーのハンドルです。 関数が失敗した場合、`EnvironmentError` 例外が 送出されます。

`CreateKey`( | key, sub_key)

  特定のキーを生成するか開き、ハンドルオブジェクト を返します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数の うちの一つです。

  sub_key はこのメソッドが開く、または新規作成するキーの 名前です。

  key が既定のキーの一つなら、sub_key は `None` でかまいません。この場合、返されるハンドルは関数に渡されたのと 同じキーハンドルです。

  キーがすでに存在する場合、この関数は既に存在するキーを開きます。

  戻り値は開かれたキーのハンドルです。この関数が失敗した場合、 `EnvironmentError` 例外が送出されます。

`DeleteKey`( | key, sub_key)

  特定のキーを削除します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  sub_key は文字列で、key パラメタによって特定された キーのサブキーでなければなりません。この値は `None` で あってはならず、キーはサブキーを持っていてはなりません。

  このメソッドはサブキーをもつキーを削除することはできません。

  このメソッドの実行が成功すると、キー全体が、その値すべてを含めて 削除されます。このメソッドが失敗した場合、 `EnvironmentError` 例外が送出されます。

`DeleteValue`( | key, value)

  レジストリキーから指定された名前つきの値を削除します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つでなければなりません。

  value は削除したい値を指定するための文字列です。

`EnumKey`( | key, index)

  開かれているレジストリキーのサブキーを列挙し、文字列で返します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つでなければなりません。

  index は整数値で、取得するキーのインデクスを特定します。

  この関数は呼び出されるたびに一つのサブキーの名前を取得します。 この関数は通常、これ以上サブキーがないことを示す `EnvironmentError` 例外が送出されるまで繰り返し呼び 出されます。

`EnumValue`( | key, index)

  開かれているレジストリキーの値を列挙し、タプルで返します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つでなければなりません。

  index は整数値で、取得する値のインデクスを特定します。

  この関数は呼び出されるたびに一つの値の名前を取得します。 この関数は通常、これ以上値がないことを示す `EnvironmentError` 例外が送出されるまで繰り返し呼び 出されます。

  結果は 3 要素のタプルになります:

  Index | Meaning
  --- | ---
  `0` | 値の名前を特定する文字列
  `1` | 値のデータを保持するためのオブジェクトで、その型は背後の レジストリ型に依存します
  `2` | 値のデータ型を特定する整数です

`FlushKey`( | key)

  キーのすべての属性をレジストリに書き込みます。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つでなければなりません。

  キーを変更するために RegFlushKey を呼ぶ必要はありません。 レジストリの変更は怠惰なフラッシュ機構 (lazy flusher) を使って フラッシュされます。また、システムの遮断時にもディスクにフラッシュ されます。`CloseKey()` と違って、`FlushKey()` メソッドはレジストリに全てのデータを書き終えたときにのみ返ります。 アプリケーションは、レジストリへの変更を絶対に確実にディスク上に 反映させる必要がある場合にのみ、`FlushKey()` を呼ぶべきです。

  `FlushKey()` を呼び出す必要があるかどうか分からない場合、 おそらくその必要はありません。

`RegLoadKey`( | key, sub_key, file_name)

  指定されたキーの下にサブキーを生成し、サブキーに指定されたファイル のレジストリ情報を記録します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  sub_key は記録先のサブキーを指定する文字列です。

  file_name はレジストリデータを読み出すためのファイル名です。 このファイルは `SaveKey()` 関数で生成されたファイルでなくては なりません。ファイル割り当てテーブル (FAT) ファイルシステム下では、 ファイル名は拡張子を持っていてはなりません。

  この関数を呼び出しているプロセスが `SE_RESTORE_PRIVILEGE` 特権を持たない場合には LoadKey() は失敗します。 この特権はファイル許可とは違うので注意してください - 詳細は Win32 ドキュメンテーションを参照してください。

  key が `ConnectRegistry()` によって返されたハンドル の場合、fileName に指定されたパスは遠隔計算機に対する相対パス 名になります。

  Win32 ドキュメンテーションでは、key は `HKEY_USER` または `HKEY_LOCAL_MACHINE` ツリー内になければならない とされています。これは正しいかもしれないし、そうでないかもしれません。

`OpenKey`( | key, sub_key[, res`= 0`][, sam`= `KEY_READ``])

  指定されたキーを開き、ハンドルオブジェクト を返します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  sub_key は開きたいサブキーを特定する文字列です。

  res 予約されている整数値で、ゼロでなくてはなりません。 標準の値はゼロです。

  sam は必要なキーへのセキュリティアクセスを記述する、 アクセスマスクを指定する整数です。標準の値は `KEY_READ` です。

  指定されたキーへの新しいハンドルが返されます。

  この関数が失敗すると 、`EnvironmentError` が送出されます。

`OpenKeyEx`( | )

  `OpenKeyEx()` の機能は `OpenKey()` を標準の引数で使うことで提供されています。

`QueryInfoKey`( | key)

  キーに関数情報をタプルとして返します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  結果は以下の 3 要素からなるタプルです:

  インデクス | 意味
  --- | ---
  `0` | このキーが持つサブキーの数を表す整数。
  `1` | このキーが持つ値の数を表す整数。
  `2` | 最後のキーの変更が (あれば) いつだったかを表す長整数で、 1600 年 1 月 1 日からの 100 ナノ秒単位で数えたもの。

`QueryValue`( | key, sub_key)

  キーに対する、名前付けられていない値を文字列で取得します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  sub_key は値が関連付けられているサブキーの名前を保持する文字列 です。この引数が `None` または空文字列の場合、この関数は key で特定されるキーに対して `SetValue()` メソッドで 設定された値を取得します。

  レジストリ中の値は名前、型、およびデータから構成されています。 このメソッドはあるキーのデータ中で、名前 NULL をもつ最初の値を取得します。 しかし背後の API 呼び出しは型情報を返しません。非常に、非常に、非常に 不完全な実装です。この関数を使うべきではありません！！！

`QueryValueEx`( | key, value_name)

  開かれたレジストリキーに関連付けられている、指定した名前の値に対して、 型およびデータを取得します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  value_name は要求する値を指定する文字列です。

  結果は 2 つの要素からなるタプルです:

  インデクス | 意味
  --- | ---
  `0` | レジストリ要素の名前。
  `1` | この値のレジストリ型を表す整数。

`SaveKey`( | key, file_name)

  指定されたキーと、そのサブキー全てを指定したファイルに保存します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  file_name はレジストリデータを保存するファイルの名前です、 このファイルはすでに存在していてはいけません。このファイル名が 拡張子を含んでいる場合、`LoadKey()`、 `ReplaceKey()` または `RestoreKey()` メソッドは、ファイル割り当てテーブル (FAT) 型ファイルシステムを使うことができません。

  key が遠隔の計算機上にあるキーを表す場合、file_name で記述されているパスは遠隔の計算機に対して相対的なパスになります。 このメソッドの呼び出し側は `SeBackupPrivilege` セキュリティ特権を保有していなければなりません。この特権は ファイルパーミッションとは異なります - 詳細は Win32 ドキュメンテーションを参照してください。

  この関数は security_attributes を NULL にして API に渡します。

`SetValue`( | key, sub_key, type, value)

  値を指定したキーに関連付けます。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  sub_key は値が関連付けられているサブキーの名前を表す文字列です。

  type はデータの型を指定する整数です。現状では、この値は `REG_SZ` でなければならず、これは文字列だけが サポートされていることを示します。他のデータ型をサポートするには `SetValueEx()` を使ってください。

  value は新たな値を指定する文字列です。

  sub_key 引数で指定されたキーが存在しなければ、 SetValue 関数で生成されます。

  値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存 するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

  key 引数に指定されたキーは `KEY_SET_VALUE` アクセスで開かれていなければなりません。

`SetValueEx`( | key, value_name, reserved, type, value)

  開かれたレジストリキーの値フィールドにデータを記録します。

  key はすでに開かれたキーか、既定の `HKEY_*` 定数 のうちの一つです。

  sub_key は値が関連付けられているサブキーの名前を表す文字列です。

  type はデータの型を指定する整数です。 値はこのモジュールで定義されている以下の定数のうちの一つでなければ なりません:

  定数 | 意味
  --- | ---
  `REG_BINARY` | 何らかの形式のバイナリデータ。
  `REG_DWORD` | 32 ビットの数。
  `REG_DWORD_LITTLE_ENDIAN` | 32 ビットのリトルエンディアン形式の数。
  `REG_DWORD_BIG_ENDIAN` | 32 ビットのビッグエンディアン形式の数。
  `REG_EXPAND_SZ` | 環境変数を参照している、ヌル文字で終端された文字列。 ("`%PATH%`")。
  `REG_LINK` | Unicode のシンボリックリンク。
  `REG_MULTI_SZ` | ヌル文字で終端された文字列からなり、二つのヌル文字で終端されている配列 (Python はこの終端の処理を自動的に行います)。
  `REG_NONE` | 定義されていない値の形式。
  `REG_RESOURCE_LIST` | デバイスドライバリソースのリスト。
  `REG_SZ` | ヌルで終端された文字列。

  reserved は何もしません - API には常にゼロが渡されます。

  value は新たな値を指定する文字列です。

  このメソッドではまた、指定されたキーに対して、さらに別の値や型情報を 設定することができます。key 引数で指定されたキーは `KEY_SET_VALUE` アクセスで開かれていなければなりません。

  キーを開くには、 `CreateKeyEx()` または `OpenKey()` メソッドを使ってください。

  値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存 するべきです。そうすればレジストリを効率的に動作させる役に立ちます。