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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in] hService

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

[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, может быть заблокирован в функции обработчика управления.

Замечания

При запуске службы драйверов функция StartService не возвращается до завершения инициализации драйвера устройства.

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

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

Текущее состояние службы имеет значение SERVICE_START_PENDING.
Элементы управления, принятые, не заданы (ноль).
Значение 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 [только классические приложения]
целевая платформа	Виндоус
заголовка	winsvc.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll