RegQueryValueExW 関数 (winreg.h)
開いているレジストリ キーに関連付けられている指定した値名の型とデータを取得します。
警告
クエリ対象の値が文字列 (REG_SZ、REG_MULTI_SZ、REG_EXPAND_SZ) の場合、返される値は null で終わる保証はありません。 返される文字列値が null で終わるようにする場合は、 RegGetValue 関数を使用します。 詳細については、以下の解説を参照してください。
構文
LSTATUS RegQueryValueExW(
[in] HKEY hKey,
[in, optional] LPCWSTR 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);
}
注意
winreg.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして RegQueryValueEx を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winreg.h (Windows.h を含む) |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |