struttura SERVICE_TRIGGER (winsvc.h)

Articolo
08/27/2023

Rappresenta un evento trigger del servizio. Questa struttura viene utilizzata dalla struttura SERVICE_TRIGGER_INFO .

Sintassi

typedef struct _SERVICE_TRIGGER {
  DWORD                               dwTriggerType;
  DWORD                               dwAction;
  GUID                                *pTriggerSubtype;
  DWORD                               cDataItems;
  PSERVICE_TRIGGER_SPECIFIC_DATA_ITEM pDataItems;
} SERVICE_TRIGGER, *PSERVICE_TRIGGER;

Members

dwTriggerType

Tipo di evento trigger. Questo membro può essere uno dei valori seguenti.

Valore	Significato
SERVICE_TRIGGER_TYPE_CUSTOM 20	L'evento è un evento personalizzato generato da un provider ETW (Event Tracing for Windows ). Questo evento trigger può essere usato per avviare o arrestare un servizio. Il membro pTriggerSubtype specifica il GUID del provider di eventi. Il membro pDataItems specifica i dati specifici del trigger definiti dal provider.
SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL 1	L'evento viene attivato quando un dispositivo della classe di interfaccia del dispositivo specificata arriva o è presente all'avvio del sistema. Questo evento trigger viene comunemente usato per avviare un servizio. Il membro pTriggerSubtype specifica il GUID della classe dell'interfaccia del dispositivo. Questi GUID sono definiti nei file di intestazione specifici del dispositivo forniti con Windows Driver Kit (WDK). Il membro pDataItems specifica uno o più ID hardware e stringhe ID compatibili per la classe dell'interfaccia del dispositivo. Le stringhe devono essere Unicode. Se viene specificata più di una stringa, l'evento viene attivato se una delle stringhe corrisponde. Ad esempio, il servizio Wpdbusenum viene avviato quando un dispositivo della classe di interfaccia del dispositivo GUID_DEVINTERFACE_DISK {53f56307-b6bf-11d0-94f2-00a0c91efb8b} e una stringa ID hardware di `"USBSTOR\GenDisk"` arrivo.
SERVICE_TRIGGER_TYPE_DOMAIN_JOIN 3	L'evento viene attivato quando il computer viene aggiunto o lascia un dominio. Questo evento trigger può essere usato per avviare o arrestare un servizio. Il membro pTriggerSubtype specifica DOMAIN_JOIN_GUID o DOMAIN_LEAVE_GUID. Il membro pDataItems non viene utilizzato.
SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT 4	L'evento viene attivato quando viene aperta una porta del firewall o circa 60 secondi dopo la chiusura della porta del firewall. Questo evento trigger può essere usato per avviare o arrestare un servizio. Il membro pTriggerSubtype specifica FIREWALL_PORT_OPEN_GUID o FIREWALL_PORT_CLOSE_GUID. Il membro pDataItems specifica la porta, il protocollo e, facoltativamente, il percorso eseguibile e le informazioni utente (stringa o nome SID) del servizio in ascolto sull'evento. Il token "RPC" può essere usato al posto della porta per specificare qualsiasi socket di ascolto usato da RPC. Il token "system" può essere usato al posto del percorso eseguibile per specificare le porte create da e in ascolto dal kernel di Windows. L'evento viene attivato solo se tutte le stringhe corrispondono. Ad esempio, se MyService ospitato all'interno di MyServiceProcess.exe deve essere attivato all'apertura della porta UDP 5001, i dati specifici del trigger saranno la rappresentazione Unicode di `"5001\0UDP\0%programfiles%\MyApplication\MyServiceProcess.exe\0MyService\0\0"`. Nota Prima di poter registrare questo evento, è necessario arrestare il servizio BFE (Base Filtering Engine) e tutti i servizi che dipendono da esso. Dopo la registrazione dell'evento, è possibile riavviare il servizio BFE e i servizi che dipendono da esso. Per altre informazioni, vedere la sezione Osservazioni.
SERVICE_TRIGGER_TYPE_GROUP_POLICY 5	L'evento viene attivato quando si verifica una modifica dei criteri del computer o dei criteri utente. Questo evento trigger viene comunemente usato per avviare un servizio. Il membro pTriggerSubtype specifica MACHINE_POLICY_PRESENT_GUID o USER_POLICY_PRESENT_GUID. Il membro pDataItems non viene utilizzato.
SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY 2	L'evento viene attivato quando il primo indirizzo IP nello stack di rete TCP/IP diventa disponibile o l'ultimo indirizzo IP nello stack diventa non disponibile. Questo evento trigger può essere usato per avviare o arrestare un servizio. Il membro pTriggerSubtype specifica NETWORK_MANAGER_FIRST_IP_ADDRESS_ARRIVAL_GUID o NETWORK_MANAGER_LAST_IP_ADDRESS_REMOVAL_GUID. Il membro pDataItems non viene utilizzato.
SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT 6	L'evento viene attivato quando arriva un pacchetto o una richiesta in un determinato protocollo di rete. Questa richiesta viene comunemente usata per avviare un servizio che si è arrestato dopo un timeout di inattività quando non è necessario eseguire alcuna operazione. Windows 7 e Windows Server 2008 R2: Questo tipo di trigger non è supportato fino a Windows 8 e Windows Server 2012. Il membro pTriggerSubtype specifica uno dei valori seguenti: RPC_INTERFACE_EVENT_GUID o NAMED_PIPE_EVENT_GUID. Il membro pDataItems specifica un GUID dell'endpoint o dell'interfaccia. La stringa deve essere Unicode. L'evento viene attivato se la stringa è una corrispondenza esatta. Il membro dwAction deve essere SERVICE_TRIGGER_ACTION_SERVICE_START.

dwAction

Azione da eseguire quando si verifica l'evento trigger specificato. Questo membro può essere uno dei valori seguenti.

Valore	Significato
SERVICE_TRIGGER_ACTION_SERVICE_START 1	Avviare il servizio quando si verifica l'evento trigger specificato.
SERVICE_TRIGGER_ACTION_SERVICE_STOP 2	Arrestare il servizio quando si verifica l'evento trigger specificato.

pTriggerSubtype

Punta a un GUID che identifica il sottotipo di evento trigger. Il valore di questo membro dipende dal valore del membro dwTriggerType .

Se dwTriggerType è SERVICE_TRIGGER_TYPE_CUSTOM, pTriggerSubtype è il GUID che identifica il provider di eventi personalizzato.

Se dwTriggerType è SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL, pTriggerSubtype è il GUID che identifica la classe dell'interfaccia del dispositivo.

Se dwTriggerType è SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT, pTriggerSubtype è uno dei valori seguenti.

Valore	Significato
NAMED_PIPE_EVENT_GUID 1F81D131-3FAC-4537-9E0C-7E7B0C2F4B55	L'evento viene attivato quando viene effettuata una richiesta per aprire la named pipe specificata da pDataItems. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT. Il membro dwAction deve essere SERVICE_TRIGGER_ACTION_SERVICE_START.
RPC_INTERFACE_EVENT_GUID BC90D167-9470-4139-A9BA-BE0BBBF5B74D	L'evento viene attivato quando arriva una richiesta di risoluzione dell'endpoint per il GUID dell'interfaccia RPC specificato da pDataItems. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT. Il membro dwAction deve essere SERVICE_TRIGGER_ACTION_SERVICE_START.

Per altri tipi di evento trigger, pTriggerSubType può essere uno dei valori seguenti.

Valore	Significato
DOMAIN_JOIN_GUID 1ce20aba-9851-4421-9430-1ddeb766e809	L'evento viene attivato quando il computer viene aggiunto a un dominio. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_DOMAIN_JOIN.
DOMAIN_LEAVE_GUID ddaf516e-58c2-4866-9574-c3b615d42ea1	L'evento viene attivato quando il computer lascia un dominio. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_DOMAIN_JOIN.
FIREWALL_PORT_OPEN_GUID b7569e07-8421-4ee0-ad10-86915afdad09	L'evento viene attivato all'apertura della porta del firewall specificata. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT.
FIREWALL_PORT_CLOSE_GUID a144ed38-8e12-4de4-9d96-e64740b1a524	L'evento viene attivato circa 60 secondi dopo la chiusura della porta del firewall specificata. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT.
MACHINE_POLICY_PRESENT_GUID 659FCAE6-5BDB-4DA9-B1FF-CA2A178D46E0	L'evento viene attivato quando i criteri del computer sono stati modificati. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_GROUP_POLICY.
NETWORK_MANAGER_FIRST_IP_ADDRESS_ARRIVAL_GUID 4f27f2de-14e2-430b-a549-7cd48cbc8245	L'evento viene attivato quando diventa disponibile il primo indirizzo IP nello stack di rete TCP/IP. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY.
NETWORK_MANAGER_LAST_IP_ADDRESS_REMOVAL_GUID cc4ba62a-162e-4648-847a-b6bdf993e335	L'evento viene attivato quando l'ultimo indirizzo IP nello stack di rete TCP/IP diventa non disponibile. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_IP_ADDRESS_AVAILABILITY.
USER_POLICY_PRESENT_GUID 54FB46C8-F089-464C-B1FD-59D1B62C3B50	L'evento viene attivato quando i criteri utente sono stati modificati. Il membro dwTriggerType deve essere SERVICE_TRIGGER_TYPE_GROUP_POLICY.

cDataItems

Numero di strutture SERVICE_TRIGGER_SPECIFIC_DATA_ITEM nella matrice a cui punta pDataItems.

Questo membro è valido solo se il membro dwDataType è SERVICE_TRIGGER_TYPE_CUSTOM, SERVICE_TRIGGER_TYPE_DEVICE_ARRIVAL, SERVICE_TRIGGER_TYPE_FIREWALL_PORT_EVENT o SERVICE_TRIGGER_TYPE_NETWORK_ENDPOINT.

pDataItems

Puntatore a una matrice di strutture SERVICE_TRIGGER_SPECIFIC_DATA_ITEM che contengono dati specifici del trigger.

Commenti

In un sistema aggiunto a un dominio, le impostazioni dei criteri di sicurezza possono impedire che il servizio BFE e i servizi dipendenti vengano arrestati o che vengano riavviati automaticamente. In questo caso, è necessario disabilitare i servizi e quindi riabilitarli dopo la registrazione dell'evento. A tale scopo, archiviare il tipo di avvio originale di ogni servizio a livello di codice, modificare il tipo di avvio del servizio in SERVICE_DISABLED, registrare l'evento e quindi ripristinare il tipo di avvio originale del servizio. Per informazioni sulla modifica del tipo di avvio di un servizio, vedere ChangeServiceConfig.

Per disabilitare i servizi usando lo strumento da riga di comando SC, usare il comando sc config bfe start= disabilitato per disabilitare il servizio BFE e i relativi servizi dipendenti, quindi usare il comando net stop bfe /Y per arrestarli. Per riabilitare i servizi, usare il comando sc config bfe start= auto. Per altre informazioni sullo strumento da riga di comando SC, vedere Controllo di un servizio tramite SC.

Se non è possibile disabilitare i servizi, potrebbe essere necessario riavviare il sistema dopo l'installazione del servizio che registra l'evento. In questo caso, non disabilitare il servizio BFE e i relativi servizi dipendenti prima di riavviare il sistema, perché il sistema potrebbe non funzionare correttamente se questi servizi rimangono disabilitati.