SHRegGetValueA 함수(shlwapi.h)

아티클
03/02/2024

[SHRegGetValue 는 운영 체제 또는 제품의 후속 버전에서 변경되거나 사용할 수 없습니다. 그 자리에 RegGetValue를 사용합니다.]

레지스트리 값을 검색합니다.

구문

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

매개 변수

[in] hkey

형식: HKEY

현재 열려 있는 키 또는 다음 미리 정의된 값에 대한 핸들입니다.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

형식: LPCTSTR

값을 검색할 hkey에서 하위 키로의 상대 경로를 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 매개 변수는 NULL 또는 빈 문자열일 수 있으며, 이 경우 데이터가 hkey 위치에서 검색됩니다.

[in] pszValue

형식: LPCTSTR

값의 이름을 포함하는 null로 끝나는 문자열에 대한 포인터입니다. 이 매개 변수는 NULL 또는 빈 문자열일 수 있으며, 이 경우 기본값에서 데이터가 검색됩니다.

[in] srrfFlags

형식: SRRF

검색할 데이터를 제한하는 하나 이상의 SRRF 플래그입니다. 하나 이상의 형식 제한(SRRF_RT) 값을 지정해야 합니다.

[in, out] pdwType

형식: LPDWORD

검색된 값에 저장된 데이터 형식을 수신하는 DWORD 에 대한 포인터입니다. 기본값을 사용하는 경우 입력 pdwType 은 기본값의 형식입니다. 가능한 값은 레지스트리 데이터 형식을 참조하세요. SRRF_NOEXPAND 플래그가 설정되지 않으면 REG_EXPAND_SZ 형식이 자동으로 확장되고 REG_SZ 반환됩니다. 형식 정보가 필요하지 않은 경우 이 매개 변수는 NULL일 수 있습니다.

[out] pvData

형식: LPVOID

값의 데이터를 수신하는 버퍼에 대한 포인터입니다. 데이터가 필요하지 않은 경우 이 매개 변수는 NULL 일 수 있습니다. 예를 들어 값의 존재만 테스트하는 경우 특정 값 데이터는 불필요합니다.

[in, out] pcbData

형식: LPDWORD

항목에서 대상 데이터 버퍼 pvData의 크기(바이트)를 포함하는 DWORD에 대한 포인터입니다. 이 값은 pvData가 NULL인 경우에만 NULL일 수 있습니다. 종료 시 pcbData 는 이러한 값 중 하나를 가리킵니다.

pvData	반환 값	pcbData
NULL	ERROR_SUCCESS	레지스트리 데이터를 보유하기에 충분한 바이트 크기입니다. 정확한 크기가 아니라 충분한 크기로 보장됩니다.
NULL이 아닌 경우	ERROR_SUCCESS	pvData에 기록된 정확한 바이트 수입니다.
NULL이 아닌 경우	ERROR_MORE_DATA	전체 데이터를 보유하는 데 필요한 바이트 크기입니다. 정확한 크기가 아니라 충분한 크기로 보장됩니다.

반환 값

형식: LSTATUS

성공하면 ERROR_SUCCESS 반환하거나, 그렇지 않으면 Winerror.h에 정의된 0이 아닌 오류 코드를 반환합니다. FormatMessage 함수를FORMAT_MESSAGE_FROM_SYSTEM 플래그와 함께 사용하여 오류에 대한 일반적인 설명을 검색할 수 있습니다.

설명

SHRegGetValue 는 데이터 형식 검사, 부팅 모드 검사, REG_EXPAND_SZ 데이터의 자동 확장 및 REG_SZ, REG_EXPAND_SZ 및 REG_MULTI_SZ 데이터의 null 종료를 보장합니다.

hkey로 식별되는 키는 KEY_QUERY_VALUE 보안 액세스를 사용하여 열어야 합니다. pszSubKey가 NULL 또는 빈 문자열이 아닌 경우 해당 키도 현재 호출 컨텍스트에서 KEY_QUERY_VALUE 보안 액세스로 열 수 있어야 합니다.

데이터 형식이 REG_SZ, REG_EXPAND_SZ 또는 REG_MULTI_SZ 경우 반환된 모든 데이터에는 문자열의 null 종료가 포함되거나 고려됩니다. 예를 들어 pvData 가 NULL이 아닌 경우 해당 버퍼에 반환된 데이터는 null로 종료됩니다. pcbData가 NULL이 아닌 경우 가리키는 버퍼 크기에는 종료 null 문자를 보유하는 데 필요한 바이트가 포함됩니다.

SRRF_NOEXPAND 플래그를 설정하지 않으면 REG_EXPAND_SZ 형식의 문자열 데이터가 반환되기 전에 자동으로 확장됩니다. 확장된 문자열의 형식은 pdwType 에서 REG_SZ 보고되고, pcbData 매개 변수는 확장된 문자열에 대해 작성된 바이트 수를 가리키고, pvData 가 가리키는 버퍼는 확장된 버전의 문자열을 보유합니다.

성능 정보

pszSubKey가 NULL 또는 빈 문자열이 아닌 경우 해당 키는 액세스할 때마다 이 함수에 의해 열리고 닫힙니다. 애플리케이션이 동일한 하위 키에서 일련의 값을 검색해야 하는 경우 SHRegGetValue를 호출하기 전에 RegOpenKeyEx를 사용하여 키를 열어 성능이 향상됩니다. pszSubKey가 NULL로 설정된 상태에서 RegOpenKeyEx의 phkResult 매개 변수에 반환된 키를 이 함수의 hkey 매개 변수로 사용합니다.

데이터 형식이 REG_EXPAND_SZ SRRF_NOEXPAND 플래그가 설정되지 않은 경우 레지스트리를 추가로 호출하여 데이터를 읽거나 다시 읽을 수 있습니다. 다음 조건으로 인해 추가 호출이 발생합니다.

pvData 는 NULL이고 pcbData 는 NULL이 아닙니다. 데이터를 검색하지는 않지만 레지스트리를 읽어 문자열을 가져와야 하며 해당 문자열이 확장되어 데이터 버퍼의 필요한 크기를 결정해야 합니다.
pvData 는 NULL이 아니지만 데이터를 보유하기에는 너무 작습니다. 전체 문자열을 가져오기 위해 데이터를 다시 읽고, 문자열이 확장되고, 필요한 총 크기가 결정됩니다.

참고

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	WINDOWS XP SP2 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	shlwapi.h
라이브러리	Shlwapi.lib
DLL	Shlwapi.dll(버전 6.0 이상)

추가 정보

RegQueryValueEx

다음을 통해 공유