RegQueryValueExA 関数 (winreg.h)

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

構文

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 つは、必要に応じて終端の null 文字を追加する RegGetValue を使用することです。

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

hKey をHKEY_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);
}

要件

関連項目

ExpandEnvironmentStrings

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegGetValue

RegOpenKeyEx

RegQueryInfoKey

レジストリ関数

レジストリの概要