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

Статья
11/20/2024

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

Синтаксис

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 только один раз.

Замечания

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

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

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

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

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

Примеры

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winsvc.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll