Funzione EvtSubscribe (winevt.h)
Crea una sottoscrizione che riceverà eventi correnti e futuri da un canale o un file di log che corrispondono ai criteri di query specificati.
Sintassi
EVT_HANDLE EvtSubscribe(
[in] EVT_HANDLE Session,
[in] HANDLE SignalEvent,
[in] LPCWSTR ChannelPath,
[in] LPCWSTR Query,
[in] EVT_HANDLE Bookmark,
[in] PVOID Context,
[in] EVT_SUBSCRIBE_CALLBACK Callback,
[in] DWORD Flags
);
Parametri
[in] Session
Handle di sessione remoto restituito dalla funzione EvtOpenSession . Impostare su NULL per sottoscrivere eventi nel computer locale.
[in] SignalEvent
Handle a un oggetto evento che il servizio segnalerà quando sono disponibili nuovi eventi che corrispondono ai criteri di query. Questo parametro deve essere NULL se il parametro Callback non è NULL.
[in] ChannelPath
Nome del canale Amministrazione o operativo che contiene gli eventi da sottoscrivere (non è possibile sottoscrivere canali analitici o debug). Il percorso è obbligatorio se il parametro Query contiene una query XPath; il percorso viene ignorato se il parametro Query contiene una query XML strutturata.
[in] Query
Query che specifica i tipi di eventi che si desidera che il servizio di sottoscrizione restituisca. È possibile specificare una query XPath 1.0 o una query XML strutturata. Se XPath contiene più di 20 espressioni, usare una query XML strutturata. Per ricevere tutti gli eventi, impostare questo parametro su NULL o "*".
[in] Bookmark
Handle a un segnalibro che identifica il punto iniziale per la sottoscrizione. Per ottenere un handle di segnalibro, chiamare la funzione EvtCreateBookmark . È necessario impostare questo parametro se il parametro Flags contiene il flag EvtSubscribeStartAfterBookmark; in caso contrario, NULL.
[in] Context
Valore di contesto definito dal chiamante che il servizio sottoscrizione passerà al callback specificato ogni volta che restituisce un evento.
[in] Callback
Puntatore alla funzione di callback EVT_SUBSCRIBE_CALLBACK che riceverà gli eventi della sottoscrizione. Questo parametro deve essere NULL se il parametro SignalEvent non è NULL.
[in] Flags
Uno o più flag che specificano quando avviare la sottoscrizione agli eventi. Ad esempio, se si specifica EvtSubscribeStartAtOldestRecord, il servizio recupera tutti gli eventi correnti e futuri che corrispondono ai criteri di query; tuttavia, se si specifica EvtSubscribeToFutureEvents, il servizio restituisce solo eventi futuri che corrispondono ai criteri di query. Per i valori possibili, vedere l'enumerazione EVT_SUBSCRIBE_FLAGS .
Valore restituito
Handle per la sottoscrizione se ha esito positivo; in caso contrario, NULL. Se la funzione restituisce NULL, chiamare la funzione GetLastError per ottenere il codice di errore. È necessario chiamare la funzione EvtClose con l'handle della sottoscrizione al termine.
Commenti
Per annullare la sottoscrizione, passare l'handle di sottoscrizione restituito alla funzione EvtClose .
Esistono due modelli di sottoscrizione: il modello di polling e il modello push. Nel modello push si implementa un callback della sottoscrizione e si imposta il parametro Callback sull'implementazione. Il servizio chiamerà il callback per ogni evento corrispondente ai criteri di query o se si verifica un errore.
Nel modello di polling si crea un oggetto evento che segnala il servizio. Quando viene segnalato, si chiama la funzione EvtNext usando l'handle della sottoscrizione per enumerare gli eventi. È necessario chiamare la funzione EvtClose in ogni evento enumerato. È quindi possibile reimpostare l'oggetto e attendere che il servizio segnali di nuovo. Questo processo viene ripetuto fino a quando non si annulla la sottoscrizione.
Esempio
Per un esempio che illustra come usare questa funzione, vedere Sottoscrizione agli eventi.
Requisiti
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winevt.h |
| Libreria | Wevtapi.lib |
| DLL | Wevtapi.dll |