RegQueryValueExA 関数 (winreg.h)

[アーティクル]
11/20/2024

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

警告

クエリ対象の値が文字列 (REG_SZ、REG_MULTI_SZ、REG_EXPAND_SZ) の場合、返される値は null で終わるとは限りません。返される文字列値が null で終わるようにする場合は、RegGetValue 関数を使用します。詳細については、以下の解説を参照してください。

構文

LSTATUS RegQueryValueExA(
  [in]                HKEY    hKey,
  [in, optional]      LPCSTR  lpValueName,
                      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_PERFORMANCE_NLSTEXT

HKEY_PERFORMANCE_TEXT

HKEY_USERS

[in, optional] lpValueName

レジストリ値の名前。

lpValueName NULL または空の文字列 "" 場合、関数はキーの名前のない値または既定値 (存在する場合) の型とデータを取得します。

lpValueName レジストリにない値を指定すると、関数はERROR_FILE_NOT_FOUNDを返します。

キーには、名前のない値や既定値は自動的に設定されません。名前のない値には、任意の型を指定できます。詳細については、「レジストリ要素のサイズ制限」を参照してください。

lpReserved

このパラメーターは予約されており、NULLする必要があります。

[out, optional] lpType

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

[out, optional] lpData

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

[in, out, optional] lpcbData

lpData パラメーターが指すバッファーのサイズをバイト単位で指定する変数へのポインター。関数から制御が戻るときに、この変数には、lpDataにコピーされたデータのサイズ格納されます。

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

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

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

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

hKey が HKEY_PERFORMANCE_DATA を指定し、lpData バッファーが返されるすべてのデータを格納するのに十分な大きさでない場合、regQueryValueEx はERROR_MORE_DATAを返し、lpcbData パラメーターを介して返される値は未定義です。これは、パフォーマンスデータのサイズが 1 つの呼び出しから次の呼び出しに変わる可能性があるためです。この場合は、バッファーサイズを大きくし、lpcbData パラメーターで更新されたバッファーサイズ再度渡 RegQueryValueEx を呼び出す必要があります。関数が成功するまで、これを繰り返します。 lpcbData によって返される値は予測できないため、バッファーサイズを追跡するには、別の変数を保持する必要があります。

lpValueName レジストリ値が存在しない場合、regQueryValueEx はERROR_FILE_NOT_FOUNDを返し、lpcbData パラメーターを介して返される値は未定義です。

戻り値

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

関数が失敗した場合、戻り値はシステムエラーコードです。

lpData バッファーが小さすぎてデータを受け取れなければ、関数はERROR_MORE_DATAを返します。

lpValueName レジストリ値が存在しない場合、関数はERROR_FILE_NOT_FOUNDを返します。

備考

アプリケーションは通常、RegEnumValue を呼び出して値の名前を決定し、RegQueryValueEx をして名前のデータを取得します。

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

データにREG_SZ、REG_MULTI_SZ、またはREG_EXPAND_SZ型があり、この関数の ANSI バージョンが使用されている場合 (RegQueryValueExA を明示的に呼び出すか、Windows.h ファイルを含める前に UNICODE を定義しない場合)、この関数は、格納されている Unicode 文字列を ANSI 文字列に変換してから、lpData指すバッファーにコピーします。

hKeyHKEY_PERFORMANCE_DATA ハンドルと指定したオブジェクトの値文字列に設定された RegQueryValueEx 関数を呼び出すと、返されるデータ構造に要求されないオブジェクトが含まれる場合があります。驚かないでください。これは通常の動作です。 RegQueryValueEx 関数を呼び出すときは、要求されたオブジェクトを検索するために、返されるデータ構造を常に確認する必要があります。

特定のレジストリキーにアクセスする操作はリダイレクトされることに注意してください。詳細については、「レジストリ仮想化およびレジストリの 32 ビットおよび 64 ビットアプリケーションデータをする」を参照してください。

例

この関数を呼び出すたびに、lpcbData パラメーターが指す値を再初期化してください。これは、次のコード例のように、ループでこの関数を呼び出すときに非常に重要です。

#include <windows.h>
#include <malloc.h>
#include <stdio.h>

#define TOTALBYTES    8192
#define BYTEINCREMENT 4096

void main()
{
    DWORD BufferSize = TOTALBYTES;
    DWORD cbData;
    DWORD dwRet;

    PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
    cbData = BufferSize;

    printf("\nRetrieving the data...");

    dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                             TEXT("Global"),
                             NULL,
                             NULL,
                             (LPBYTE) PerfData,
                             &cbData );
    while( dwRet == ERROR_MORE_DATA )
    {
        // Get a buffer that is big enough.

        BufferSize += BYTEINCREMENT;
        PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
        cbData = BufferSize;

        printf(".");
        dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                         TEXT("Global"),
                         NULL,
                         NULL,
                         (LPBYTE) PerfData,
                         &cbData );
    }
    if( dwRet == ERROR_SUCCESS )
        printf("\n\nFinal buffer size is %d\n", BufferSize);
    else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}

手記

winreg.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして RegQueryValueEx を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	winreg.h (Windows.h を含む)
ライブラリ	Advapi32.lib
DLL	Advapi32.dll

次の方法で共有

RegQueryValueExA 関数 (winreg.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース