Поделиться через


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

Создает объект службы и добавляет его в указанную базу данных диспетчера управления службами.

Синтаксис

SC_HANDLE CreateServiceA(
  [in]            SC_HANDLE hSCManager,
  [in]            LPCSTR    lpServiceName,
  [in, optional]  LPCSTR    lpDisplayName,
  [in]            DWORD     dwDesiredAccess,
  [in]            DWORD     dwServiceType,
  [in]            DWORD     dwStartType,
  [in]            DWORD     dwErrorControl,
  [in, optional]  LPCSTR    lpBinaryPathName,
  [in, optional]  LPCSTR    lpLoadOrderGroup,
  [out, optional] LPDWORD   lpdwTagId,
  [in, optional]  LPCSTR    lpDependencies,
  [in, optional]  LPCSTR    lpServiceStartName,
  [in, optional]  LPCSTR    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_ADAPTER
0x00000004
Зарезервировано.
SERVICE_FILE_SYSTEM_DRIVER
0x00000002
Служба драйвера файловой системы.
SERVICE_KERNEL_DRIVER
0x00000001
Служба драйверов.
SERVICE_RECOGNIZER_DRIVER
0x00000008
Зарезервировано.
SERVICE_WIN32_OWN_PROCESS
0x00000010
Служба, которая выполняется в собственном процессе.
SERVICE_WIN32_SHARE_PROCESS
0x00000020
Служба, которая совместно использует процесс с одной или несколькими другими службами. Дополнительные сведения см. в разделе Служебные программы.
 

Если вы указываете SERVICE_WIN32_OWN_PROCESS или SERVICE_WIN32_SHARE_PROCESS, а служба выполняется в контексте учетной записи LocalSystem, можно также указать следующее значение.

Значение Значение
SERVICE_INTERACTIVE_PROCESS
0x00000100
Служба может взаимодействовать с рабочим столом.

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

[in] dwStartType

Параметры запуска службы. Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
SERVICE_AUTO_START
0x00000002
Служба автоматически запускается диспетчером управления службами во время запуска системы. Дополнительные сведения см. в разделе Автоматический запуск служб.
SERVICE_BOOT_START
0x00000000
Драйвер устройства, запущенный системным загрузчиком. Это значение допустимо только для служб драйверов.
SERVICE_DEMAND_START
0x00000003
Служба, запущенная диспетчером управления службами, когда процесс вызывает функцию StartService . Дополнительные сведения см. в разделе Запуск служб по запросу.
SERVICE_DISABLED
0x00000004
Служба, которая не может быть запущена. Попытки запустить службу приводят к ERROR_SERVICE_DISABLED кода ошибки.
SERVICE_SYSTEM_START
0x00000001
Драйвер устройства, запущенный функцией IoInitSystem . Это значение допустимо только для служб драйверов.

[in] dwErrorControl

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

Значение Значение
SERVICE_ERROR_CRITICAL
0x00000003
Программа запуска регистрирует ошибку в журнале событий, если это возможно. Если запускается последняя известная конфигурация, операция запуска завершается ошибкой. В противном случае система перезапускается с последней известной хорошей конфигурацией.
SERVICE_ERROR_IGNORE
0x00000000
Программа запуска игнорирует ошибку и продолжает операцию запуска.
SERVICE_ERROR_NORMAL
0x00000001
Программа запуска регистрирует ошибку в журнале событий, но продолжает операцию запуска.
SERVICE_ERROR_SEVERE
0x00000002
Программа запуска регистрирует ошибку в журнале событий. Если запускается последняя известная конфигурация, операция запуска продолжается. В противном случае система перезапускается с последней известной хорошей конфигурацией.

[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.

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

Код возврата Описание
ERROR_ACCESS_DENIED
Дескриптор базы данных SCM не имеет права доступа к SC_MANAGER_CREATE_SERVICE .
ERROR_CIRCULAR_DEPENDENCY
Указана циклическая зависимость службы.
ERROR_DUPLICATE_SERVICE_NAME
Отображаемое имя уже существует в базе данных диспетчера управления службами в качестве имени службы или другого отображаемого имени.
ERROR_INVALID_HANDLE
Дескриптор указанной базы данных диспетчера управления службами недопустим.
ERROR_INVALID_NAME
Указанное имя службы является недопустимым.
ERROR_INVALID_PARAMETER
Указан недопустимый параметр.
ERROR_INVALID_SERVICE_ACCOUNT
Имя учетной записи пользователя, указанное в параметре lpServiceStartName , не существует.
ERROR_SERVICE_EXISTS
Указанная служба уже существует в этой базе данных.
ERROR_SERVICE_MARKED_FOR_DELETE
Указанная служба уже существует в этой базе данных и помечена для удаления.

Комментарии

Функция 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

См. также раздел

ChangeServiceConfig

ChangeServiceConfig2

CloseServiceHandle

ControlService

DeleteService

EnumDependentServices

OpenSCManager

QueryServiceConfig

QueryServiceDynamicInformation

QueryServiceObjectSecurity

QueryServiceStatusEx

Пошаговое руководство по использованию учетных записей служб

Функции службы

Установка, удаление и перечисление службы

SetServiceObjectSecurity

StartService