RegisterServiceCtrlHandlerExA 함수(winsvc.h)

아티클
08/27/2023

확장 서비스 제어 요청을 처리하는 함수를 등록합니다.

구문

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

매개 변수

[in] lpServiceName

호출 스레드에서 실행하는 서비스의 이름입니다. 서비스를 만들 때 CreateService 함수에 지정된 서비스 제어 프로그램의 서비스 이름입니다.

[in] lpHandlerProc

등록할 처리기 함수에 대한 포인터입니다. 자세한 내용은 HandlerEx를 참조하세요.

[in, optional] lpContext

모든 사용자 정의 데이터입니다. 처리기 함수에 전달되는 이 매개 변수는 여러 서비스가 프로세스를 공유할 때 서비스를 식별하는 데 도움이 될 수 있습니다.

반환 값

함수가 성공하면 반환 값은 서비스 상태 핸들입니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

서비스 제어 관리자가 설정할 수 있는 오류 코드는 다음과 같습니다.

반환 코드	설명
ERROR_NOT_ENOUGH_MEMORY	ANSI 문자열 매개 변수를 유니코드로 변환하는 데 메모리가 부족합니다. 유니코드 문자열 매개 변수에는 이 오류가 발생하지 않습니다.
ERROR_SERVICE_NOT_IN_EXE	프로세스가 StartServiceCtrlDispatcher 함수를 호출할 때 서비스 항목이 잘못 지정되었습니다.

설명

새 서비스의 ServiceMain 함수는 RegisterServiceCtrlHandlerEx 함수를 즉시 호출하여 컨트롤 처리기 함수를 컨트롤 디스패처에 등록해야 합니다. 이렇게 하면 컨트롤 디스패처가 이 서비스에 대한 제어 요청을 받을 때 지정된 함수를 호출할 수 있습니다. 가능한 제어 코드 목록은 HandlerEx를 참조하세요. 호출 프로세스의 스레드는 이 함수에서 반환된 서비스 상태 핸들을 사용하여 SetServiceStatus 함수에 대한 후속 호출에서 서비스를 식별할 수 있습니다.

RegisterServiceCtrlHandlerEx는 다른 서비스가 실수로 이 서비스를 상태 설정할 수 없도록 호출자가 사용할 서비스 상태 핸들을 반환하므로 첫 번째 SetServiceStatus 호출 전에 RegisterServiceCtrlHandlerEx 함수를 호출해야 합니다. 또한 서비스에서 SetServiceStatus 함수를 통해 수락하는 컨트롤을 지정할 때까지 컨트롤 요청을 수신하려면 컨트롤 처리기가 있어야 합니다.

제어 요청으로 제어 처리기 함수를 호출하는 경우 서비스는 서비스가 중지 또는 종료 컨트롤을 처리하는 경우와 같이 서비스 상태 변경된 경우에만 SetServiceStatus를 호출하여 서비스 제어 관리자에 상태 보고해야 합니다. 서비스 상태 변경되지 않은 경우 서비스는 서비스 제어 관리자에 상태 보고해서는 안 됩니다.

서비스 상태 핸들을 닫을 필요가 없습니다.

참고

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

요구 사항

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