CreateServiceA 函数 (winsvc.h)

项目
03/04/2024

创建服务对象并将其添加到指定的服务控制管理器数据库。

语法

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 访问权限。有关详细信息，请参阅服务安全性和访问权限。

[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	该服务可以与桌面交互。有关详细信息，请参阅 Interactive Services。

[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 终止数组的指针，系统必须在此服务之前启动这些名称。如果服务没有依赖项，请指定 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，则名称是系统用于加载设备驱动程序的驱动程序对象名称。如果驱动程序要使用 I/O 系统创建的默认对象名称，请指定 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 指定的说明。
DisplayName	由 lpDisplayName 指定的显示名称。
ErrorControl	dwErrorControl 指定的错误控制。
FailureActions	ChangeServiceConfig2 指定的失败操作。
组	由 lpLoadOrderGroup 指定的加载排序组。请注意，设置此值可以替代 DependOnService 值的设置。
ImagePath	二进制文件的名称，由 lpBinaryPathName 指定。
ObjectName	由 lpServiceStartName 指定的帐户名称。
启动	何时启动服务，由 dwStartType 指定。
标记	由 lpdwTagId 指定的标记标识符。
类型	由 dwServiceType 指定的服务类型。

安装程序和服务本身可以为特定于服务的信息创建其他子项。

返回的句柄仅对调用 CreateService 的进程有效。可以通过调用 CloseServiceHandle 函数将其关闭。

如果要创建共享进程的服务，请避免调用具有进程范围效果的函数，例如 ExitProcess。此外，请勿卸载服务 DLL。

示例

有关示例，请参阅安装服务。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	winsvc.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll