RegQueryValueA 함수(winreg.h)

아티클
08/27/2023

지정된 레지스트리 키의 기본값 또는 명명되지 않은 값과 연결된 데이터를 검색합니다. 데이터는 null로 끝나는 문자열이어야 합니다.

참고 이 함수는 16비트 버전의 Windows와의 호환성을 위해서만 제공됩니다. 애플리케이션은 RegQueryValueEx 함수를 사용해야 합니다.

구문

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

매개 변수

[in] hKey

열린 레지스트리 키에 대한 핸들입니다. 키는 KEY_QUERY_VALUE 액세스 권한으로 열려 있어야 합니다. 자세한 내용은 레지스트리 키 보안 및 액세스 권한을 참조하세요.

이 핸들은 RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx 또는 RegOpenKeyTransacted 함수에 의해 반환됩니다. 미리 정의된 다음 키 중 하나일 수도 있습니다.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in, optional] lpSubKey

기본값이 검색되는 hKey 매개 변수의 하위 키 이름입니다.

키 이름은 대/소문자를 구분하지 않습니다.

이 매개 변수가 NULL 이거나 빈 문자열을 가리키는 경우 함수는 hKey로 식별된 키의 기본값을 검색합니다.

자세한 내용은 레지스트리 요소 크기 제한을 참조하세요.

[out, optional] lpData

지정된 키의 기본값을 받는 버퍼에 대한 포인터입니다.

lpValue가 NULL이고 lpcbValue가 NULL이 아닌 경우 함수는 ERROR_SUCCESS 반환하고 lpcbValue가 가리키는 변수에 데이터 크기를 바이트 단위로 저장합니다. 이렇게 하면 애플리케이션이 값의 데이터에 버퍼를 할당하는 가장 좋은 방법을 결정할 수 있습니다.

[in, out, optional] lpcbData

lpValue 매개 변수가 가리키는 버퍼의 크기를 바이트 단위로 지정하는 변수에 대한 포인터입니다. 함수가 반환되면 이 변수에는 종료되는 null 문자를 포함하여 lpValue에 복사된 데이터의 크기가 포함됩니다.

데이터에 REG_SZ, REG_MULTI_SZ 또는 REG_EXPAND_SZ 형식이 있는 경우 이 크기에는 종료 되는 null 문자 또는 문자가 포함됩니다. 자세한 내용은 설명 부분을 참조하세요.

지정된 lpValue 버퍼가 데이터를 저장할 만큼 크지 않은 경우 함수는 ERROR_MORE_DATA 반환하고 lpcbValue가 가리키는 변수에 필요한 버퍼 크기를 저장합니다. 이 경우 lpValue 버퍼의 내용은 정의되지 않습니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드입니다.

lpValue 버퍼가 너무 작아서 값을 받지 못하면 함수는 ERROR_MORE_DATA 반환합니다.

설명

이 함수의 ANSI 버전을 사용하는 경우( 명시적으로 RegQueryValueA 를 호출하거나 Windows.h 파일을 포함하기 전에 UNICODE를 정의하지 않음) 이 함수는 저장된 유니코드 문자열을 ANSI 문자열로 변환한 후 lpValue 매개 변수로 지정된 버퍼로 복사합니다.

데이터에 REG_SZ, REG_MULTI_SZ 또는 REG_EXPAND_SZ 형식이 있는 경우 문자열이 적절한 null 종료 문자와 함께 저장되지 않았을 수 있습니다. 따라서 함수가 ERROR_SUCCESS 반환하더라도 애플리케이션은 문자열을 사용하기 전에 문자열이 올바르게 종료되었는지 확인해야 합니다. 그렇지 않으면 버퍼를 덮어쓸 수 있습니다. (REG_MULTI_SZ 문자열에는 두 개의 null 종결 문자가 있어야 합니다.)

특정 레지스트리 키에 액세스하는 작업은 리디렉션됩니다. 자세한 내용은 레지스트리의 레지스트리 가상화 및 32비트 및 64비트 애플리케이션 데이터를 참조하세요.

참고

winreg.h 헤더는 REgQueryValue를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


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