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 アクセス権が必要です。 詳細については、「 サービス セキュリティとアクセス権」を参照してください。
[in] lpServiceName
インストールするサービスの名前。 文字列の最大長は 256 文字です。 サービス 制御マネージャー データベースでは文字の大文字と小文字が保持されますが、サービス名の比較では常に大文字と小文字が区別されません。 スラッシュ (/) と円記号 (\) は有効なサービス名文字ではありません。
[in, optional] lpDisplayName
ユーザー・インターフェース・プログラムがサービスを識別するために使用する表示名。 この文字列の長さは最大 256 文字です。 名前は、サービス コントロール マネージャーで大文字と小文字が保持されます。 表示名の比較では、常に大文字と小文字が区別されません。
[in] dwDesiredAccess
サービスへのアクセス。 要求されたアクセスを許可する前に、システムは呼び出し元プロセスのアクセス トークンを確認します。 値の一覧については、「 サービス セキュリティとアクセス権」を参照してください。
[in] dwServiceType
サービスの型。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 意味 |
|---|---|
|
予約済み。 |
|
ファイル システム ドライバー サービス。 |
|
ドライバー サービス。 |
|
予約済み。 |
|
独自のプロセスで実行されるサービス。 |
|
1 つ以上の他のサービスとプロセスを共有するサービス。 詳細については、「 サービス プログラム」を参照してください。 |
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" などです。 これらの引数は、サービス エントリ ポイント (通常は メイン 関数) に渡されます。
別のコンピューターでパスを指定する場合は、リモート呼び出しで使用されるセキュリティ コンテキストであるため、ローカル コンピューターのコンピューター アカウントから共有にアクセスできる必要があります。 ただし、この要件により、リモート コンピューターの潜在的な脆弱性がローカル コンピューターに影響を与える可能性があります。 そのため、ローカル ファイルを使用することをお勧めします。
[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 または空の文字列を指定します。 グループへの依存関係があるサービスとは、グループのすべてのメンバーを起動しようとした際、そのグループの少なくとも 1 つのメンバーが実行されないと、このサービスを実行できないことを意味します。
サービスとサービス グループは同じ名前空間を共有するため、サービス名と区別できるように、グループ名の前に 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 を呼び出します。
次のエラー コードは、サービス コントロール マネージャーによって設定できます。 その他のエラー コードは、サービス コントロール マネージャーによって呼び出されるレジストリ関数によって設定できます。
| リターン コード | 説明 |
|---|---|
|
SCM データベースへのハンドルには、 SC_MANAGER_CREATE_SERVICE アクセス権がありません。 |
|
循環サービスの依存関係が指定されました。 |
|
表示名は、サービス名または別の表示名として、サービス制御マネージャー・データベースに既に存在します。 |
|
指定されたサービス コントロール マネージャー データベースへのハンドルが無効です。 |
|
指定されたサービス名が無効です。 |
|
指定されたパラメーターが無効です。 |
|
lpServiceStartName パラメーターで指定されたユーザー アカウント名が存在しません。 |
|
指定されたサービスは、このデータベースに既に存在します。 |
|
指定されたサービスはこのデータベースに既に存在し、削除対象としてマークされています。 |
注釈
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 で指定されたアカウント名。 |
| Start | dwStartType で指定されたサービスを開始するタイミング。 |
| Tag | lpdwTagId で指定されたタグ識別子。 |
| Type | dwServiceType で指定されたサービスの種類。 |
セットアップ プログラムとサービス自体は、サービス固有の情報の追加のサブキーを作成できます。
返されるハンドルは、 CreateService を呼び出したプロセスに対してのみ有効です。 CloseServiceHandle 関数を呼び出すことで閉じることができます。
プロセスを共有するサービスを作成する場合は、 ExitProcess などのプロセス全体の効果を持つ関数を呼び出さないようにします。 さらに、サービス DLL をアンロードしないでください。
例
例については、「 サービスのインストール」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | winsvc.h (Windows.h を含む) |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |