CreateServiceA 函式 (winsvc.h)

發行項
03/13/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	服務可以與桌面互動。如需詳細資訊，請參閱互動式服務。

[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，請使用 DomainName\UserName 格式的帳戶名稱。服務進程將會以此使用者身分登入。如果帳戶屬於內建網域，您可以指定 .\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。

服務控制管理員可以設定下列錯誤碼。服務控制管理員呼叫的登錄函式可以設定其他錯誤碼。

傳回碼	Description
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 所指定的資訊會儲存為此機碼下的值。以下是針對服務儲存的值範例。

值	Description
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)
程式庫	Advapi32.lib
Dll	Advapi32.dll