35.3. "_winreg" --- Windows レジストリへのアクセス
**************************************************

注釈: "_winreg" モジュールは、Python 3 では "winreg" にリネームされ
  ました 。 *2to3* ツールが自動的にソースコードの import を修正します
  。

バージョン 2.0 で追加.

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

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

_winreg.CloseKey(hkey)

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

   注釈: このメソッドを使って (または "hkey.Close()" によって)
     *hkey* が閉 じられなかった場合、Python が *hkey* オブジェクトを破
     壊する際に閉 じられます。

_winreg.ConnectRegistry(computer_name, key)

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

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

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

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

_winreg.CreateKey(key, sub_key)

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

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

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

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

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

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

_winreg.CreateKeyEx(key, sub_key[, res[, sam]])

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

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

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

   *res* は予約された整数で、 0 でなくてはなりません。デフォルト値は 0
   です。

   *sam* は、 key に対して想定するセキュリティアクセスを示すアクセスマ
   スクを指定します。デフォルトは "KEY_ALL_ACCESS" です。利用可能な値
   については アクセス権 を参照してください。

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

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

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

バージョン 2.7 で追加.

_winreg.DeleteKey(key, sub_key)

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

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

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

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

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

_winreg.DeleteKeyEx(key, sub_key[, sam[, res]])

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

   注釈: The "DeleteKeyEx()" 関数は、RegDeleteKeyEx Windows API 関数
     で実装 されています。これは Windows の 64-bit バージョンに特有で
     す。 RegDeleteKeyEx documentation を参照してください。

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

   *sub_key* は *key* 引数によって指定された key の subkey でなければ
   なりません。この値は "None" であってはなりません。また、key は
   subkey を持たないかもしれません。

   *res* は予約された整数で、 0 でなくてはなりません。デフォルト値は 0
   です。

   *sam* は、 key に対して想定するセキュリティアクセスを示すアクセスマ
   スクを指定します。デフォルトは "KEY_WOW64_64KEY" です。利用可能な値
   については アクセス権 を参照してください。

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

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

   サポートされていない Windows バージョンでは、 "NotImplementedError"
   例外を発生させます。

バージョン 2.7 で追加.

_winreg.DeleteValue(key, value)

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

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

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

_winreg.EnumKey(key, index)

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

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

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

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

_winreg.EnumValue(key, index)

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

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

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

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

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

   +---------+----------------------------------------------+
   | インデ  | 意味                                         |
   | ックス  |                                              |
   +=========+==============================================+
   | "0"     | 値の名前を特定する文字列                     |
   +---------+----------------------------------------------+
   | "1"     | 値のデータを保持するためのオブジェクトで、そ |
   |         | の型は背後のレジストリ 型に依存します        |
   +---------+----------------------------------------------+
   | "2"     | 値のデータ型を特定する整数です               |
   |         | ("SetValueEx()" のドキュメント内のテ ーブル  |
   |         | を参照してください)                          |
   +---------+----------------------------------------------+

_winreg.ExpandEnvironmentStrings(unicode)

   "REG_EXPAND_SZ" のように、環境変数プレースホルダ "%NAME%" を
   Unicode 文字列で展開します:

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

   バージョン 2.6 で追加.

_winreg.FlushKey(key)

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

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

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

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

_winreg.LoadKey(key, sub_key, file_name)

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

   *key* は "ConnectRegistry()" が返したハンドルか、定数 "HKEY_USERS"
   と "HKEY_LOCAL_MACHINE" のどちらかです。

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

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

   この関数を呼び出しているプロセスが "SE_RESTORE_PRIVILEGE" 特権を持
   たない場合には "LoadKey()" は失敗します。この特権はファイル許可とは
   違うので注意してください - 詳細は RegLoadKey documentation を参照し
   てください。

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

_winreg.OpenKey(key, sub_key[, res[, sam]])

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

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

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

   *res* は予約されている整数値で、ゼロでなくてはなりません。デフォル
   トはゼロです。

   *sam* は必要なキーへのセキュリティアクセスを記述する、アクセスマス
   クを指定する整数です。標準の値は "KEY_READ" です。その他の利用でき
   る値については アクセス権限 を参照してください。

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

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

