Export (0) Print
Expand All

SERVICE_TRIGGER structure

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.

ValueMeaning
SERVICE_TRIGGER_TYPE_CUSTOM
20

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.

SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL
1

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 "USBSTOR\GenDisk" arrives.

SERVICE_TRIGGER_TYPE_DOMAIN_JOIN
3

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.

SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT
4

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 "5001\0UDP\0%programfiles%\MyApplication\MyServiceProcess.exe\0MyService\0\0".

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.

SERVICE_TRIGGER_TYPE_GROUP_POLICY
5

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.

SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY
2

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.

SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT
6

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, NAMED_PIPE_EVENT_GUID, TCP_PORT_EVENT_GUID, or UDP_EVENT_PORT_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.

ValueMeaning
SERVICE_TRIGGER_ACTION_SERVICE_START
1

Start the service when the specified trigger event occurs.

SERVICE_TRIGGER_ACTION_SERVICE_STOP
2

Stop the service when the specified trigger event occurs.

 

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.

ValueMeaning
NAMED_PIPE_EVENT_GUID
1F81D131-3FAC-4537-9E0C-7E7B0C2F4B55

The event is triggered when a request is made to open the named pipe specified by pDataItems. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT. The dwAction member must be SERVICE_TRIGGER_ACTION_SERVICE_START.

RPC_INTERFACE_EVENT_GUID
BC90D167-9470-4139-A9BA-BE0BBBF5B74D

The event is triggered when an endpoint resolution request arrives for the RPC interface GUID specified by pDataItems. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT. The dwAction member must be SERVICE_TRIGGER_ACTION_SERVICE_START.

 

For other trigger event types, pTriggerSubType can be one of the following values.

ValueMeaning
DOMAIN_JOIN_GUID
1ce20aba-9851-4421-9430-1ddeb766e809

The event is triggered when the computer joins a domain. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_DOMAIN_JOIN.

DOMAIN_LEAVE_GUID
ddaf516e-58c2-4866-9574-c3b615d42ea1

The event is triggered when the computer leaves a domain. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_DOMAIN_JOIN.

FIREWALL_PORT_OPEN_GUID
b7569e07-8421-4ee0-ad10-86915afdad09

The event is triggered when the specified firewall port is opened. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT.

FIREWALL_PORT_CLOSE_GUID
a144ed38-8e12-4de4-9d96-e64740b1a524

The event is triggered approximately 60 seconds after the specified firewall port is closed. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT.

MACHINE_POLICY_PRESENT_GUID
659FCAE6-5BDB-4DA9-B1FF-CA2A178D46E0

The event is triggered when the machine policy has changed. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_GROUP_POLICY.

NETWORK_MANAGER_FIRST_IP_ADDRESS_ARRIVAL_GUID
4f27f2de-14e2-430b-a549-7cd48cbc8245

The event is triggered when the first IP address on the TCP/IP networking stack becomes available. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY.

NETWORK_MANAGER_LAST_IP_ADDRESS_REMOVAL_GUID
cc4ba62a-162e-4648-847a-b6bdf993e335

The event is triggered when the last IP address on the TCP/IP networking stack becomes unavailable. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY.

USER_POLICY_PRESENT_GUID
54FB46C8-F089-464C-B1FD-59D1B62C3B50

The event is triggered when the user policy has changed. The dwTriggerType member must be SERVICE_TRIGGER_TYPE_GROUP_POLICY.

 

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

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winsvc.h

See also

ChangeServiceConfig2
QueryServiceConfig2
Service Trigger Events
SERVICE_TRIGGER_INFO
SERVICE_TRIGGER_SPECIFIC_DATA_ITEM

 

 

Community Additions

ADD
Show:
© 2014 Microsoft