SERVICE_TRIGGER structure (winsvc.h)
Represents a service trigger event. This structure is used by the SERVICE_TRIGGER_INFO structure.
Syntax
typedef struct _SERVICE_TRIGGER {
DWORD dwTriggerType;
DWORD dwAction;
GUID *pTriggerSubtype;
DWORD cDataItems;
PSERVICE_TRIGGER_SPECIFIC_DATA_ITEM pDataItems;
} SERVICE_TRIGGER, *PSERVICE_TRIGGER;
Members
dwTriggerType
The trigger event type. This member can be one of the following values.
| Value | Meaning |
|---|---|
|
The event is a custom event generated by an Event Tracing for Windows (ETW) provider. This trigger event can be used to start or stop a service.
The pTriggerSubtype member specifies the event provider's GUID. The pDataItems member specifies trigger-specific data defined by the provider. |
|
The event is triggered when a device of the specified device interface class arrives or is present when the system starts. This trigger event is commonly used to start a service.
The pTriggerSubtype member specifies the device interface class GUID. These GUIDs are defined in device-specific header files provided with the Windows Driver Kit (WDK). The pDataItems member specifies one or more hardware ID and compatible ID strings for the device interface class. Strings must be Unicode. If more than one string is specified, the event is triggered if any one of the strings match. For example, the Wpdbusenum service is started when a device of device interface class GUID_DEVINTERFACE_DISK {53f56307-b6bf-11d0-94f2-00a0c91efb8b} and a hardware ID string of |
|
The event is triggered when the computer joins or leaves a domain. This trigger event can be used to start or stop a service.
The pTriggerSubtype member specifies DOMAIN_JOIN_GUID or DOMAIN_LEAVE_GUID. The pDataItems member is not used. |
|
The event is triggered when a firewall port is opened or approximately 60 seconds after the firewall port is closed. This trigger event can be used to start or stop a service.
The pTriggerSubtype member specifies FIREWALL_PORT_OPEN_GUID or FIREWALL_PORT_CLOSE_GUID. The pDataItems member specifies the port, the protocol, and optionally the executable path and user information (SID string or name) of the service listening on the event. The "RPC" token can be used in place of the port to specify any listening socket used by RPC. The "system" token can be used in place of the executable path to specify ports created by and listened on by the Windows kernel. The event is triggered only if all strings match. For example, if MyService hosted inside MyServiceProcess.exe is to be trigger-started when port UDP 5001 opens, the trigger-specific data would be the Unicode representation of Note Before this event can be registered, the Base Filtering Engine (BFE) service and all services that depend on it must be stopped. After the event is registered, the BFE service and services that depend on it can be restarted. For more information, see Remarks.
|
|
The event is triggered when a machine policy or user policy change occurs. This trigger event is commonly used to start a service.
The pTriggerSubtype member specifies MACHINE_POLICY_PRESENT_GUID or USER_POLICY_PRESENT_GUID. The pDataItems member is not used. |
|
The event is triggered when the first IP address on the TCP/IP networking stack becomes available or the last IP address on the stack becomes unavailable. This trigger event can be used to start or stop a service.
The pTriggerSubtype member specifies NETWORK_MANAGER_FIRST_IP_ADDRESS_ARRIVAL_GUID or NETWORK_MANAGER_LAST_IP_ADDRESS_REMOVAL_GUID. The pDataItems member is not used. |
|
The event is triggered when a packet or request arrives on a particular network protocol. This request is commonly used to start a service that has stopped itself after an idle time-out when there is no work to do.
Windows 7 and Windows Server 2008 R2: This trigger type is not supported until Windows 8 and Windows Server 2012. The pTriggerSubtype member specifies one of the following values: RPC_INTERFACE_EVENT_GUID or NAMED_PIPE_EVENT_GUID. The pDataItems member specifies an endpoint or interface GUID. The string must be Unicode. The event triggers if the string is an exact match. The dwAction member must be SERVICE_TRIGGER_ACTION_SERVICE_START. |
dwAction
The action to take when the specified trigger event occurs. This member can be one of the following values.
pTriggerSubtype
Points to a GUID that identifies the trigger event subtype. The value of this member depends on the value of the dwTriggerType member.
If dwTriggerType is SERVICE_TRIGGER_TYPE_CUSTOM, pTriggerSubtype is the GUID that identifies the custom event provider.
If dwTriggerType is SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL, pTriggerSubtype is the GUID that identifies the device interface class.
If dwTriggerType is SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT, pTriggerSubtype is one of the following values.
For other trigger event types, pTriggerSubType can be one of the following values.
cDataItems
The number of SERVICE_TRIGGER_SPECIFIC_DATA_ITEM structures in the array pointed to by pDataItems.
This member is valid only if the dwDataType member is SERVICE_TRIGGER_TYPE_CUSTOM, SERVICE_TRIGGER_TYPE_DEVICE_ARRIVAL, SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT, or SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT.
pDataItems
A pointer to an array of SERVICE_TRIGGER_SPECIFIC_DATA_ITEM structures that contain trigger-specific data.
Remarks
On a system that is joined to a domain, security policy settings may prevent the BFE service and its dependent services from being stopped or cause them to restart automatically. In this case, it is necessary to disable the services and then re-enable them after the event is registered. To do this programmatically, store each service's original start type, change the service start type to SERVICE_DISABLED, register the event, and then restore the service's original start type. For information about changing a service's start type, see ChangeServiceConfig.
To disable the services using the SC command-line tool, use the command sc config bfe start= disabled to disable the BFE service and its dependent services, then use the command net stop bfe /Y to stop them. To re-enable the services, use the command sc config bfe start= auto. For more information about the SC command-line tool, see Controlling a Service Using SC.
If it is not possible to disable the services, it may be necessary to restart the system after installing the service that is registering the event. In this case, do not disable the BFE service and its dependent services before restarting the system, because the system may not work correctly if these services remain disabled.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Header | winsvc.h |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for