_winreg.OpenKeyEx()

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

_winreg.QueryInfoKey(key)

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

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

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

   +---------+-----------------------------------------------+
   | インデ  | 意味                                          |
   | ックス  |                                               |
   +=========+===============================================+
   | "0"     | 結果は以下の 3 要素からなるタプルです。       |
   +---------+-----------------------------------------------+
   | "1"     | このキーが持つサブキーの数を表す整数。        |
   +---------+-----------------------------------------------+
   | "2"     | 最後のキーの変更が (あれば) いつだったかを表  |
   |         | す長整数で、1601 年 1 月 1 日からの 100 ナノ  |
   |         | 秒単位で数えたもの。                          |
   +---------+-----------------------------------------------+

_winreg.QueryValue(key, sub_key)

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

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

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

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

_winreg.QueryValueEx(key, value_name)

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

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

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

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

   +---------+-------------------------------------------+
   | インデ  | 意味                                      |
   | ックス  |                                           |
   +=========+===========================================+
   | "0"     | レジストリ要素の値。                      |
   +---------+-------------------------------------------+
   | "1"     | この値のレジストリ型を表す整数。          |
   |         | ("SetValueEx()" のドキュメント内の テーブ |
   |         | ルを参照してください。)                   |
   +---------+-------------------------------------------+

_winreg.SaveKey(key, file_name)

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

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

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

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

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

_winreg.SetValue(key, sub_key, type, value)

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

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

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

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

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

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

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

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

_winreg.SetValueEx(key, value_name, reserved, type, value)

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

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

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

   *type* はデータの型を指定する整数です。利用できる型については 値の
   型 を参照してください。

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

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

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

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

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

_winreg.DisableReflectionKey(key)

   64ビット OS上で動作している 32bit プロセスに対するレジストリリフレ
   クションを無効にします。

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

   32bit OS上では一般的に "NotImplemented" 例外を発生させます。

   key がリフレクションリストに無い場合は、この関数は成功しますが効果
   はありません。あるキーのリフレクションを無効にしても、その全てのサ
   ブキーのリフレクションには影響しません。

_winreg.EnableReflectionKey(key)

   指定された、リフレクションが無効にされたキーのリフレクションを再び
   有効にします。

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

   32bit OS上では一般的に "NotImplemented" 例外を発生させます。

   あるキーのリフレクションを再開しても、その全てのサブキーには影響し
   ません。

_winreg.QueryReflectionKey(key)

   指定されたキーのリフレクション状態を確認します。

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

   リフレクションが無効になっている場合、"True" を返します。

   32bit OS上では一般的に "NotImplemented" 例外を発生させます。


35.3.1. 定数
============

"_winreg" の多くの関数で利用するために以下の定数が定義されています。


35.3.1.1. HKEY_* 定数
---------------------

_winreg.HKEY_CLASSES_ROOT

   このキー以下のレジストリエントリは、ドキュメントのタイプ（またはク
   ラス）や、それに関連付けられたプロパティを定義しています。シェルと
   COM アプリケーションがこの情報を利用します。

_winreg.HKEY_CURRENT_USER

   このキー以下のレジストリエントリは、現在のユーザーの設定を定義しま
   す。この設定には、環境変数、プログラムグループに関するデータ、カラ
   ー、プリンター、ネットワーク接続、アプリケーション設定などが含まれ
   ます。

_winreg.HKEY_LOCAL_MACHINE

   このキー以下のレジストリエントリは、コンピュータの物理的な状態を定
   義します。これには、バスタイプ、システムメモリ、インストールされて
   いるソフトウェアやハードウェアが含まれます。

_winreg.HKEY_USERS

   このキー以下のレジストリエントリは、ローカルコンピュータの新規ユー
   ザーのためのデフォルト設定や、現在のユーザーの設定を定義しています
   。

_winreg.HKEY_PERFORMANCE_DATA

   このキー以下のレジストリエントリは、パフォーマンスデータへのアクセ
   スを可能にしています。実際にはデータはレジストリには格納されていま
   せん。レジストリ関数がシステムにソースからデータを集めさせます。

