Функция CreateService

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

Синтаксис

SC_HANDLE CreateService(
  SC_HANDLE hSCManager,
  LPCTSTR lpServiceName,
  LPCTSTR lpDisplayName,
  DWORD dwDesiredAccess,
  DWORD dwServiceType,
  DWORD dwStartType,
  DWORD dwErrorControl,
  LPCTSTR lpBinaryPathName,
  LPCTSTR lpLoadOrderGroup,
  LPDWORD lpdwTagId,
  LPCTSTR lpDependencies,
  LPCTSTR lpServiceStartName,
  LPCTSTR lpPassword
);

Параметры

hSCManager

[in] Дескриптор базы данных диспетчера управления службой. Этот дескриптор возвращается функцией OpenSCManager и должен иметь право доступа SC_MANAGER_CREATE_SERVICE. Дополнительную информацию смотри в статье Защита службы и права доступа.

lpServiceName

[in] Указатель на строку с завершающим нулем, которая задает устанавливаемое имя службы. Максимальная длина строки - 256 символов. База данных диспетчера управления службами сохраняет регистр символов, но при сравнении имени службы - всегда без учета регистра. Прямой слэш (/) и обратный слэш (\) - неприменяемые символы в имени службы.

lpDisplayName

[in] Указатель на строку с завершающим нулем, которая имеет в своем составе отображаемое имя, которое используется пользовательскими программами интерфейса, чтобы идентифицировать службу. Эта строка имеет максимальную длину 256 символов. Имя сохраняется с учетом регистра в диспетчере управления службами. Сравнения отображаемого имени всегда не чувствительны к регистру.

dwDesiredAccess

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

dwServiceType

[in] Типы службы. Этот параметр может быть одним из следующих значений.

Тип	Предназначение
SERVICE_FILE_SYSTEM_DRIVER	Сервисный драйвер файловой системы.
SERVICE_KERNEL_DRIVER	Сервисный драйвер.
SERVICE_WIN32_OWN_PROCESS	Служба, которая запускается в своем собственном процессе.
SERVICE_WIN32_SHARE_PROCESS	Служба, которая совместно использует процесс с одной или несколькими другими службами. Дополнительную информацию смотри в статье Сервисные программы.

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

Тип	Предназначение
SERVICE_INTERACTIVE_PROCESS	Служба может взаимодействовать с рабочим столом. Дополнительную информацию смотри в статье Диалоговые службы.

dwStartType

[in] Варианты запуска службы. Этот параметр может быть одним из следующих значений.

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

dwErrorControl

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

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

lpBinaryPathName

[in] Указатель на строку с завершающим нулем, которая имеет в своем составе полный путь доступа к двоичному файлу службы. Если путь имеет в своем составе пробел, он должен быть заключен в кавычки так, чтобы правильно понимался. Например, "d:\\my share\\myservice.exe" должен быть определен как "\" d:\\my share\\myservice.exe" "".

Путь может также включать в себя и параметры для автозапуска службы. Например, "d:\\myshare\\ myservice.exe arg1 arg2". Эти параметры передаются в точке входа службы (обычно это функция main).

lpLoadOrderGroup

[in] Указатель на строку с завершающим нулем, именующую группу очередности загрузки, членом которой является эта служба. Задайте значение ПУСТО (NULL) или пустую строку, если служба не принадлежит группе.

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

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder

lpdwTagId

[out] Указатель на переменную, которая получает значение признака, являющееся уникальным в группе, заданной в параметре lpLoadOrderGroup. Задайте значение ПУСТО (NULL), если Вы не изменяете существующий признак.

Вы можете использовать признак для того, чтобы упорядочить запуск службы в пределах очередности загрузки группы, определяя вектор очередности признака в следующем значении реестра:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList

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

lpDependencies

[in] Указатель на массив имен служб, разделенных нулем, с двойным символом нуля в конце или очередности загрузки групп, которую система должна запустить перед этой службой. Задайте значение ПУСТО (NULL) или пустую строку, если служба не имеет никаких зависимостей. Зависимость от группы означает, что эта служба может запуститься тогда, если по крайней мере один член группы запущен после попытки запустить все члены группы.

Вы должны ставить в начале имен группы SC_GROUP_IDENTIFIER так, чтобы они могли отличаться от имени службы, потому что службы и группы служб совместно используют то же самое пространство имен.

lpServiceStartName

[in] Указатель на строку с завершающим нулем, которая задает имя учетной записи, под которой должна запуститься служба. Если тип службы - SERVICE_WIN32_OWN_PROCESS, используйте имя учетной записи в форме DomainName\UserName. Процесс службы начнет работу как этот пользователь. Если учетная запись принадлежит встроенному домену, Вы можете задать .\UserName.

Если этот параметр - значение ПУСТО (NULL), функция CreateService использует учетную запись LocalSystem. Если тип службы задан - SERVICE_INTERACTIVE_PROCESS, служба должна запуститься в учетной записи LocalSystem.

Если этот параметр - NT AUTHORITY\LocalService, функция CreateService использует учетную запись LocalService. Если параметр - NT AUTHORITY\NetworkService, CreateService использует учетную запись NetworkService.

Windows NT: Если тип службы - SERVICE_WIN32_SHARE_PROCESS, Вы должны задать учетную запись LocalSystem. На более поздних версиях Windows, совместно используемый процесс может запуститься как любой пользователь.

Если тип службы - SERVICE_KERNEL_DRIVER или SERVICE_FILE_SYSTEM_DRIVER, ее имя - имя объекта драйвера, который система использует, чтобы загрузить драйвер устройства. Задайте значение ПУСТО (NULL), если драйвер должен использовать имя объекта по умолчанию, созданное системой ввода / вывода (I/O).

lpPassword

[in] Указатель на строку с завершающим нулем, которая имеет в своем составе пароль к имени учетной записи, заданному параметром lpServiceStartName. Задайте пустую строку, если учетная запись не имеет пароля или, если служба запускается в учетной записи LocalService, NetworkService или LocalSystem. Дополнительную информацию смотри в статье Список сервисных записей.

Для служб драйвера пароли игнорируются .

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

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

Если функция завершается ошибкой, возвращаемое значение - значение ПУСТО (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	Указанная служба уже существует в этой базе данных.

Замечания

Функция CreateService создает объект службы и устанавливает его в базу данных диспетчера управления службами, создавая ключ с тем же самым именем, что и служба, в следующем ключе реестра:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services

Информация, определяемая CreateService, ChangeServiceConfig и ChangeServiceConfig2 сохраняется как значения под этим ключом. Ниже - примеры значений, сохраненных для службы.

Значение	Описание
DependOnGroup	Очередность загрузки групп, от которой эта служба зависит, как задано параметром lpDependencies.
DependOnService	Службы, от которых эта служба зависит, как задано параметром lpDependencies.
Description	Набор признаков, определяемых функцией ChangeServiceConfig2.
DisplayName	Отображаемое имя, заданное параметром lpDisplayName.
ErrorControl	Защита от ошибок, заданная параметром dwErrorControl.
FailureActions	Действия сбоя, заданные функцией ChangeServiceConfig2.
Group	Очередность загрузки группы, заданная параметром lpLoadOrderGroup. Обратите внимание! на то, что такая установка этого значения может отвергнуть установку значения DependOnService.
ImagePath	Имя двоичного файла, как задано параметром lpBinaryPathName.
ObjectName	Имя учетной записи, заданное параметром lpServiceStartName.
Start	Когда запускать службу, как задано параметром dwStartType.
Tag	Идентификатор признака, заданный параметром lpdwTagId.
Type	Тип службы, заданный параметром dwServiceType.

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

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

Если Вы создаете службы, которые совместно используют процесс, избегайте вызывать функции с воздействиями на весь процесс, типа ExitProcess. Кроме того, не выгружайте вашу DLL службы.

Демонстрационный код

Пример смотри в статье Установка службы.

Смотри также

Обзор Службы, Функции, используемые службами, ChangeServiceConfig, ChangeServiceConfig2, CloseServiceHandle, ControlService, DeleteService, EnumDependentServices, OpenSCManager, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatusEx, SetServiceObjectSecurity, StartService

Размещение и совместимость CreateService
К	Windows XP	Да
л	Windows 2000 Professional	Да
и	Windows NT Workstation	Да
е	Windows Me	Нет
н	Windows 98	Нет
т	Windows 95	Нет

С	Windows Server 2003	Да
е	Windows 2000 Server	Да
р	Windows NT Server	Да
в
е
р
Используемая библиотека		Advapi32.lib
Используемая DLL		advapi32.dll
Заголовочный файл
- объявлено в		Winsvc.h
- включено в		Windows.h
Unicode		Реализуется как CreateServiceW (Unicode) и CreateServiceA (ANSI).
Замечания по платформе		Не имеется

Назад в оглавление

На главную страницу

В оглавление справки