StartServiceCtrlDispatcherA 함수(winsvc.h)

아티클
08/27/2023

서비스 프로세스의 기본 스레드를 서비스 제어 관리자에 연결하여 스레드가 호출 프로세스의 서비스 제어 디스패처 스레드가 됩니다.

구문

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);

매개 변수

[in] lpServiceStartTable

호출 프로세스에서 실행할 수 있는 각 서비스에 대해 하나의 항목을 포함하는 SERVICE_TABLE_ENTRY 구조체 배열에 대한 포인터입니다. 테이블의 마지막 항목 멤버는 테이블의 끝을 지정하는 NULL 값이 있어야 합니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

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

서비스 제어 관리자에서 다음 오류 코드를 설정할 수 있습니다. 다른 오류 코드는 서비스 제어 관리자가 호출하는 레지스트리 함수에서 설정할 수 있습니다.

반환 코드	설명
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT	이 오류는 프로그램이 서비스가 아닌 콘솔 애플리케이션으로 실행되는 경우 반환됩니다. 프로그램이 디버깅을 위해 콘솔 애플리케이션으로 실행되는 경우 이 오류가 반환될 때 서비스별 코드가 호출되지 않도록 구성합니다.
ERROR_INVALID_DATA	지정된 디스패치 테이블에는 적절한 형식이 아닌 항목이 포함되어 있습니다.
ERROR_SERVICE_ALREADY_RUNNING	이 프로세스는 이미 StartServiceCtrlDispatcher를 호출했습니다. 각 프로세스 는 StartServiceCtrlDispatcher를 한 번만 호출할 수 있습니다.

설명

서비스 제어 관리자가 서비스 프로세스를 시작하면 프로세스가 StartServiceCtrlDispatcher 함수를 호출할 때까지 기다립니다. 서비스 프로세스의 기본 스레드는 시작 후(30초 이내에) 가능한 한 빨리 이 호출을 수행해야 합니다. StartServiceCtrlDispatcher가 성공하면 호출 스레드를 서비스 제어 관리자에 연결하고 프로세스에서 실행 중인 모든 서비스가 SERVICE_STOPPED 상태가 될 때까지 반환되지 않습니다. 서비스 제어 관리자는 이 연결을 사용하여 제어 및 서비스 시작 요청을 서비스 프로세스의 기본 스레드로 보냅니다. 기본 스레드는 제어 요청을 처리하기 위해 적절한 HandlerEx 함수를 호출하거나 새 서비스가 시작될 때 적절한 ServiceMain 함수를 실행하는 새 스레드를 만들어 디스패처 역할을 합니다.

lpServiceTable 매개 변수에는 호출 프로세스에서 실행할 수 있는 각 서비스에 대한 항목이 포함되어 있습니다. 각 항목은 해당 서비스에 대한 ServiceMain 함수를 지정합니다. SERVICE_WIN32_SHARE_PROCESS 서비스의 경우 각 항목에 서비스 이름이 포함되어야 합니다. 이 이름은 서비스가 설치되었을 때 CreateService 함수에서 지정한 서비스 이름입니다. SERVICE_WIN32_OWN_PROCESS 서비스의 경우 테이블 항목의 서비스 이름은 무시됩니다.

서비스가 자체 프로세스에서 실행되는 경우 서비스 프로세스의 기본 스레드는 StartServiceCtrlDispatcher를 즉시 호출해야 합니다. 모든 초기화 작업은 서비스가 시작될 때 서비스의 ServiceMain 함수에서 수행됩니다.

여러 서비스가 프로세스를 공유하고 일부 일반적인 프로세스 전체 초기화를 ServiceMain 함수가 호출되기 전에 수행해야 하는 경우 기본 스레드는 30초 미만이 걸리는 한 StartServiceCtrlDispatcher를 호출하기 전에 작업을 수행할 수 있습니다. 그렇지 않으면 프로세스 전체 초기화를 수행하려면 다른 스레드를 만들어야 하고, 기본 스레드는 StartServiceCtrlDispatcher를 호출하고 서비스 제어 디스패처가 됩니다. 모든 서비스별 초기화는 개별 서비스 기본 함수에서 계속 수행해야 합니다.

서비스는 사용자 인터페이스를 직접 표시하려고 시도해서는 안 됩니다. 자세한 내용은 Interactive Services를 참조하세요.

예제

예를 들어 서비스 프로그램의 기본 함수 작성을 참조하세요.

참고

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

요구 사항

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