Функция CreateServiceW (winsvc.h)
Создает объект службы и добавляет его в указанную базу данных диспетчера управления службами.
Синтаксис
SC_HANDLE CreateServiceW(
[in] SC_HANDLE hSCManager,
[in] LPCWSTR lpServiceName,
[in, optional] LPCWSTR lpDisplayName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwServiceType,
[in] DWORD dwStartType,
[in] DWORD dwErrorControl,
[in, optional] LPCWSTR lpBinaryPathName,
[in, optional] LPCWSTR lpLoadOrderGroup,
[out, optional] LPDWORD lpdwTagId,
[in, optional] LPCWSTR lpDependencies,
[in, optional] LPCWSTR lpServiceStartName,
[in, optional] LPCWSTR lpPassword
);
Параметры
[in] hSCManager
Дескриптор базы данных диспетчера управления службами. Этот дескриптор возвращается функцией OpenSCManager и должен иметь право доступа SC_MANAGER_CREATE_SERVICE . Дополнительные сведения см. в разделе Service Security and Access Rights.
[in] lpServiceName
Имя устанавливаемой службы. Максимальная длина строки составляет 256 символов. В базе данных диспетчера управления службами сохраняется регистр символов, но при сравнении имен служб регистр всегда не учитывается. Косая черта (/) и обратная косая черта (\) являются недопустимыми символами имени службы.
[in, optional] lpDisplayName
Отображаемое имя, используемое программами пользовательского интерфейса для идентификации службы. Максимальная длина этой строки равна 256 символам. Имя сохраняется с учетом регистра в диспетчере управления службами. Сравнение отображаемых имен всегда не учитывает регистр.
[in] dwDesiredAccess
Доступ к службе. Перед предоставлением запрошенного доступа система проверяет маркер доступа вызывающего процесса. Список значений см. в разделе Безопасность службы и права доступа.
[in] dwServiceType
Тип службы. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Зарезервировано. |
|
Служба драйвера файловой системы. |
|
Служба драйверов. |
|
Зарезервировано. |
|
Служба, которая выполняется в собственном процессе. |
|
Служба, которая совместно использует процесс с одной или несколькими другими службами. Дополнительные сведения см. в разделе Служебные программы. |
Если вы указываете SERVICE_WIN32_OWN_PROCESS или SERVICE_WIN32_SHARE_PROCESS, а служба выполняется в контексте учетной записи LocalSystem, можно также указать следующее значение.
| Значение | Значение |
|---|---|
|
Служба может взаимодействовать с рабочим столом.
Дополнительные сведения см. в разделе Интерактивные службы. |
[in] dwStartType
Параметры запуска службы. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Служба автоматически запускается диспетчером управления службами во время запуска системы. Дополнительные сведения см. в разделе Автоматический запуск служб. |
|
Драйвер устройства, запущенный системным загрузчиком. Это значение допустимо только для служб драйверов. |
|
Служба, запущенная диспетчером управления службами, когда процесс вызывает функцию StartService . Дополнительные сведения см. в разделе Запуск служб по запросу. |
|
Служба, которая не может быть запущена. Попытки запустить службу приводят к ERROR_SERVICE_DISABLED кода ошибки. |
|
Драйвер устройства, запущенный функцией IoInitSystem . Это значение допустимо только для служб драйверов. |
[in] dwErrorControl
Серьезность ошибки и выполняемое действие, если эта служба не запускается. Этот параметр может принимать одно из указанных ниже значений.
[in, optional] lpBinaryPathName
Полный путь к двоичному файлу службы. Если путь содержит пробел, он должен быть заключен в кавычки, чтобы он правильно интерпретировался. Например, "d:\my share\myservice.exe" следует указать как ""d:\my share\myservice.exe"".
Путь также может содержать аргументы для службы с автоматическим запуском. Например, "d:\myshare\myservice.exe arg1 arg2". Эти аргументы передаются в точку входа службы (обычно это функция main).
Если указать путь на другом компьютере, общая папка должна быть доступна учетной записи локального компьютера, так как это контекст безопасности, используемый в удаленном вызове. Однако это требование позволяет использовать любые потенциальные уязвимости на удаленном компьютере, чтобы повлиять на локальный компьютер. Поэтому лучше всего использовать локальный файл.
[in, optional] lpLoadOrderGroup
Имена группы упорядочения загрузки, членом которой является эта служба. Укажите ЗНАЧЕНИЕ NULL или пустую строку, если служба не принадлежит группе.
Программа запуска использует группы упорядочения загрузки для загрузки групп служб в указанном порядке по отношению к другим группам. Список групп упорядочения нагрузки содержится в следующем значении реестра: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
[out, optional] lpdwTagId
Указатель на переменную, получающую значение тега, уникальное в группе, указанной в параметре lpLoadOrderGroup . Укажите ЗНАЧЕНИЕ NULL, если вы не изменяете существующий тег.
Вы можете использовать тег для запуска службы заказа в группе упорядочения нагрузки, указав вектор порядка тегов в следующем значении реестра:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList
Теги оцениваются только для служб драйверов, которые имеют SERVICE_BOOT_START или SERVICE_SYSTEM_START типы запуска.
[in, optional] lpDependencies
Указатель на массив имен служб, разделенных значениями NULL, или групп упорядочения загрузки, которые система должна запустить перед этой службой. Укажите значение NULL или пустую строку, если у службы нет зависимостей. Зависимость от группы означает, что эта служба может запускаться, если после попытки запуска всех участников группы выполняется по крайней мере один из участников группы.
Имена групп должны быть префиксированы с помощью SC_GROUP_IDENTIFIER , чтобы их можно было отличить от имени службы, так как службы и группы служб используют одно и то же пространство имен.
[in, optional] lpServiceStartName
Имя учетной записи, под которой должна выполняться служба. Если служба имеет тип SERVICE_WIN32_OWN_PROCESS, используйте имя учетной записи в формате Имя_\пользователя домена. Процесс службы войдет в систему от имени этого пользователя. Если учетная запись принадлежит встроенному домену, можно указать .\UserName.
Если этот параметр имеет значение NULL, CreateService использует учетную запись LocalSystem. Если тип службы указывает SERVICE_INTERACTIVE_PROCESS, служба должна выполняться в учетной записи LocalSystem.
Если этот параметр имеет значение NT AUTHORITY\LocalService, CreateService использует учетную запись LocalService. Если параметр имеет значение NT AUTHORITY\NetworkService, CreateService использует учетную запись NetworkService.
Общий процесс может выполняться от имени любого пользователя.
Если служба имеет тип SERVICE_KERNEL_DRIVER или SERVICE_FILE_SYSTEM_DRIVER, это имя объекта драйвера, которое система использует для загрузки драйвера устройства. Укажите значение NULL, если драйвер использует имя объекта по умолчанию, созданное системой ввода-вывода.
Службу можно настроить для использования управляемой учетной записи или виртуальной учетной записи. Если служба настроена для использования управляемой учетной записи службы, это имя управляемой учетной записи службы. Если служба настроена для использования виртуальной учетной записи, укажите имя NT SERVICE\ServiceName. Дополнительные сведения об управляемых учетных записях служб и виртуальных учетных записях см. в пошаговом руководстве по учетным записям служб.
Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Управляемые учетные записи служб и виртуальные учетные записи не поддерживаются до Windows 7 и Windows Server 2008 R2.
[in, optional] lpPassword
Пароль для имени учетной записи, указанной параметром lpServiceStartName . Укажите пустую строку, если у учетной записи нет пароля или если служба выполняется в учетной записи LocalService, NetworkService или LocalSystem. Дополнительные сведения см. в разделе Список записей служб.
Если имя учетной записи, указанное параметром lpServiceStartName , является именем управляемой учетной записи службы или виртуальной учетной записи, параметр lpPassword должен иметь значение NULL.
Пароли для служб драйверов игнорируются.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение является дескриптором для службы.
Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Диспетчер управления службами может задать следующие коды ошибок. Другие коды ошибок могут задаваться функциями реестра, которые вызываются диспетчером управления службами.
| Код возврата | Описание |
|---|---|
|
Дескриптор базы данных SCM не имеет права доступа к SC_MANAGER_CREATE_SERVICE . |
|
Указана циклическая зависимость службы. |
|
Отображаемое имя уже существует в базе данных диспетчера управления службами в качестве имени службы или другого отображаемого имени. |
|
Дескриптор указанной базы данных диспетчера управления службами недопустим. |
|
Указанное имя службы является недопустимым. |
|
Указан недопустимый параметр. |
|
Имя учетной записи пользователя, указанное в параметре lpServiceStartName , не существует. |
|
Указанная служба уже существует в этой базе данных. |
|
Указанная служба уже существует в этой базе данных и помечена для удаления. |
Комментарии
Функция CreateService создает объект службы и устанавливает его в базе данных диспетчера управления службами, создавая ключ с тем же именем, что и служба в следующем разделе реестра:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
Сведения, указанные в параметрах CreateService, ChangeServiceConfig и ChangeServiceConfig2 , сохраняются в качестве значений в этом ключе. Ниже приведены примеры значений, хранящихся для службы.
| Значение | Описание |
|---|---|
| DependOnGroup | Группы упорядочения нагрузки, от которых зависит эта служба, как указано в lpDependencies. |
| DependOnService | Службы, от которых зависит эта служба, как указано в lpDependencies. |
| Описание | Описание, указанное в ChangeServiceConfig2. |
| Отображаемое имя | Отображаемое имя, указанное в параметре lpDisplayName. |
| ErrorControl | Управление ошибками, заданное dwErrorControl. |
| FailureActions | Действия сбоя, указанные в ChangeServiceConfig2. |
| Группа | Группа упорядочения загрузки, указанная в lpLoadOrderGroup. Обратите внимание, что установка этого значения может переопределить значение DependOnService . |
| Imagepath | Имя двоичного файла, указанное в параметре lpBinaryPathName. |
| ObjectName | Имя учетной записи, указанное в параметре lpServiceStartName. |
| Запуск | Когда следует запускать службу, как указано в dwStartType. |
| Тег | Идентификатор тега, указанный lpdwTagId. |
| Тип | Тип службы, указанный параметром dwServiceType. |
Программы установки и сама служба могут создавать дополнительные подразделы для сведений, относящихся к службе.
Возвращенный дескриптор действителен только для процесса, который вызвал CreateService. Его можно закрыть, вызвав функцию CloseServiceHandle .
Если вы создаете службы, которые совместно используют процесс, избегайте вызова функций с эффектами для всего процесса, такими как ExitProcess. Кроме того, не выгружайте библиотеку DLL службы.
Примеры
Пример см. в разделе Установка службы.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winsvc.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
QueryServiceDynamicInformation
Пошаговое руководство по использованию учетных записей служб