RegisterServiceCtrlHandlerExA 함수(winsvc.h)

아티클
11/20/2024

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

통사론

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

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

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

메모

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

요구 사항

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