Функция StartServiceCtrlDispatcherA (winsvc.h)

Статья
08/27/2023

Подключает поток main процесса службы к диспетчеру управления службами, что приводит к тому, что поток будет потоком диспетчера управления службой для вызывающего процесса.

Синтаксис

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

Параметры

[in] lpServiceStartTable

Указатель на массив SERVICE_TABLE_ENTRY структур, содержащих одну запись для каждой службы, которая может выполняться в вызывающем процессе. Члены последней записи в таблице должны иметь значения NULL для обозначения конца таблицы.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Диспетчер управления службами может задать следующий код ошибки. Другие коды ошибок могут задаваться функциями реестра, которые вызываются диспетчером управления службами.

Код возврата	Описание
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT	Эта ошибка возвращается, если программа выполняется как консольное приложение, а не как услуга. Если программа будет запускаться как консольное приложение для отладки, структурировать ее таким образом, чтобы код службы не вызывался при возврате этой ошибки.
ERROR_INVALID_DATA	Указанная таблица диспетчеризации содержит записи в неправильном формате.
ERROR_SERVICE_ALREADY_RUNNING	Процесс уже вызвал StartServiceCtrlDispatcher. Каждый процесс может вызывать StartServiceCtrlDispatcher только один раз.

Когда диспетчер управления службами запускает процесс службы, он ожидает, пока процесс вызовет функцию StartServiceCtrlDispatcher . Поток main процесса службы должен выполнить этот вызов как можно скорее после его запуска (в течение 30 секунд). Если startServiceCtrlDispatcher завершается успешно, вызывающий поток подключается к диспетчеру управления службами и не возвращается до тех пор, пока все запущенные службы в процессе не перешлы в состояние SERVICE_STOPPED. Диспетчер управления службами использует это подключение для отправки запросов на управление и запуск службы в main поток процесса службы. Поток main выступает в качестве диспетчера, вызывая соответствующую функцию HandlerEx для обработки запросов управления или создавая новый поток для выполнения соответствующей функции ServiceMain при запуске новой службы.

Параметр lpServiceTable содержит запись для каждой службы, которая может выполняться в вызывающем процессе. Каждая запись указывает функцию ServiceMain для этой службы. Для SERVICE_WIN32_SHARE_PROCESS служб каждая запись должна содержать имя службы. Это имя службы, указанное функцией CreateService при установке службы. Для SERVICE_WIN32_OWN_PROCESS служб имя службы в записи таблицы игнорируется.

Если служба выполняется в собственном процессе, main поток процесса службы должен немедленно вызвать StartServiceCtrlDispatcher. Все задачи инициализации выполняются в функции ServiceMain службы при запуске службы.

Если несколько служб совместно используют один процесс и необходимо выполнить некоторую общую инициализацию на уровне процесса перед вызовом какой-либо функции ServiceMain, поток main может выполнить работу перед вызовом StartServiceCtrlDispatcher, если это займет менее 30 секунд. В противном случае необходимо создать другой поток для выполнения инициализации на уровне процесса, а поток main вызывает StartServiceCtrlDispatcher и становится диспетчером управления службой. Любая инициализация для конкретной службы по-прежнему должна выполняться в отдельных функциях службы main.

Службы не должны пытаться отобразить пользовательский интерфейс напрямую. Дополнительные сведения см. в разделе Интерактивные службы.

Примеры

Пример см. в разделе Написание основной функции программы службы.

Примечание

Заголовок winsvc.h определяет StartServiceCtrlDispatcher как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winsvc.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll