Win32 API 日本語リファレンス
ホームSystem.Services › SERVICE_TRIGGER

SERVICE_TRIGGER

構造体
サイズx64: 32 バイト / x86: 20 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
dwTriggerTypeSERVICE_TRIGGER_TYPE4+0+0

トリガーイベントの種類です。このメンバーには次のいずれかの値を指定できます。

意味
SERVICE_TRIGGER_TYPE_CUSTOM
20
このイベントは、Event Tracing for Windows (ETW) プロバイダーによって生成されるカスタムイベントです。このトリガーイベントは、サービスの開始または停止に使用できます。

pTriggerSubtype メンバーは、イベントプロバイダーの GUID を指定します。

pDataItems メンバーは、プロバイダーが定義するトリガー固有のデータを指定します。

SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL
1
指定したデバイスインターフェイスクラスのデバイスが到着したとき、またはシステムの起動時にそのデバイスが存在する場合に、このイベントが発生します。このトリガーイベントは、一般にサービスの開始に使用されます。

pTriggerSubtype メンバーは、デバイスインターフェイスクラスの GUID を指定します。これらの GUID は、Windows Driver Kit (WDK) に付属するデバイス固有のヘッダーファイルで定義されています。

pDataItems メンバーは、デバイスインターフェイスクラスに対する 1 つ以上のハードウェア ID 文字列および互換 ID 文字列を指定します。文字列は Unicode でなければなりません。複数の文字列を指定した場合、そのいずれかが一致するとイベントが発生します。たとえば Wpdbusenum サービスは、デバイスインターフェイスクラス GUID_DEVINTERFACE_DISK {53f56307-b6bf-11d0-94f2-00a0c91efb8b} を持ち、ハードウェア ID 文字列が "USBSTOR\GenDisk" であるデバイスが到着したときに開始されます。

SERVICE_TRIGGER_TYPE_DOMAIN_JOIN
3
コンピューターがドメインに参加したとき、またはドメインから離脱したときに、このイベントが発生します。このトリガーイベントは、サービスの開始または停止に使用できます。

pTriggerSubtype メンバーは、DOMAIN_JOIN_GUID または DOMAIN_LEAVE_GUID を指定します。

pDataItems メンバーは使用されません。

SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT
4
ファイアウォールのポートが開かれたとき、またはファイアウォールのポートが閉じられてからおよそ 60 秒後に、このイベントが発生します。このトリガーイベントは、サービスの開始または停止に使用できます。

pTriggerSubtype メンバーは、FIREWALL_PORT_OPEN_GUID または FIREWALL_PORT_CLOSE_GUID を指定します。

pDataItems メンバーは、ポート、プロトコル、および省略可能な項目として、そのイベントを待ち受けるサービスの実行可能ファイルのパスとユーザー情報 (SID 文字列または名前) を指定します。ポートの代わりに "RPC" トークンを使用すると、RPC が使用する任意の待ち受けソケットを指定できます。実行可能ファイルのパスの代わりに "system" トークンを使用すると、Windows カーネルが作成して待ち受けるポートを指定できます。

イベントは、すべての文字列が一致した場合にのみ発生します。たとえば、MyServiceProcess.exe 内でホストされる MyService を UDP ポート 5001 が開いたときにトリガー開始する場合、トリガー固有のデータは "5001\0UDP\0%programfiles%\MyApplication\MyServiceProcess.exe\0MyService\0\0" の Unicode 表現になります。

Note このイベントを登録する前に、Base Filtering Engine (BFE) サービスおよびそれに依存するすべてのサービスを停止しておく必要があります。イベントの登録後は、BFE サービスとそれに依存するサービスを再開できます。詳細については、「解説」を参照してください。
SERVICE_TRIGGER_TYPE_GROUP_POLICY
5
コンピューターポリシーまたはユーザーポリシーの変更が発生したときに、このイベントが発生します。このトリガーイベントは、一般にサービスの開始に使用されます。

pTriggerSubtype メンバーは、MACHINE_POLICY_PRESENT_GUID または USER_POLICY_PRESENT_GUID を指定します。

pDataItems メンバーは使用されません。

SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY
2
TCP/IP ネットワークスタック上で最初の IP アドレスが利用可能になったとき、または最後の IP アドレスが利用できなくなったときに、このイベントが発生します。このトリガーイベントは、サービスの開始または停止に使用できます。

pTriggerSubtype メンバーは、NETWORK_MANAGER_FIRST_IP_ADDRESS_ARRIVAL_GUID または NETWORK_MANAGER_LAST_IP_ADDRESS_REMOVAL_GUID を指定します。

pDataItems メンバーは使用されません。

SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT
6
特定のネットワークプロトコルでパケットまたは要求が到着したときに、このイベントが発生します。この要求は、処理すべき作業がなくアイドルタイムアウトによって自身を停止したサービスを開始するために、一般に使用されます。

Windows 7 および Windows Server 2008 R2: このトリガーの種類は、Windows 8 および Windows Server 2012 までサポートされません。

pTriggerSubtype メンバーは、次のいずれかの値を指定します。RPC_INTERFACE_EVENT_GUID または NAMED_PIPE_EVENT_GUID です。

pDataItems メンバーは、エンドポイントまたはインターフェイスの GUID を指定します。文字列は Unicode でなければなりません。文字列が完全に一致した場合にイベントが発生します。

dwAction メンバーは SERVICE_TRIGGER_ACTION_SERVICE_START でなければなりません。

dwActionSERVICE_TRIGGER_ACTION4+4+4

指定したトリガーイベントが発生したときに実行するアクションです。このメンバーには次のいずれかの値を指定できます。

意味
SERVICE_TRIGGER_ACTION_SERVICE_START
1
指定したトリガーイベントが発生したときにサービスを開始します。
SERVICE_TRIGGER_ACTION_SERVICE_STOP
2
指定したトリガーイベントが発生したときにサービスを停止します。
pTriggerSubtypeGUID*8/4+8+8

トリガーイベントのサブタイプを識別する GUID を指すポインターです。このメンバーの値は、dwTriggerType メンバーの値によって異なります。

dwTriggerTypeSERVICE_TRIGGER_TYPE_CUSTOM の場合、pTriggerSubtype はカスタムイベントプロバイダーを識別する GUID です。

dwTriggerTypeSERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL の場合、pTriggerSubtype はデバイスインターフェイスクラスを識別する GUID です。

dwTriggerTypeSERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT の場合、pTriggerSubtype は次のいずれかの値になります。

意味
NAMED_PIPE_EVENT_GUID
1F81D131-3FAC-4537-9E0C-7E7B0C2F4B55
pDataItems で指定された名前付きパイプを開く要求が行われたときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT でなければなりません。dwAction メンバーは SERVICE_TRIGGER_ACTION_SERVICE_START でなければなりません。
RPC_INTERFACE_EVENT_GUID
BC90D167-9470-4139-A9BA-BE0BBBF5B74D
pDataItems で指定された RPC インターフェイス GUID に対するエンドポイント解決要求が到着したときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT でなければなりません。dwAction メンバーは SERVICE_TRIGGER_ACTION_SERVICE_START でなければなりません。

その他のトリガーイベントの種類では、pTriggerSubType は次のいずれかの値になります。

