RegQueryValueExA 함수(winreg.h)

아티클
06/01/2023

열린 레지스트리 키와 연결된 지정된 값 이름의 형식 및 데이터를 검색합니다.

경고

쿼리되는 값이 문자열(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에 복사된 데이터의 크기가 포함됩니다.

lpData가 NULL인 경우에만 lpcbData 매개 변수는 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 매개 변수를 통해 반환되는 값은 정의되지 않습니다. 성능 데이터의 크기가 한 호출에서 다음 호출로 변경 될 수 있기 때문입니다. 이 경우 버퍼 크기를 늘리고 RegQueryValueEx 를 다시 호출하여 lpcbData 매개 변수에서 업데이트된 버퍼 크기를 전달해야 합니다. 함수가 성공할 때까지 이 작업을 반복합니다. 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 문자열에는 두 개의 종료 null 문자가 있어야 합니다.) 애플리케이션에서 문자열이 올바르게 종료되도록 할 수 있는 한 가지 방법은 필요한 경우 종료 null 문자를 추가하는 RegGetValue를 사용하는 것입니다.

데이터에 REG_SZ, REG_MULTI_SZ 또는 REG_EXPAND_SZ 형식이 있고 이 함수의 ANSI 버전이 사용되는 경우( 명시적으로 RegQueryValueExA 를 호출하거나 Windows.h 파일을 포함하기 전에 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 헤더는 REgQueryValueEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	winreg.h(Windows.h 포함)
라이브러리	Advapi32.lib
DLL	Advapi32.dll