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

Статья
08/27/2023

Запускает службу.

Синтаксис

BOOL StartServiceA(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwNumServiceArgs,
  [in, optional] LPCSTR    *lpServiceArgVectors
);

Параметры

[in] hService

Дескриптор службы. Этот дескриптор возвращается функцией OpenService или CreateService и должен иметь право доступа SERVICE_START. Дополнительные сведения см. в разделе Service Security and Access Rights.

[in] dwNumServiceArgs

Количество строк в массиве lpServiceArgVectors . Если lpServiceArgVectors имеет значение NULL, этот параметр может быть равен нулю.

[in, optional] lpServiceArgVectors

Строки со значением NULL, передаваемые в функцию ServiceMain для службы в качестве аргументов. Если аргументы отсутствуют, этот параметр может иметь значение NULL. В противном случае первый аргумент (lpServiceArgVectors[0]) — это имя службы, за которым следуют любые дополнительные аргументы (lpServiceArgVectors[1] через lpServiceArgVectors[dwNumServiceArgs-1]).

Службы драйверов не получают эти аргументы.

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

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Дескриптор не имеет права доступа к SERVICE_START.
ERROR_INVALID_HANDLE	Дескриптор недействителен.
ERROR_PATH_NOT_FOUND	Не удалось найти двоичный файл службы.
ERROR_SERVICE_ALREADY_RUNNING	Экземпляр службы уже запущен.
ERROR_SERVICE_DATABASE_LOCKED	База данных заблокирована.
ERROR_SERVICE_DEPENDENCY_DELETED	Служба зависит от службы, которая не существует или помечена для удаления.
ERROR_SERVICE_DEPENDENCY_FAIL	Служба зависит от другой службы, которая не смогла запуститься.
ERROR_SERVICE_DISABLED	Служба отключена.
ERROR_SERVICE_LOGON_FAILED	Служба не запущена из-за ошибки входа в систему. Эта ошибка возникает, если служба настроена для запуска с учетной записью, которая не имеет права "Вход в качестве службы".
ERROR_SERVICE_MARKED_FOR_DELETE	Служба помечена для удаления.
ERROR_SERVICE_NO_THREAD	Не удалось создать поток для службы.
ERROR_SERVICE_REQUEST_TIMEOUT	Процесс для службы был запущен, но он не вызвал StartServiceCtrlDispatcher, или поток, который вызвал StartServiceCtrlDispatcher , может быть заблокирован в функции обработчика управления.

При запуске службы диспетчер управления службами (SCM) при необходимости создает процесс службы. Если указанная служба совместно использует процесс с другими службами, требуемый процесс может уже существовать. Функция StartService не ожидает первого обновления состояния от новой службы, так как это может занять некоторое время. Вместо этого он возвращает, когда SCM получает уведомление от диспетчера управления службой о том, что поток ServiceMain для этой службы был успешно создан.

Перед возвратом из StartService SCM устанавливает следующие значения состояния по умолчанию:

Текущее состояние службы равно SERVICE_START_PENDING.
Для принятых элементов управления задано значение none (ноль).
Значение CheckPoint равно нулю.
Время WaitHint равно 2 секундам.

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

Служба не может вызвать StartService во время инициализации. Причина в том, что SCM блокирует базу данных управления службой во время инициализации, поэтому вызов StartService будет блокироваться. После того как служба сообщит об успешном запуске SCM, она может вызвать StartService.

Как и в случае с ControlService, StartService блокируется на 30 секунд, если какая-либо служба занята обработкой кода управления. Если занятая служба по-прежнему не возвращается из функции обработчика по истечении времени ожидания, startService завершается сбоем с ERROR_SERVICE_REQUEST_TIMEOUT. Это связано с тем, что SCM одновременно обрабатывает только одно уведомление элемента управления службой.

Примеры

Пример см. в разделе Запуск службы.

Примечание

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

Требования


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