RegEnumValueA 関数 (winreg.h)

指定した開いているレジストリ キーの値を列挙します。 関数は、キーが呼び出されるたびに、キーのインデックス付き値名とデータ ブロックを 1 つコピーします。

構文

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   lpValueName,
  [in, out]           LPDWORD lpcchValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

パラメーター

[in] hKey

開いているレジストリ キーへのハンドル。 キーは、KEY_QUERY_VALUEアクセス権で開かれている必要があります。 詳細については、「 レジストリ キーのセキュリティとアクセス権」を参照してください。

このハンドルは、 RegCreateKeyEx、 RegCreateKeyTransacted、 RegOpenKeyEx、または RegOpenKeyTransacted 関数によって返されます。 また、次の 定義済みキーのいずれかを指定することもできます。

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

取得する値のインデックス。 このパラメーターは、 RegEnumValue 関数の最初の呼び出しでは 0 にしてから、後続の呼び出しに対してインクリメントする必要があります。

値は順序付けされないため、新しい値には任意のインデックスがあります。 これは、関数が任意の順序で値を返す可能性があることを意味します。

[out] lpValueName

値の名前を null で終わる文字列として受け取るバッファーへのポインター。

このバッファーは、終端 の null 文字を含めるのに十分な大きさにする必要があります。

詳細については、「 レジストリ要素のサイズ制限」を参照してください。

[in, out] lpcchValueName

lpValueName パラメーターによって指されるバッファーのサイズを文字で指定する変数へのポインター。 関数が戻ると、変数はバッファーに格納されている文字数を受け取りますが、終端の null 文字は含まれません。

lpValueName で指定されたバッファーがデータを保持するのに十分な大きさでない場合、関数は ERROR_MORE_DATAを返し、lpValueName が指す変数のバッファー サイズは変更されません。 この場合、 lpcchValueName の内容は未定義です。

レジストリ値の名前は 32,767 バイトに制限されています。 この関数の ANSI バージョンでは、このパラメーターは SHORT 値として扱われます。 したがって、32,767 バイトを超える値を指定すると、オーバーフローが発生し、関数はERROR_MORE_DATAを返す可能性があります。

lpReserved

このパラメーターは予約済みであり、 NULL である必要があります。

[out, optional] lpType

指定した値に格納されているデータの種類を示すコードを受け取る変数へのポインター。 使用可能な型コードの一覧については、「 レジストリ値の型」を参照してください。 型コードが不要な場合、 lpType パラメーターは NULL にすることができます。

[out, optional] lpData

値エントリのデータを受け取るバッファーへのポインター。 データが不要な場合、このパラメーターは NULL にすることができます。

lpData が NULL で、lpcbData が NULL 以外の場合、関数はデータのサイズをバイト単位で lpcbData が指す変数に格納します。 これにより、アプリケーションはデータのバッファーを割り当てる最適な方法を決定できます。

[in, out, optional] lpcbData

lpData パラメーターによって指されるバッファーのサイズをバイト単位で指定する変数へのポインター。 関数が戻ると、変数はバッファーに格納されているバイト数を受け取ります。

このパラメーターは、lpData が NULL の場合にのみ NULL にすることができます。

データにREG_SZ、REG_MULTI_SZ、またはREG_EXPAND_SZの型がある場合、このサイズには終端 の null 文字または文字が含まれます。 詳細については、「解説」を参照してください。

lpData で指定されたバッファーがデータを保持するのに十分な大きさでない場合、関数は ERROR_MORE_DATAを返し、lpcbData が指す変数に必要なバッファー サイズを格納します。 この場合、 lpData の内容は未定義です。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は システム エラー コードです。 使用可能な値がこれ以上ない場合、関数はERROR_NO_MORE_ITEMSを返します。

lpValueName または lpData で指定されたバッファーが小さすぎて値を受け取れない場合、関数はERROR_MORE_DATAを返します。

解説

値を列挙するには、アプリケーションは最初に、dwIndex パラメーターを 0 に設定して RegEnumValue 関数を呼び出す必要があります。 その後、アプリケーションは dwIndex をインクリメントし、(関数がERROR_NO_MORE_ITEMSを返すまで) 値がなくなったまで RegEnumValue 関数を呼び出す必要があります。

また、アプリケーションでは、 dwIndex を関数の最初の呼び出しで最後の値のインデックスに設定し、インデックス 0 の値が列挙されるまでインデックスをデクリメントすることもできます。 最後の値のインデックスを取得するには、 RegQueryInfoKey 関数を使用します。

RegEnumValue を使用している間は、クエリ対象のキーを変更する可能性のあるレジストリ関数をアプリケーションで呼び出さないでください。

データにREG_SZ、REG_MULTI_SZ、またはREG_EXPAND_SZの型がある場合、文字列が適切な null 終端文字で格納されていない可能性があります。 したがって、関数がERROR_SUCCESSを返した場合でも、アプリケーションは文字列を使用する前に適切に終了するようにする必要があります。それ以外の場合は、バッファーが上書きされる可能性があります。 (REG_MULTI_SZ文字列には 、null で終わる 2 つの文字を含める必要があることに注意してください)。

名前バッファーとデータ バッファーの最大サイズを確認するには、 RegQueryInfoKey 関数を使用します。

例

例については、「 レジストリ サブキーの列挙」を参照してください。

要件

関連項目

RegCreateKeyEx

RegEnumKeyEx

RegOpenKeyEx

RegQueryInfoKey

レジストリ関数

レジストリの概要