_winreg.HKEY_CURRENT_CONFIG

   ローカルコンピュータシステムの現在のハードウェアプロファイルに関す
   る情報を含みます。

_winreg.HKEY_DYN_DATA

   このキーは Windows の 98 以降のバージョンでは利用されていません。


35.3.1.2. アクセス権限
----------------------

より詳しい情報については、Registry Key Security and Access を参照して
ください。

_winreg.KEY_ALL_ACCESS

   STANDARD_RIGHTS_REQUIRED ("KEY_QUERY_VALUE", "KEY_SET_VALUE",
   "KEY_CREATE_SUB_KEY", "KEY_ENUMERATE_SUB_KEYS", "KEY_NOTIFY",
   "KEY_CREATE_LINK") アクセス権限の組み合わせ。

_winreg.KEY_WRITE

   STANDARD_RIGHTS_WRITE ("KEY_SET_VALUE", "KEY_CREATE_SUB_KEY") アク
   セス権限の組み合わせ。

_winreg.KEY_READ

   STANDARD_RIGHTS_READ ("KEY_QUERY_VALUE", "KEY_ENUMERATE_SUB_KEYS",
   "KEY_NOTIFY") アクセス権限の組み合わせ。

_winreg.KEY_EXECUTE

   "KEY_READ" と同じ。

_winreg.KEY_QUERY_VALUE

   レジストリキーの値を問い合わせるのに必要。

_winreg.KEY_SET_VALUE

   レジストリの値を作成、削除、設定するのに必要。

_winreg.KEY_CREATE_SUB_KEY

   レジストリキーのサブキーを作るのに必要。

_winreg.KEY_ENUMERATE_SUB_KEYS

   レジストリキーのサブキーを列挙するのに必要。

_winreg.KEY_NOTIFY

   レジストリキーやそのサブキーに対する変更通知を要求するのに必要。

_winreg.KEY_CREATE_LINK

   システムでの利用のために予約されている。


35.3.1.2.1. 64-bit 特有のアクセス権
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

より詳しい情報については、Accessing an Alternate Registry View を参照
してください。

_winreg.KEY_WOW64_64KEY

   64 bit Windows 上のアプリケーションが、64 bit のレジストリビュー上
   で操作する事を示します。

_winreg.KEY_WOW64_32KEY

   64 bit Windows 上のアプリケーションが、32 bit のレジストリビュー上
   で操作する事を示します。


35.3.1.3. 値の型
----------------

より詳しい情報は、Registry Value Types を参照してください。

_winreg.REG_BINARY

   何らかの形式のバイナリデータ。

_winreg.REG_DWORD

   32 ビットの数。

_winreg.REG_DWORD_LITTLE_ENDIAN

   32 ビットのリトルエンディアン形式の数。

_winreg.REG_DWORD_BIG_ENDIAN

   32 ビットのビッグエンディアン形式の数。

_winreg.REG_EXPAND_SZ

   環境変数を参照している、ヌル文字で終端された文字列。("%PATH%")。

_winreg.REG_LINK

   Unicode のシンボリックリンク。

_winreg.REG_MULTI_SZ

   ヌル文字で終端された文字列からなり、二つのヌル文字で終端されている
   配列。 (Python はこの終端の処理を自動的に行います。)

_winreg.REG_NONE

   定義されていない値の形式。

_winreg.REG_RESOURCE_LIST

   デバイスドライバリソースのリスト。

_winreg.REG_FULL_RESOURCE_DESCRIPTOR

   ハードウェアセッティング。

_winreg.REG_RESOURCE_REQUIREMENTS_LIST

   ハードウェアリソースリスト。

_winreg.REG_SZ

   ヌル文字で終端された文字列。


35.3.2. レジストリハンドルオブジェクト
======================================

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

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

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

ハンドルオブジェクトは "__nonzero__()" のセマンティクスを持ちます - す
なわち

   if handle:
       print "Yes"

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

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

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

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

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

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

PyHKEY.__enter__()
PyHKEY.__exit__(*exc_info)

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

      with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
          ...  # work with key

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

   バージョン 2.6 で追加.