意味
DOMAIN_JOIN_GUID
1ce20aba-9851-4421-9430-1ddeb766e809
コンピューターがドメインに参加したときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_DOMAIN_JOIN でなければなりません。
DOMAIN_LEAVE_GUID
ddaf516e-58c2-4866-9574-c3b615d42ea1
コンピューターがドメインから離脱したときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_DOMAIN_JOIN でなければなりません。
FIREWALL_PORT_OPEN_GUID
b7569e07-8421-4ee0-ad10-86915afdad09
指定したファイアウォールのポートが開かれたときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT でなければなりません。
FIREWALL_PORT_CLOSE_GUID
a144ed38-8e12-4de4-9d96-e64740b1a524
指定したファイアウォールのポートが閉じられてからおよそ 60 秒後に、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT でなければなりません。
MACHINE_POLICY_PRESENT_GUID
659FCAE6-5BDB-4DA9-B1FF-CA2A178D46E0
コンピューターポリシーが変更されたときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_GROUP_POLICY でなければなりません。
NETWORK_MANAGER_FIRST_IP_ADDRESS_ARRIVAL_GUID
4f27f2de-14e2-430b-a549-7cd48cbc8245
TCP/IP ネットワークスタック上で最初の IP アドレスが利用可能になったときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY でなければなりません。
NETWORK_MANAGER_LAST_IP_ADDRESS_REMOVAL_GUID
cc4ba62a-162e-4648-847a-b6bdf993e335
TCP/IP ネットワークスタック上で最後の IP アドレスが利用できなくなったときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY でなければなりません。
USER_POLICY_PRESENT_GUID
54FB46C8-F089-464C-B1FD-59D1B62C3B50
ユーザーポリシーが変更されたときに、このイベントが発生します。dwTriggerType メンバーは SERVICE_TRIGGER_TYPE_GROUP_POLICY でなければなりません。
cDataItemsDWORD4+16+12

pDataItems が指す配列に含まれる SERVICE_TRIGGER_SPECIFIC_DATA_ITEM 構造体の数です。

このメンバーは、dwDataType メンバーが SERVICE_TRIGGER_TYPE_CUSTOM、SERVICE_TRIGGER_TYPE_DEVICE_ARRIVAL、SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT、または SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT の場合にのみ有効です。

pDataItemsSERVICE_TRIGGER_SPECIFIC_DATA_ITEM*8/4+24+16トリガー固有のデータを格納する SERVICE_TRIGGER_SPECIFIC_DATA_ITEM 構造体の配列へのポインターです。

公式ドキュメント

サービスのトリガーイベントを表します。この構造体は SERVICE_TRIGGER_INFO 構造体で使用されます。

解説(Remarks)

ドメインに参加しているシステムでは、セキュリティポリシーの設定によって BFE サービスおよびそれに依存するサービスを停止できなかったり、それらが自動的に再起動されたりすることがあります。この場合は、いったんサービスを無効にし、イベントの登録後に再度有効にする必要があります。これをプログラムから行うには、各サービスの元のスタートアップの種類を保存し、サービスのスタートアップの種類を SERVICE_DISABLED に変更してイベントを登録し、その後で元のスタートアップの種類に戻します。サービスのスタートアップの種類の変更については、ChangeServiceConfig を参照してください。

SC コマンドラインツールでサービスを無効にするには、sc config bfe start= disabled コマンドを使用して BFE サービスとそれに依存するサービスを無効にし、続いて net stop bfe /Y コマンドを使用してそれらを停止します。サービスを再度有効にするには、sc config bfe start= auto コマンドを使用します。SC コマンドラインツールの詳細については、Controlling a Service Using SC を参照してください。

サービスを無効にできない場合は、イベントを登録するサービスをインストールした後にシステムの再起動が必要になることがあります。この場合、システムを再起動する前に BFE サービスおよびそれに依存するサービスを無効にしないでください。これらのサービスが無効のままだと、システムが正しく動作しない可能性があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// SERVICE_TRIGGER  (x64 32 / x86 20 バイト)
typedef struct SERVICE_TRIGGER {
    SERVICE_TRIGGER_TYPE dwTriggerType;
    SERVICE_TRIGGER_ACTION dwAction;
    GUID* pTriggerSubtype;
    DWORD cDataItems;
    SERVICE_TRIGGER_SPECIFIC_DATA_ITEM* pDataItems;
} SERVICE_TRIGGER;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct SERVICE_TRIGGER
{
    public uint dwTriggerType;
    public uint dwAction;
    public IntPtr pTriggerSubtype;
    public uint cDataItems;
    public IntPtr pDataItems;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure SERVICE_TRIGGER
    Public dwTriggerType As UInteger
    Public dwAction As UInteger
    Public pTriggerSubtype As IntPtr
    Public cDataItems As UInteger
    Public pDataItems As IntPtr
End Structure
import ctypes
from ctypes import wintypes

class SERVICE_TRIGGER(ctypes.Structure):
    _fields_ = [
        ("dwTriggerType", wintypes.DWORD),
        ("dwAction", wintypes.DWORD),
        ("pTriggerSubtype", ctypes.c_void_p),
        ("cDataItems", wintypes.DWORD),
        ("pDataItems", ctypes.c_void_p),
    ]
#[repr(C)]
pub struct SERVICE_TRIGGER {
    pub dwTriggerType: u32,
    pub dwAction: u32,
    pub pTriggerSubtype: *mut core::ffi::c_void,
    pub cDataItems: u32,
    pub pDataItems: *mut core::ffi::c_void,
}
import "golang.org/x/sys/windows"

type SERVICE_TRIGGER struct {
	dwTriggerType uint32
	dwAction uint32
	pTriggerSubtype uintptr
	cDataItems uint32
	pDataItems uintptr
}
type
  SERVICE_TRIGGER = record
    dwTriggerType: DWORD;
    dwAction: DWORD;
    pTriggerSubtype: Pointer;
    cDataItems: DWORD;
    pDataItems: Pointer;
  end;
const SERVICE_TRIGGER = extern struct {
    dwTriggerType: u32,
    dwAction: u32,
    pTriggerSubtype: ?*anyopaque,
    cDataItems: u32,
    pDataItems: ?*anyopaque,
};
type
  SERVICE_TRIGGER {.bycopy.} = object
    dwTriggerType: uint32
    dwAction: uint32
    pTriggerSubtype: pointer
    cDataItems: uint32
    pDataItems: pointer
struct SERVICE_TRIGGER
{
    uint dwTriggerType;
    uint dwAction;
    void* pTriggerSubtype;
    uint cDataItems;
    void* pDataItems;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; SERVICE_TRIGGER サイズ: 20 バイト(x86)
dim st, 5    ; 4byte整数×5(構造体サイズ 20 / 4 切り上げ)
; dwTriggerType : SERVICE_TRIGGER_TYPE (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; dwAction : SERVICE_TRIGGER_ACTION (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; pTriggerSubtype : GUID* (+8, 4byte)  varptr(st)+8 を基点に操作(4byte:入れ子/配列)
; cDataItems : DWORD (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; pDataItems : SERVICE_TRIGGER_SPECIFIC_DATA_ITEM* (+16, 4byte)  varptr(st)+16 を基点に操作(4byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; SERVICE_TRIGGER サイズ: 32 バイト(x64)
dim st, 8    ; 4byte整数×8(構造体サイズ 32 / 4 切り上げ)
; dwTriggerType : SERVICE_TRIGGER_TYPE (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; dwAction : SERVICE_TRIGGER_ACTION (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; pTriggerSubtype : GUID* (+8, 8byte)  varptr(st)+8 を基点に操作(8byte:入れ子/配列)
; cDataItems : DWORD (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; pDataItems : SERVICE_TRIGGER_SPECIFIC_DATA_ITEM* (+24, 8byte)  varptr(st)+24 を基点に操作(8byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global SERVICE_TRIGGER
    #field int dwTriggerType
    #field int dwAction
    #field intptr pTriggerSubtype
    #field int cDataItems
    #field intptr pDataItems
#endstruct

stdim st, SERVICE_TRIGGER        ; NSTRUCT 変数を確保
st->dwTriggerType = 100
mes "dwTriggerType=" + st->dwTriggerType