Функция StartServiceCtrlDispatcher устанавливает связь главного потока процесса службы с диспетчером управления службами, который заставляет поток быть потоком диспетчера управления службой для вызывающего процесса.
Синтаксис
BOOL StartServiceCtrlDispatcher( const LPSERVICE_TABLE_ENTRY lpServiceTable ); |
[in] Указатель на массив структур SERVICE_TABLE_ENTRY, имеющих в своем составе одну запись для каждой службы, которая может выполнить код в вызывающем процесс. Члены структуры последней записи в таблице должны иметь значения значения ПУСТО (NULL), чтобы определять конец таблицы.
Если функция завершается успешно, возвращаемое значение является ненулевым.
Если функция завершается ошибкой, возвращаемое значение - нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.
Следующие коды ошибки могут быть установлены диспетчером управления службами. Другие могут установиться функциями реестра, которые вызывает диспетчер управления службами.
Код возврата | Описание |
---|---|
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT | Как правило, эта ошибка указывает, что программа
запускается как консольное приложение, а не как служба.
Если программа запускается как консольное приложение для отладки целевого модуля, структура ее также не вызывает специальный для службы код, когда возвращается эта ошибка. |
ERROR_INVALID_DATA | Указанная координирующая таблица имеет в своем составе записи, которые находятся в неправильном формате. |
ERROR_SERVICE_ALREADY_RUNNING | Процесс уже вызвал
StartServiceCtrlDispatcher. Каждый
процесс может вызвать StartServiceCtrlDispatcher только один раз.
Windows NT: Это значение не поддерживается. |
Замечания
Когда диспетчер управления службами запускает процесс службы, он ставит его в режим ожидания, чтобы вызвать функцию StartServiceCtrlDispatcher. Главный поток процесса службы должен сделать этот вызов как можно скорее после того, как он запуститься. Если вызов функции StartServiceCtrlDispatcher завершается успешно, она устанавливает связь вызывающего потока с диспетчером управления службами и не возвращает значение до тех пор, пока все запущенные службы в процессе не завершаться. Диспетчер управления службами использует эту связь, чтобы отправлять управление и запускать службы по запросу главного потока процесса службы. Главный поток действует как диспетчер, вызывая соответствующую функцию HandlerEx, чтобы обработать запросы на управление, или создавая новый поток, чтобы выполнить соответствующую функцию ServiceMain, когда новая служба запускается.
Параметр lpServiceTable имеет в своем составе запись для каждой службы, которая может запуститься в вызывающем процесс. Каждая запись задает функцию ServiceMain для этой службы. Для служб SERVICE_WIN32_SHARE_PROCESS, каждая запись должна иметь в своем составе имя службы. Это имя - имя службы, которое определялось функцией CreateService, когда служба была установлена. Для служб SERVICE_WIN32_OWN_PROCESS игнорируется имя службы в записи таблицы.
Если служба запускается в своем собственном процессе, главный поток процесса службы должен немедленно вызвать StartServiceCtrlDispatcher. Все задачи инициализации делаются в функции ServiceMain службы, когда служба запускается.
Если несколько служб совместно используют процесс и нужна какая-то общая инициализация всего процесса, то нужно прежде всего вызывать любую функцию ServiceMain, главный поток которой может сделать эту работу перед вызовом StartServiceCtrlDispatcher, занимая для нее меньше чем 30 секунд. Иначе, должен создаться другой поток, чтобы сделать инициализацию всего процесса, в то время как главный поток вызывает StartServiceCtrlDispatcher, и стать диспетчером управления службой. Любая специальная для службы инициализация должна все же делаться в отдельных главных функциях служб.
Демонстрационный код
Пример смотри в статье Запись функции ServiceMain.
Смотри также
Обзор Службы, Функции, используемые службами, ControlService, HandlerEx, ServiceMain, SERVICE_TABLE_ENTRY
Размещение и совместимость StartServiceCtrlDispatcher |
||
К | Windows XP | Да |
л | Windows 2000 Professional | Да |
и | Windows NT Workstation | Да |
е | Windows Me | Нет |
н | Windows 98 | Нет |
т | Windows 95 | Нет |
С | Windows Server 2003 | Да |
е | Windows 2000 Server | Да |
р | Windows NT Server | Да |
в | ||
е | ||
р | ||
Используемая библиотека | Advapi32.lib | |
Используемая DLL | advapi32.dll | |
Заголовочный файл | ||
- объявлено в | Winsvc.h | |
- включено в | Windows.h | |
Unicode | Реализуется как StartServiceCtrlDispatcherW (Unicode) и StartServiceCtrlDispatcherA (ANSI) | |
Замечания по платформе | Не имеется |