:mod:`_winreg` -- Windows レジストリへのアクセス
================================================

.. module:: _winreg
   :platform: Windows
   :synopsis: Windows レジストリを操作するためのルーチンおよびオブジェクト。
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>

.. note::
   :mod:`_winreg` モジュールは Python 3.0 では :mod:`winreg` にリネームされました。
   ソースコードを3.0用に変換するときは、 :term:`2to3` ツールが自動的に import を修正します。


.. versionadded:: 2.0

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

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

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


.. function:: CloseKey(hkey)

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

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


.. function:: ConnectRegistry(computer_name, key)

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

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

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

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


.. function:: CreateKey(key, sub_key)

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

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

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

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

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

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


.. function:: DeleteKey(key, sub_key)

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

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

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

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

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


.. function:: DeleteValue(key, value)

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

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

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


.. function:: EnumKey(key, index)

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

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

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

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


.. function:: EnumValue(key, index)

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

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

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

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

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

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


.. function:: ExpandEnvironmentStrings(unicode)

   const:`REG_EXPAND_SZ` のような、%NAME% を環境変数で置き換えます。 ::

      >>> ExpandEnvironmentStrings(u"%windir%")
      u"C:\\Windows"

   .. versionadded:: 2.6


.. function:: FlushKey(key)

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

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

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

   .. note::

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


.. function:: LoadKey(key, sub_key, file_name)

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

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

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

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

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

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

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


.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])

   指定されたキーを開き、 :dfn:`handle object` を返します。

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

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

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

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

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

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


.. function:: OpenKeyEx()

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


.. function:: QueryInfoKey(key)

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

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

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

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


.. function:: QueryValue(key, sub_key)

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

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

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

   レジストリ中の値は名前、型、およびデータから構成されています。
   このメソッドはあるキーのデータ中で、名前 NULL をもつ最初の値を取得します。
   しかし背後のAPI 呼び出しは型情報を返しません。
   なので、可能ならいつでも :func:`QueryValueEx` を使うべきです。


.. function:: QueryValueEx(key, value_name)

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

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

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

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

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


.. function:: SaveKey(key, file_name)

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

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

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

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

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


.. function:: SetValue(key, sub_key, type, value)

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

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

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

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

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

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

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

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


.. function:: SetValueEx(key, value_name, reserved, type, value)

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

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

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

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

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

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

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

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

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

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


.. _handle-object:

レジストリハンドルオブジェクト
------------------------------

このオブジェクトは Windows の HKEY オブジェクトをラップし、オブジェクトが破壊されたときに自動的にハンドルを閉じます。オブジェクトの
:meth:`Close` メソッドと :func:`CloseKey` 関数のどちらも、後始末がきちんと行われることを保証するために呼び出す
ことができます。

このモジュールのレジストリ関数は全て、これらのハンドルオブジェクトの一つを返します。

このモジュールのレジストリ関数でハンドルオブジェクトを受理するものは全て整数も受理しますが、ハンドルオブジェクトを利用することを推奨します。

ハンドルオブジェクトは :meth:`__nonzero__` の意味構成を持ちます - すなわち、  ::

   if handle:
       print "Yes"

は、ハンドルが現在有効な (閉じられたり切り離されたりしていない) 場合には ``Yes`` となります。

ハンドルオブジェクトはまた、比較の意味構成もサポートしています。このため、背後の Windows ハンドル値が同じものを複数のハンドルオブジェクト
が参照している場合、それらの比較は真になります。

ハンドルオブジェクトは (例えば組み込みの :func:`int` 関数を使って) 整数に変換することができます。この場合、背後の Windows
ハンドル値が返されます、また、 :meth:`Detach` メソッドを使って整数のハンドル値を返させると同時に、ハンドルオブジェクトから Windows
ハンドルを切り離すこともできます。


.. method:: PyHKEY.Close()

   背後の Windows ハンドルを閉じます。

   ハンドルがすでに閉じられていてもエラーは送出されません。


.. method:: PyHKEY.Detach()

   ハンドルオブジェクトから Windows ハンドルを切り離します。

   切り離される以前にそのハンドルを保持していた整数 (または 64 ビット  Windows の場合には長整数) オブジェクトが返されます。
   ハンドルがすでに切り離されていたり閉じられていたりした場合、ゼロが返されます。

   この関数を呼び出した後、ハンドルは確実に無効化されますが、閉じられるわけではありません。背後の Win32 ハンドルがハンドル
   オブジェクトよりも長く維持される必要がある場合にはこの関数を呼び出すとよいでしょう。

.. method:: PyHKEY.__enter__()
            PyHKEY.__exit__(\*exc_info)

   HKEY オブジェクトは :meth:`__enter__`, :meth:`__exit__` メソッドを実装していて、
   :keyword:`with` 文のためのコンテキストプロトコルをサポートしています。 ::

      with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
          # ... key を使った処理 ...

   このコードは、 :keyword:`with` ブロックから抜けるときに自動的に *key* を閉じます。

   .. versionadded:: 2.6

